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 ()=default
	Construct an empty controller.
	~Controller ()
	Destroy the controller.
	ENABLE_DEFAULT_MOVE_DISABLE_COPY (Controller)
	Move is allowed, copy is disabled.
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)
	Remove a node by id.
bool	removeNode (std::string_view name)
	Remove a node by name.
bool	hasNode (Core::Node::Id id) const
	Check whether a node id exists.
bool	hasNode (std::string_view name) const
	Check whether a node name exists.
bool	hasNodeType (std::string_view type) const
	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).
Core::Channel::Id	addChannel (Core::OutputPort &src, Core::InputPort &dst, std::vector< std::string > *errors=nullptr, std::size_t errorLimit=0)
	Create a channel between an output and an input port.
bool	removeChannel (Core::Channel::Id id)
	Remove a channel by id.
bool	hasChannel (Core::Channel::Id id) const
	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).
NodeFactory &	nodeFactory () noexcept
	Access the node factory used to create nodes.
NodeFactory const &	nodeFactory () const noexcept
	Access the node factory used to create nodes.
bool	isChannelVerificationEnabled () const noexcept
	Whether channel verification is enabled.
void	setChannelVerification (bool enabled)
	Enable/disable channel verification.
void	registerHook (Hooks::Graph *hook)
	Register a graph hook.
void	deregisterHook (Hooks::Graph *hook)
	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

Channels are created as Core::SPSCChannel instances and are registered on both ports Channel ids are allocated through a Utils::RecyclableIdAllocator as well.

Channel verification (mime-type compatibility)

By default, channel creation is verified (setChannelVerification() and Graph channel verification (kind + mime-type compatibility)). Verification rejects connections that are incompatible by:

• port kind mismatch (input/output kind),
• mime-type incompatibilities, including propagation constraints.

The verification logic is intentionally conservative: when ports declare any mime-type, the controller can infer possible mime-types by walking existing connections and applying propagation rules (node-level and port-level).

When verification fails:

• if an errors vector is provided to addChannel(), it is filled and the call returns {}.
• otherwise, errors are logged and an exception is thrown.

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 ( )

default

Construct an empty controller.

~Controller()

dfx::Graph::Controller::~Controller

(

)

Destroy the controller.

Member Function Documentation

addChannel()

Core::Channel::Id dfx::Graph::Controller::addChannel	(	Core::OutputPort &	src,
		Core::InputPort &	dst,
		std::vector< std::string > *	errors = nullptr,
		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::SPSCChannel is created,
• the channel is registered into both ports,
• hooks are notified via Hooks::Graph::onChannelCreated().

Parameters

src	Source output port.
dst	Destination input port.
errors	Optional output list of human-readable validation errors.
errorLimit	Optional cap on number of collected errors (0 = no limit).

Returns

New channel id on success, or {} on validation failure when errors is provided.

Exceptions

dfx::Utils::Exception

if validation fails and errors is null (errors are logged then an exception is thrown), or if channel construction fails for any reason.

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).

deregisterHook()

void dfx::Graph::Controller::deregisterHook

(

Hooks::Graph *

hook

)

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

Parameters

hook	Hook instance to remove.

ENABLE_DEFAULT_MOVE_DISABLE_COPY()

dfx::Graph::Controller::ENABLE_DEFAULT_MOVE_DISABLE_COPY

(

Controller

)

Move is allowed, copy is disabled.

hasChannel()

bool dfx::Graph::Controller::hasChannel

(

Core::Channel::Id

id

)

const

Check whether a channel id exists.

hasNode() [1/2]

bool dfx::Graph::Controller::hasNode

(

Core::Node::Id

id

)

const

Check whether a node id exists.

hasNode() [2/2]

bool dfx::Graph::Controller::hasNode

(

std::string_view

name

)

const

Check whether a node name exists.

hasNodeType()

bool dfx::Graph::Controller::hasNodeType

(

std::string_view

type

)

const

Check whether a node type is known by the factory.

isChannelVerificationEnabled()

bool dfx::Graph::Controller::isChannelVerificationEnabled ( ) const

inlinenoexcept

Whether channel verification is enabled.

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

)

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

)

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

)

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.

setChannelVerification()

void dfx::Graph::Controller::setChannelVerification ( bool enabled )

inline

Enable/disable channel verification.

When disabled, addChannel() skips compatibility checks entirely. This is mainly intended for debugging or for scenarios where compatibility is enforced elsewhere.

See also

Graph channel verification (kind + mime-type compatibility)

---

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

• lib/dfx-graph/Controller.hpp