Abstract base class for all nodes in the dfx runtime. More...

#include <dfx-core/Node.hpp>

Inheritance diagram for dfx::Core::Node:

Collaboration diagram for dfx::Core::Node:

Public Types
enum class	ExecutionFlowPolicy { AlwaysDispatch , InlineIfAvailable }
	Policy controlling how execution is chained after message delivery. More...
using	Id = uint32_t
	Node identifier type (unique and stable within a graph instance).

Public Member Functions
	Node (std::string type, Id id, std::string name)
	Construct a node instance.
virtual	~Node ()=0
	Virtual destructor. Pure virtual to ensure Node is abstract, but defined out-of-line.
void	setName (std::string newName)
	Rename the node.
template<DerivedFromNode T>
bool	is () const noexcept
	Check whether this node is of a given derived type.
template<DerivedFromNode T>
T &	as () noexcept
	Cast this node to a derived type (unchecked).
template<DerivedFromNode T>
T const &	as () const noexcept
	Cast this node to a derived type (unchecked).
Introspection
std::string const &	type () const noexcept
	Get the node type.
std::string const &	name () const noexcept
	Get the node name.
Id	id () const noexcept
	Get the node id.
nlohmann::json const &	config () const noexcept
	Get the node configuration.
ExecutionFlowPolicy	executionFlowPolicy () const noexcept
	Get the node execution policy.
bool	isRunning () const noexcept
	Check of the node is currently running.
bool	allowsMimeTypePropagation () const noexcept
	Whether this node allows mime-type propagation through its ports.
Lifecycle
void	start ()
	Start the node.
void	stop ()
	Stop the node.
void	waitForStopped ()
	Block the current thread until the node is stopped.
bool	stopRequested () const noexcept
	Check if stop has already been called or not.
Ports
InputPortContainer const &	inputPorts () const noexcept
	Get all input ports of all Kind.
OutputPortContainer const &	outputPorts () const noexcept
	Get all output ports of all Kind.
bool	hasInputPort (std::string_view portName) const noexcept
	Check whether an input port exists by name.
bool	hasOutputPort (std::string_view portName) const noexcept
	Check whether an output port exists by name.
bool	hasInputPort (Port::Id id) const noexcept
	Check whether an input port exists by id.
bool	hasOutputPort (Port::Id id) const noexcept
	Check whether an output port exists by id.
InputPort const &	inputPort (std::string_view portName) const
	Get an input port by name.
OutputPort const &	outputPort (std::string_view portName) const
	Get an output port by name.
InputPort &	inputPort (std::string_view portName)
	Get an input port by name (mutable).
OutputPort &	outputPort (std::string_view portName)
	Get an output port by name (mutable).
InputPort const &	inputPort (Port::Id id) const
	Get an input port by id.
OutputPort const &	outputPort (Port::Id id) const
	Get an output port by id.
InputPort &	inputPort (Port::Id id)
	Get an input port by id (mutable).
OutputPort &	outputPort (Port::Id id)
	Get an output port by id (mutable).
Sending messages
void	sendMessage (Port::Id id, MessagePtr message)
	Send a message on an output port by id.
void	sendMessage (std::string_view portName, MessagePtr message)
	Send a message on an output port by name.
void	sendMessage (OutputPort &port, MessagePtr message)
	Send a message on the provided output port.
Lockable interface
void	lock ()
	Lock the node's internal recursive mutex.
void	unlock ()
	Unlock the node's internal recursive mutex.
bool	try_lock () noexcept
	Try to lock the node's internal recursive mutex.
Metadata
virtual nlohmann::json	configSchema () const =0
	Return the JSON schema describing the node configuration. Used by the dfx::Graph::NodeFactory / tooling / UI to validate and edit configuration.
virtual nlohmann::json	metadata () const =0
	Return node metadata (description, categories, ports, etc.). Intended for UI/tooling and discovery.

Static Public Member Functions
static void	validateNodeName (std::string_view name)
	Validate a node name.

Protected Member Functions
void	initialize (nlohmann::json config)
	Initialize the node with its configuration.
