dfx::Graph::Controller Class Reference

In-memory graph builder and mutation controller (nodes + channels) with optional connection verification. More...

#include <dfx-graph/Controller.hpp>

Public Member Functions
	Controller (NodeFactory &nodeFactory, TransportFactory &transportFactory)
	Construct an empty controller.
	~Controller ()=default
	Destroy the controller.
	DFX_DISABLE_COPY_AND_MOVE (Controller)
	Move and copy are disallowed.
Node
Core::Node::Id	addNode (std::string_view type, std::string_view name, nlohmann::json config={})
	Add a node and allocate a fresh node id.
Core::Node::Id	addNode (Core::Node::Id id, std::string_view type, std::string_view name, nlohmann::json config={})
	Add a node using a specific id.
bool	removeNode (Core::Node::Id id) noexcept
	Remove a node by id.
bool	removeNode (std::string_view name) noexcept
	Remove a node by name.
bool	hasNode (Core::Node::Id id) const noexcept
	Check whether a node id exists.
bool	hasNode (std::string_view name) const noexcept
	Check whether a node name exists.
bool	hasNodeType (std::string_view type) const noexcept
	Check whether a node type is known by the factory.
std::vector< std::string >	allNodeType () const
	List all node types known by the factory.
std::vector< std::string >	allNodeName () const
	List all node names currently in the graph.
std::vector< Core::Node::Id >	allNodeId () const
	List all node ids currently in the graph.
Core::NodePtr	node (Core::Node::Id id) const
	Get a node by id.
Core::NodePtr	node (std::string_view name) const
	Get a node by name.
std::vector< Core::NodePtr >	nodes () const
	Return all nodes currently in the graph (strong pointers).
Channel
Core::Channel::Id	addChannel (std::string_view src, std::string_view dst, nlohmann::json srcConfig={}, nlohmann::json dstConfig={}, std::size_t errorLimit=0)
	Create a channel between an output and an input port.
Core::Channel::Id	addChannel (Core::Endpoint::Descriptor src, Core::Endpoint::Descriptor dst, nlohmann::json srcConfig={}, nlohmann::json dstConfig={}, std::size_t errorLimit=0)
	Create a channel between an output and an input port.
bool	removeChannel (Core::Channel::Id id) noexcept
	Remove a channel by id.
bool	hasChannel (Core::Channel::Id id) const noexcept
	Check whether a channel id exists.
std::vector< Core::Channel::Id >	allChannelId () const
	List all channel ids currently in the graph.
Core::ChannelPtr	channel (Core::Channel::Id id) const
	Get a channel by id.
std::vector< Core::ChannelPtr >	channels () const
	Return all channels currently in the graph (strong pointers).
Factory and validator
NodeFactory &	nodeFactory () noexcept
	Access the node factory used to create nodes.
NodeFactory const &	nodeFactory () const noexcept
	Access the node factory used to create nodes.
TransportFactory &	transportFactory () noexcept
	Access the transport factory used to create dfx::Core::Transport.
TransportFactory const &	transportFactory () const noexcept
	Access the transport factory used to create dfx::Core::Transport.
ConnectionValidator &	connectionValidator () noexcept
	Access the connection validator used to verify connections between ports.
ConnectionValidator const &	connectionValidator () const noexcept
	Access the connection validator used to verify connections between ports.
Hook
void	registerHook (Hooks::Graph *hook)
	Register a graph hook.
void	deregisterHook (Hooks::Graph *hook) noexcept
	Deregister a previously registered hook (no-op if not present).

Detailed Description

In-memory graph builder and mutation controller (nodes + channels) with optional connection verification.

Controller owns the editable state of a dfx graph:

• the set of nodes currently present in the graph,
• the set of channels connecting node ports,
• id allocation for nodes and channels,
• and the node factory used to instantiate nodes by type.

This is the central mutation API used to construct graphs from configuration files, and to apply runtime modifications (add/remove nodes, add/remove channels).

Node creation

Nodes are created through NodeFactory (by type) and are stored by id. Node ids are allocated through a Utils::RecyclableIdAllocator so ids can be reused after removal.

Node names must be unique and are validated via Core::Node::validateNodeName().

Channel creation

Channel transports are created through TransportFactory (by scheme) and are assigned to each endpoint of the channel. For local endpoint, the channel is given to its associated port.