void	setAllowsMimeTypePropagation (bool allowed)
	Enable/disable global mime-type propagation for this node. This affects how the runtime may propagate mime types through connected ports.
virtual void	setExecutionFlowPolicy (ExecutionFlowPolicy policy)
	Set the execution flow policy used by the runtime scheduler.
virtual void	handleMessage (InputPort const &port, MessagePtr message)=0
	Handle an incoming message on an input port.
Lifecycle hooks for derived classes
virtual void	startImpl ()
	Called by start before the node is marked running.
virtual void	stopImpl ()
	Called by stop before the node is marked stopped.
virtual void	initializeImpl (nlohmann::json config)=0
	Called by initialize; derived nodes must parse `config` here.
void	onNodeStopped ()
	Must be called by classes that re-implement the stopImpl function.
Port registration helpers (for derived classes)
OutputPort &	registerOutputPort (std::string name, MimeType mimeType=MimeType::Any, std::optional< bool > allowsMimeTypePropagation=std::nullopt)
	Register a data output port.
InputPort &	registerInputPort (std::string name, MimeTypes supportedMimeTypes={}, std::optional< bool > allowsMimeTypePropagation=std::nullopt)
	Register a data input port.
OutputPort &	registerControlOutputPort (std::string name)
	Register a control output port.
InputPort &	registerControlInputPort (std::string name)
	Register a control input port.

Friends
class	Graph::NodeFactory
class	InputPort

Runtime integration
void	setReactor (Runtime::Api::NodeReactor *reactor)
	Attach the runtime reactor used by this node.
Runtime::Api::NodeReactor *	reactor () const noexcept
	Get the currently attached reactor (may be null if not set).
FdWatch::Poller &	poller ()
	Access a poller instance associated with this node.
template<typename T = Runtime::Api::NodeTaskExecutor>
T *	customExecutor () const noexcept
	Access the customer executor of this node if any.
void	assignTaskExecutor (Runtime::Api::NodeTaskExecutorPtr executor)
	Assigns a custom task executor to this node.
void	revokeTaskExecutor () noexcept
	Revokes a custom task executor, returning this node to the default execution model.

Detailed Description

Abstract base class for all nodes in the dfx runtime.

Ownership and lifetime: Nodes are intended to be managed through NodePtr and created by a factory (e.g. dfx::Graph::NodeFactory). The node inherits from std::enable_shared_from_this and some operations require the node to already be owned by a shared_ptr.

Threading: The class exposes a lockable interface (lock, unlock, try_lock) backed by an internal recursive mutex. This enables patterns like:
std::lock_guard lock(node);

dfx::Core::Node::lock
void lock()
Lock the node's internal recursive mutex.
Definition Node.hpp:315

Thread-safety of higher-level operations still depends on the rest of the runtime (reactor/poller and port/message delivery).

See also: DFX_NODE

Member Typedef Documentation

◆ Id

using dfx::Core::Node::Id = uint32_t

Node identifier type (unique and stable within a graph instance).

Member Enumeration Documentation

◆ ExecutionFlowPolicy

enum class dfx::Core::Node::ExecutionFlowPolicy

strong

Policy controlling how execution is chained after message delivery.

This value is read by the runtime to decide whether the next node execution should be enqueued or can run inline on the current thread.

See also: dfx::Runtime::Scheduler

Enumerator
AlwaysDispatch	Always enqueue next task for deferred execution.
InlineIfAvailable	Run inline on the current thread when possible.

Constructor & Destructor Documentation

◆ Node()

dfx::Core::Node::Node	(	std::string	type,
		Id	id,
		std::string	name )

Construct a node instance.

Parameters

type	Node type name (typically stable across versions and used by factories/UI).
id	Unique node identifier within the graph.
name	Human-readable node name (must satisfy validateNodeName).

Warning: This constructor validates the name and may throw on invalid input.

◆ ~Node()

virtual dfx::Core::Node::~Node ( )

pure virtual

Virtual destructor. Pure virtual to ensure Node is abstract, but defined out-of-line.

Member Function Documentation

◆ allowsMimeTypePropagation()

bool dfx::Core::Node::allowsMimeTypePropagation ( ) const

inlinenoexcept

Whether this node allows mime-type propagation through its ports.

This is used during graph validation at node creation time. See Graph channel verification (kind + mime-type compatibility) for more information. Nodes may change this behavior during initialization via setAllowsMimeTypePropagation.

◆ as() [1/2]

template<DerivedFromNode T>

T const & dfx::Core::Node::as ( ) const

inlinenoexcept

Cast this node to a derived type (unchecked).

Template Parameters

T	A type derived from Node.

Returns: Const-reference to the node as T.

Warning: This is a static_cast. Only call it if you are sure of the type, or check first with is.

◆ as() [2/2]

template<DerivedFromNode T>

T & dfx::Core::Node::as ( )

inlinenoexcept

Cast this node to a derived type (unchecked).

Template Parameters

T	A type derived from Node.

Returns: Reference to the node as T.

Warning: This is a static_cast. Only call it if you are sure of the type, or check first with is.

◆ assignTaskExecutor()

void dfx::Core::Node::assignTaskExecutor ( Runtime::Api::NodeTaskExecutorPtr executor )

protected

Assigns a custom task executor to this node.

The custom executor is saved in this class and will be automatically set to the reactor when it is set or changed.

Warning: This method must not be called from the constructor since it requires that weak_from_this returns a valid weak_ptr.

See also: dfx::Runtime::Api::NodeReactor::assignTaskExecutor; CustomExecutor

◆ config()

nlohmann::json const & dfx::Core::Node::config ( ) const

inlinenoexcept

Get the node configuration.

◆ configSchema()

virtual nlohmann::json dfx::Core::Node::configSchema ( ) const

pure virtual

Return the JSON schema describing the node configuration. Used by the dfx::Graph::NodeFactory / tooling / UI to validate and edit configuration.

See also: DFX_NODE

Implemented in dfx::Plugins::CNode.

◆ customExecutor()

template<typename T = Runtime::Api::NodeTaskExecutor>

T * dfx::Core::Node::customExecutor ( ) const

inlinenoexcept

Access the customer executor of this node if any.

Template Parameters

T	The type of the underlying executor

Returns: The customer executor or nullptr if none has been set

◆ executionFlowPolicy()

ExecutionFlowPolicy dfx::Core::Node::executionFlowPolicy ( ) const

inlinenoexcept

Get the node execution policy.

◆ handleMessage()

virtual void dfx::Core::Node::handleMessage	(	InputPort const &	port,
		MessagePtr	message )

protectedpure virtual

Handle an incoming message on an input port.

This is the core callback invoked by dfx::Core::InputPort when messages are delivered to this node.

Parameters

port	The input port that received the message.
message	The delivered message.

Implemented in dfx::Node::Base64, dfx::Node::Delay, dfx::Node::FileSink, dfx::Node::FileSource, dfx::Node::Log, dfx::Node::MimeTypeRouter, dfx::Node::NullSink, dfx::Node::Process, dfx::Node::Switch, dfx::Node::Testing::Configurable, dfx::Node::ThreadBased, and dfx::Plugins::CNode.

◆ hasInputPort() [1/2]

bool dfx::Core::Node::hasInputPort ( Port::Id id ) const

inlinenoexcept

Check whether an input port exists by id.

◆ hasInputPort() [2/2]

bool dfx::Core::Node::hasInputPort ( std::string_view portName ) const

inlinenoexcept

Check whether an input port exists by name.

◆ hasOutputPort() [1/2]

bool dfx::Core::Node::hasOutputPort ( Port::Id id ) const

inlinenoexcept

Check whether an output port exists by id.

◆ hasOutputPort() [2/2]

bool dfx::Core::Node::hasOutputPort ( std::string_view portName ) const

inlinenoexcept

Check whether an output port exists by name.

◆ id()

Id dfx::Core::Node::id ( ) const

inlinenoexcept

Get the node id.

◆ initialize()

void dfx::Core::Node::initialize ( nlohmann::json config )

protected

Initialize the node with its configuration.