Hooks

The controller can notify observers through Hooks::Graph callbacks:

• Hooks::Graph::onNodeCreated / onNodeRemoved
• Hooks::Graph::onChannelCreated / onChannelRemoved

Hooks are invoked with a "safe invoke" wrapper so one misbehaving hook does not break graph operations.

Warning

Removing a node also removes all channels connected to any of its input/output ports to prevent half-connected channels from remaining in the graph.

Constructor & Destructor Documentation

Controller()

dfx::Graph::Controller::Controller	(	NodeFactory &	nodeFactory,
		TransportFactory &	transportFactory )

Construct an empty controller.

~Controller()

dfx::Graph::Controller::~Controller ( )

default

Destroy the controller.

Member Function Documentation

addChannel() [1/2]

Core::Channel::Id dfx::Graph::Controller::addChannel	(	Core::Endpoint::Descriptor	src,
		Core::Endpoint::Descriptor	dst,
		nlohmann::json	srcConfig = {},
		nlohmann::json	dstConfig = {},
		std::size_t	errorLimit = 0 )

Create a channel between an output and an input port.

When verification is enabled (default), the controller validates compatibility. See Graph channel verification (kind + mime-type compatibility) for more information.

On success:

• a Core::Channel is created,
• hooks are notified via Hooks::Graph::onChannelCreated().

Parameters

src	Source transport definition.
dst	Destination transport definition.
srcConfig	Additional source transport configuration.
dstConfig	Additional destination transport configuration.
errorLimit	Optional cap on number of collected errors (0 = no limit).

Returns

New channel id on success, or throws dfx::Utils::Exception on error.

addChannel() [2/2]

Core::Channel::Id dfx::Graph::Controller::addChannel	(	std::string_view	src,
		std::string_view	dst,
		nlohmann::json	srcConfig = {},
		nlohmann::json	dstConfig = {},
		std::size_t	errorLimit = 0 )

Create a channel between an output and an input port.

When verification is enabled (default), the controller validates compatibility. See Graph channel verification (kind + mime-type compatibility) for more information.

On success:

• a Core::Channel is created,
• hooks are notified via Hooks::Graph::onChannelCreated().

Parameters

src	Source transport definition.
dst	Destination transport definition.
srcConfig	Additional source transport configuration.
dstConfig	Additional destination transport configuration.
errorLimit	Optional cap on number of collected errors (0 = no limit).

Returns

New channel id on success, or throws dfx::Utils::Exception on error.

addNode() [1/2]

Core::Node::Id dfx::Graph::Controller::addNode	(	Core::Node::Id	id,
		std::string_view	type,
		std::string_view	name,
		nlohmann::json	config = {} )

Add a node using a specific id.

Reserves id in the allocator before creation. If creation fails, the id is released. This overload is mainly intended for graph loading / replay where ids are already known.

Parameters

id	Desired node id.
type	Node type name (resolved by NodeFactory).
name	Unique node name.
config	Optional node configuration blob (passed to the factory).

Returns

The node id (same as id).

addNode() [2/2]

Core::Node::Id dfx::Graph::Controller::addNode	(	std::string_view	type,
		std::string_view	name,
		nlohmann::json	config = {} )

Add a node and allocate a fresh node id.

If creation fails, the allocated id is released back to the allocator so it will be reused for the next node. On success, hooks are notified via Hooks::Graph::onNodeCreated().

Parameters

type	Node type name (resolved by NodeFactory).
name	Unique node name.
config	Optional node configuration blob (passed to the factory).

Returns

The allocated node id.

allChannelId()

std::vector< Core::Channel::Id > dfx::Graph::Controller::allChannelId

(

)

const

List all channel ids currently in the graph.

allNodeId()

std::vector< Core::Node::Id > dfx::Graph::Controller::allNodeId

(

)

const

List all node ids currently in the graph.

allNodeName()

std::vector< std::string > dfx::Graph::Controller::allNodeName

(

)

const

List all node names currently in the graph.

allNodeType()

std::vector< std::string > dfx::Graph::Controller::allNodeType

(

)

const

List all node types known by the factory.

channel()

Core::ChannelPtr dfx::Graph::Controller::channel

(

Core::Channel::Id

id

)