Calls initializeImpl and then stores the resulting configuration in config().

Note: This is typically invoked by the graph/factory layer, not by end users. Hence why it is not public.

◆ initializeImpl()

virtual void dfx::Core::Node::initializeImpl ( nlohmann::json config )

protectedpure virtual

Called by initialize; derived nodes must parse config here.

Implemented in dfx::Node::Base64, dfx::Node::Delay, dfx::Node::FileSink, dfx::Node::FileSource, dfx::Node::Generator, dfx::Node::Log, dfx::Node::MimeTypeRouter, dfx::Node::NullSink, dfx::Node::Process, dfx::Node::Switch, dfx::Node::Testing::Configurable, and dfx::Plugins::CNode.

◆ inputPort() [1/4]

InputPort & dfx::Core::Node::inputPort ( Port::Id id )

Get an input port by id (mutable).

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ inputPort() [2/4]

InputPort const & dfx::Core::Node::inputPort ( Port::Id id ) const

Get an input port by id.

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ inputPort() [3/4]

InputPort & dfx::Core::Node::inputPort ( std::string_view portName )

Get an input port by name (mutable).

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ inputPort() [4/4]

InputPort const & dfx::Core::Node::inputPort ( std::string_view portName ) const

Get an input port by name.

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ inputPorts()

InputPortContainer const & dfx::Core::Node::inputPorts ( ) const

inlinenoexcept

Get all input ports of all Kind.

◆ is()

template<DerivedFromNode T>

bool dfx::Core::Node::is ( ) const

inlinenoexcept

Check whether this node is of a given derived type.

Template Parameters

T	A type derived from Node.

Returns: true if dynamic_cast<T const*>(this) succeeds.

◆ isRunning()

bool dfx::Core::Node::isRunning ( ) const

inlinenoexcept

Check of the node is currently running.

◆ lock()

void dfx::Core::Node::lock ( )

inline

Lock the node's internal recursive mutex.

◆ metadata()

virtual nlohmann::json dfx::Core::Node::metadata ( ) const

pure virtual

Return node metadata (description, categories, ports, etc.). Intended for UI/tooling and discovery.

See also: DFX_NODE

Implemented in dfx::Plugins::CNode.

◆ name()

std::string const & dfx::Core::Node::name ( ) const

inlinenoexcept

Get the node name.

◆ onNodeStopped()

void dfx::Core::Node::onNodeStopped ( )

protected

Must be called by classes that re-implement the stopImpl function.

Informs the node that it has actually stop since some node may take a while to stop.

◆ outputPort() [1/4]

OutputPort & dfx::Core::Node::outputPort ( Port::Id id )

Get an output port by id (mutable).

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ outputPort() [2/4]

OutputPort const & dfx::Core::Node::outputPort ( Port::Id id ) const

Get an output port by id.

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ outputPort() [3/4]

OutputPort & dfx::Core::Node::outputPort ( std::string_view portName )

Get an output port by name (mutable).

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ outputPort() [4/4]

OutputPort const & dfx::Core::Node::outputPort ( std::string_view portName ) const

Get an output port by name.

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ outputPorts()

OutputPortContainer const & dfx::Core::Node::outputPorts ( ) const

inlinenoexcept

Get all output ports of all Kind.

◆ poller()

FdWatch::Poller & dfx::Core::Node::poller ( )

Access a poller instance associated with this node.

The poller is provided through a lazy-created dfx::Runtime::Api::PollerProxy that forwards registration requests to the runtime reactor.

Precondition: A reactor must have been set via setReactor.

Exceptions

dfx::Utils::Exception Throws if called without a reactor.

◆ reactor()

Runtime::Api::NodeReactor * dfx::Core::Node::reactor ( ) const

inlinenoexcept

Get the currently attached reactor (may be null if not set).

◆ registerControlInputPort()

InputPort & dfx::Core::Node::registerControlInputPort ( std::string name )

protected

Register a control input port.

Control ports are used for runtime control messages and use dfx::Core::MimeType::DfxControl.

Warning: Calling this from the node constructor is forbidden (the implementation requires weak_from_this).

◆ registerControlOutputPort()

OutputPort & dfx::Core::Node::registerControlOutputPort ( std::string name )

protected

Register a control output port.

Control ports are used for runtime control messages and use dfx::Core::MimeType::DfxControl.

Warning: Calling this from the node constructor is forbidden (the implementation requires weak_from_this).

◆ registerInputPort()

InputPort & dfx::Core::Node::registerInputPort	(	std::string	name,
		MimeTypes	supportedMimeTypes = {},
		std::optional< bool >	allowsMimeTypePropagation = std::nullopt )

protected

Register a data input port.

Parameters

name	Input port name (unique within the node).
supportedMimeTypes	Mime types accepted by the port.
allowsMimeTypePropagation	Optional override for propagation behavior.

Returns: Reference to the created port.

Warning: Calling this from the node constructor is forbidden (the implementation requires weak_from_this).

◆ registerOutputPort()

OutputPort & dfx::Core::Node::registerOutputPort	(	std::string	name,
		MimeType	mimeType = MimeType::Any,
		std::optional< bool >	allowsMimeTypePropagation = std::nullopt )

protected

Register a data output port.

Parameters

name	Output port name (unique within the node).
mimeType	Default mime type advertised by the port.
allowsMimeTypePropagation	Optional override for propagation behavior.

Returns: Reference to the created port.

Warning: Calling this from the node constructor is forbidden (the implementation requires weak_from_this).

◆ revokeTaskExecutor()

void dfx::Core::Node::revokeTaskExecutor ( )

protectednoexcept

Revokes a custom task executor, returning this node to the default execution model.

See also: dfx::Runtime::Api::NodeReactor::revokeTaskExecutor

◆ sendMessage() [1/3]

void dfx::Core::Node::sendMessage	(	OutputPort &	port,
		MessagePtr	message )

Send a message on the provided output port.

This is the lowest-level overload; it simply forwards to dfx::Core::OutputPort::sendMessage.

◆ sendMessage() [2/3]

void dfx::Core::Node::sendMessage	(	Port::Id	id,
		MessagePtr	message )

Send a message on an output port by id.

Parameters

id	Output port id.
message	Message to send.

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ sendMessage() [3/3]

void dfx::Core::Node::sendMessage	(	std::string_view	portName,
		MessagePtr	message )

Send a message on an output port by name.

Parameters

portName	Output port name.
message	Message to send.

Exceptions

dfx::Utils::Exception Throws if the port does not exist.

◆ setAllowsMimeTypePropagation()

void dfx::Core::Node::setAllowsMimeTypePropagation ( bool allowed )

inlineprotected

Enable/disable global mime-type propagation for this node. This affects how the runtime may propagate mime types through connected ports.

See also: Graph channel verification (kind + mime-type compatibility)

◆ setExecutionFlowPolicy()

virtual void dfx::Core::Node::setExecutionFlowPolicy ( ExecutionFlowPolicy policy )

inlineprotectedvirtual

Set the execution flow policy used by the runtime scheduler.

Derived nodes may choose a policy depending on their semantics (e.g. nodes that do heavy work might prefer AlwaysDispatch).

Reimplemented in dfx::Node::ThreadBased.

◆ setName()

void dfx::Core::Node::setName ( std::string newName )

Rename the node.

Parameters

newName New node name (must satisfy validateNodeName).

Precondition: The node must not be running.

Exceptions

dfx::Utils::Exception An exception (wrapped with context) if the node is running or the name is invalid.

◆ setReactor()

void dfx::Core::Node::setReactor ( Runtime::Api::NodeReactor * reactor )

Attach the runtime reactor used by this node.

Setting a new reactor clears the cached poller proxy; poller will recreate it lazily when needed.

The custom executor, if any, is revoked from the previous reactor and assign to the new one.

◆ start()

void dfx::Core::Node::start ( )

Start the node.

If the node is already running, this is a no-op.

First start all transport attached to this node, then calls startImpl and finally marks the node as running.

After starting, any messages that were received while the node was stopped are processed by asking each input port to flush its pending queue.