const

Get a channel by id.

Exceptions

dfx::Utils::Exception

If the id does not exist.

channels()

std::vector< Core::ChannelPtr > dfx::Graph::Controller::channels

(

)

const

Return all channels currently in the graph (strong pointers).

connectionValidator() [1/2]

ConnectionValidator const & dfx::Graph::Controller::connectionValidator ( ) const

inlinenoexcept

Access the connection validator used to verify connections between ports.

connectionValidator() [2/2]

ConnectionValidator & dfx::Graph::Controller::connectionValidator ( )

inlinenoexcept

Access the connection validator used to verify connections between ports.

deregisterHook()

void dfx::Graph::Controller::deregisterHook ( Hooks::Graph * hook )

noexcept

Deregister a previously registered hook (no-op if not present).

Parameters

hook	Hook instance to remove.

DFX_DISABLE_COPY_AND_MOVE()

dfx::Graph::Controller::DFX_DISABLE_COPY_AND_MOVE

(

Controller

)

Move and copy are disallowed.

hasChannel()

bool dfx::Graph::Controller::hasChannel ( Core::Channel::Id id ) const

noexcept

Check whether a channel id exists.

hasNode() [1/2]

bool dfx::Graph::Controller::hasNode ( Core::Node::Id id ) const

noexcept

Check whether a node id exists.

hasNode() [2/2]

bool dfx::Graph::Controller::hasNode ( std::string_view name ) const

noexcept

Check whether a node name exists.

hasNodeType()

bool dfx::Graph::Controller::hasNodeType ( std::string_view type ) const

noexcept

Check whether a node type is known by the factory.

node() [1/2]

Core::NodePtr dfx::Graph::Controller::node

(

Core::Node::Id

id

)

const

Get a node by id.

Exceptions

dfx::Utils::Exception

If the id does not exist.

node() [2/2]

Core::NodePtr dfx::Graph::Controller::node

(

std::string_view

name

)

const

Get a node by name.

Exceptions

dfx::Utils::Exception

If the name does not exist.

nodeFactory() [1/2]

NodeFactory const & dfx::Graph::Controller::nodeFactory ( ) const

inlinenoexcept

Access the node factory used to create nodes.

nodeFactory() [2/2]

NodeFactory & dfx::Graph::Controller::nodeFactory ( )

inlinenoexcept

Access the node factory used to create nodes.

nodes()

std::vector< Core::NodePtr > dfx::Graph::Controller::nodes

(

)

const

Return all nodes currently in the graph (strong pointers).

registerHook()

void dfx::Graph::Controller::registerHook

(

Hooks::Graph *

hook

)

Register a graph hook.

The same hook pointer is not added twice.

Parameters

hook	Hook instance (must not be null).

removeChannel()

bool dfx::Graph::Controller::removeChannel ( Core::Channel::Id id )

noexcept

Remove a channel by id.

On success:

• hooks are notified via Hooks::Graph::onChannelRemoved(),
• the channel is detached from both ports,
• the id is released to the allocator.

Parameters

id	Channel id.

Returns

True if the channel existed and was removed, false otherwise.

removeNode() [1/2]

bool dfx::Graph::Controller::removeNode ( Core::Node::Id id )

noexcept

Remove a node by id.

Also removes all channels connected to the node before erasing it, to prevent dangling connections. Hooks are notified via Hooks::Graph::onNodeRemoved() and Hooks::Graph::onChannelRemoved().

Parameters

id

Node id.

Returns

True if the node existed and was removed, false otherwise.

removeNode() [2/2]

bool dfx::Graph::Controller::removeNode ( std::string_view name )

noexcept

Remove a node by name.

Same semantics as removeNode(Core::Node::Id).

Parameters

name	Node name.

Returns

True if the node existed and was removed, false otherwise.

transportFactory() [1/2]

TransportFactory const & dfx::Graph::Controller::transportFactory ( ) const

inlinenoexcept

Access the transport factory used to create dfx::Core::Transport.

transportFactory() [2/2]

TransportFactory & dfx::Graph::Controller::transportFactory ( )

inlinenoexcept

Access the transport factory used to create dfx::Core::Transport.

---

The documentation for this class was generated from the following file:

• lib/dfx-graph/Controller.hpp