◆ startImpl()

virtual void dfx::Core::Node::startImpl ( )

inlineprotectedvirtual

Called by start before the node is marked running.

Reimplemented in dfx::Node::FileSink, dfx::Node::FileSource, dfx::Node::Process, dfx::Node::ThreadBased, and dfx::Plugins::CNode.

◆ stop()

void dfx::Core::Node::stop ( )

Stop the node.

If the node is not running, this is a no-op.

First stop all transport attached to this node, then calls stopImpl and finally marks the node as not running.

◆ stopImpl()

virtual void dfx::Core::Node::stopImpl ( )

inlineprotectedvirtual

Called by stop before the node is marked stopped.

When re-implementing this function, onNodeStopped must be called synchronously or not to inform the system that this node is now stopped.

Reimplemented in dfx::Node::FileSource, dfx::Node::Process, dfx::Node::ThreadBased, and dfx::Plugins::CNode.

◆ stopRequested()

bool dfx::Core::Node::stopRequested ( ) const

inlinenoexcept

Check if stop has already been called or not.

Returns: true if stop has been called at least once while the node was running

◆ try_lock()

bool dfx::Core::Node::try_lock ( )

inlinenoexcept

Try to lock the node's internal recursive mutex.

◆ type()

std::string const & dfx::Core::Node::type ( ) const

inlinenoexcept

Get the node type.

◆ unlock()

void dfx::Core::Node::unlock ( )

inline

Unlock the node's internal recursive mutex.

◆ validateNodeName()

void dfx::Core::Node::validateNodeName ( std::string_view name )

static

Validate a node name.

Rules enforced by the implementation:

Must not be empty.
Must only contain ASCII letters/digits, -, _, and spaces.
Must not start with a digit.
Dot (.) is forbidden (it is used as separator between node and port).

Parameters

name	Name to validate.

Exceptions

dfx::Utils::Exception if the name is invalid

◆ waitForStopped()

void dfx::Core::Node::waitForStopped ( )

Block the current thread until the node is stopped.

This function will return immediately if the node is already stopped

Warning: Must NOT be called while the node lock is held by the current thread otherwise a deadlock will occur

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

lib/dfx-core/Node.hpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Runtime integration

Detailed Description

Member Typedef Documentation

◆ Id

Member Enumeration Documentation

◆ ExecutionFlowPolicy

Constructor & Destructor Documentation

◆ Node()

◆ ~Node()

Member Function Documentation

◆ allowsMimeTypePropagation()

◆ as() [1/2]

◆ as() [2/2]

◆ assignTaskExecutor()

◆ config()

◆ configSchema()

◆ customExecutor()

◆ executionFlowPolicy()

◆ handleMessage()

◆ hasInputPort() [1/2]

◆ hasInputPort() [2/2]

◆ hasOutputPort() [1/2]

◆ hasOutputPort() [2/2]

◆ id()

◆ initialize()

◆ initializeImpl()

◆ inputPort() [1/4]

◆ inputPort() [2/4]

◆ inputPort() [3/4]

◆ inputPort() [4/4]

◆ inputPorts()

◆ is()

◆ isRunning()

◆ lock()

◆ metadata()

◆ name()

◆ onNodeStopped()

◆ outputPort() [1/4]

◆ outputPort() [2/4]

◆ outputPort() [3/4]

◆ outputPort() [4/4]

◆ outputPorts()

◆ poller()

◆ reactor()

◆ registerControlInputPort()

◆ registerControlOutputPort()

◆ registerInputPort()

◆ registerOutputPort()

◆ revokeTaskExecutor()

◆ sendMessage() [1/3]

◆ sendMessage() [2/3]

◆ sendMessage() [3/3]

◆ setAllowsMimeTypePropagation()

◆ setExecutionFlowPolicy()

◆ setName()

◆ setReactor()

◆ start()

◆ startImpl()

◆ stop()

◆ stopImpl()

◆ stopRequested()

◆ try_lock()

◆ type()

◆ unlock()

◆ validateNodeName()

◆ waitForStopped()