Transport-agnostic CRTP base for all VLink communication primitives. More...

#include <node.h>

Inheritance diagram for vlink::Node< ImplT, SecT >:

Collaboration diagram for vlink::Node< ImplT, SecT >:

Public Types
using	StatusCallback = NodeImpl::StatusCallback
	Handler signature for status-change notifications. More...

Public Member Functions
virtual bool	init ()
	Initialises the node and its transport back-end. More...

virtual bool	deinit ()
	Tears the node down and releases all transport resources. More...

virtual void	interrupt ()
	Aborts any blocking wait on this node. More...

bool	has_inited () const
	Reports whether `init()` has been successfully called. More...

bool	is_support_loan () const
	Reports whether the transport supports zero-copy loaned buffers. More...

Bytes	loan (int64_t size)
	Allocates a loaned buffer from the transport memory pool. More...

bool	return_loan (const Bytes &bytes)
	Returns a previously loaned buffer to the transport pool. More...

virtual void	set_manual_unloan (bool manual_unloan)
	Toggles manual-unloan mode for zero-copy receives. More...

virtual bool	is_manual_unloan () const
	Reports whether manual-unloan mode is currently active. More...

bool	suspend ()
	Suspends message delivery on this node. More...

bool	resume ()
	Resumes message delivery after a prior `suspend()`. More...

bool	is_suspend () const
	Reports whether the node is currently suspended. More...

bool	attach (class MessageLoop *message_loop)
	Attaches the node to a `MessageLoop` for callback dispatch. More...

bool	detach ()
	Detaches the node from its current `MessageLoop`. More...

class MessageLoop *	get_message_loop () const
	Returns the `MessageLoop` this node is currently attached to. More...

const AbstractNode *	get_abstract_node () const
	Returns the abstract-graph handle for runtime topology inspection. More...

Status::BasePtr	get_status (Status::Type type) const
	Retrieves the current status object for the requested category. More...

void	register_status_handler (StatusCallback &&callback)
	Registers a handler invoked whenever the node's status changes. More...

void	set_property (const std::string &prop, const std::string &value)
	Sets a transport-specific string-keyed property. More...

std::string	get_property (const std::string &prop) const
	Retrieves a previously set transport-specific property value. More...

TransportType	get_transport_type () const
	Returns the `TransportType` this node is bound to. More...

const std::string &	get_url () const
	Returns the URL string used to construct this node. More...

void	set_record_path (const std::string &path)
	Enables recording of inbound or outbound messages to a bag file. More...

void	set_ser_type (const std::string &ser_type, SchemaType schema_type=SchemaType::kUnknown)
	Overrides the runtime wire-metadata identifiers for this node. More...

const std::string &	get_ser_type () const
	Returns the current concrete runtime type identifier. More...

SchemaType	get_schema_type () const
	Returns the current coarse schema family. More...

void	set_discovery_enabled (bool enable)
	Toggles peer-discovery on this node. More...

bool	get_discovery_enabled () const
	Reports whether peer-discovery is currently enabled. More...

void	bind_proto_arena (void *proto_arena)
	Binds a Protobuf Arena for arena-allocated message objects. More...

double	get_cpu_usage () const
	Returns the cumulative CPU-usage ratio sampled by the profiler. More...

bool	get_safety_quit () const
	Reports whether safe-quit mode is currently active. More...

void	set_safety_quit (bool safety_quit)
	Enables or disables safe-quit mode. More...

void	set_ssl_options (const SslOptions &options)
	Configures transport-layer SSL/TLS encryption for this node. More...

Protected Member Functions
	Node ()

virtual	~Node ()

bool	enable_security (const Security::Config &cfg)
	Installs a `Security` configuration before transport initialisation. More...

bool	enable_security (Security::Config &&cfg)
	Move overload for construction-time security installation. More...

template<typename CallbackT , typename... ArgsT>
void	invoke_callback (const CallbackT &callback, ArgsT &&... args)

template<typename TypeT >
TypeT	get_default_value ()

Protected Attributes
void *	proto_arena_ {nullptr}

bool	is_support_loan_ {false}

bool	is_manual_unloan_ {false}

std::atomic_bool	has_inited_ {false}

std::optional< std::mutex >	quit_mtx_

std::unique_ptr< ImplT >	impl_

Detailed Description

template<typename ImplT, SecurityType SecT>
class vlink::Node< ImplT, SecT >

Transport-agnostic CRTP base for all VLink communication primitives.

Provides the lifecycle, loan, security, property, profiler, message-loop, recording, discovery, and TLS APIs shared by every primitive in the library. Subclasses fill in the role-specific operations (publish, listen, invoke, set, get, etc.).

Template Parameters

ImplT	Concrete implementation class (e.g. `PublisherImpl`).
SecT	Security mode (`kWithoutSecurity` or `kWithSecurity`).

Member Typedef Documentation

◆ StatusCallback

template<typename ImplT , SecurityType SecT>

using vlink::Node< ImplT, SecT >::StatusCallback = NodeImpl::StatusCallback

Handler signature for status-change notifications.

Constructor & Destructor Documentation

◆ Node()

template<typename ImplT , SecurityType SecT>

vlink::Node< ImplT, SecT >::Node

inlineprotected

◆ ~Node()

template<typename ImplT , SecurityType SecT>

vlink::Node< ImplT, SecT >::~Node

inlineprotectedvirtual

Member Function Documentation

◆ attach()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::attach ( class MessageLoop * message_loop )

inline

Attaches the node to a MessageLoop for callback dispatch.

After attachment, inbound callbacks are posted onto message_loop rather than invoked on the transport delivery thread. This serialises dispatch onto the loop's thread, which is convenient for single-threaded user code.

Parameters

message_loop Pointer to the target MessageLoop.

Returns: true on success; false if a loop is already attached.

◆ bind_proto_arena()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::bind_proto_arena ( void * proto_arena )

inline

Binds a Protobuf Arena for arena-allocated message objects.

Required when MsgT is a raw Protobuf pointer type (e.g. MyProto*). The arena must outlive this node. Forgetting to bind an arena before the first received message triggers a fatal log.

Parameters

proto_arena Pointer to a google::protobuf::Arena instance (typed as void*).

◆ deinit()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::deinit

inlinevirtual

Tears the node down and releases all transport resources.

Atomically guards against double-deinit, then runs interrupt(), impl_->deinit(), and impl_->deinit_ext(). When safe-quit mode is active the sequence runs under the safe-quit mutex. The destructor calls this automatically so explicit calls are only required for early shutdown.

Returns: true on first successful deinit; false if not initialised.

Reimplemented in vlink::Setter< ValueT, SecT >, and vlink::Setter< ValueT, SecurityType::kWithSecurity >.

Here is the caller graph for this function:

◆ detach()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::detach

inline

Detaches the node from its current MessageLoop.

After detachment the callback returns to running on the transport delivery thread.

Returns: true on success; false if no loop was attached.

◆ enable_security() [1/2]

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::enable_security ( const Security::Config & cfg )

inlineprotected

Installs a Security configuration before transport initialisation.

Internal helper used by the Security* primitive constructors after impl_ has been created but before init(). Delegates default handling, validation, and storage to NodeImpl::enable_security().

Parameters

cfg	Security configuration aggregate.

Returns: true when cfg (including the default empty case) is usable for this role / transport.

Here is the caller graph for this function:

◆ enable_security() [2/2]

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::enable_security ( Security::Config && cfg )

inlineprotected

Move overload for construction-time security installation.

Used when an internal caller owns the config and can forward it without an extra copy.

Parameters

cfg	Security configuration aggregate to consume.

Returns: true when cfg (including the default empty case) is usable for this role / transport.

◆ get_abstract_node()

template<typename ImplT , SecurityType SecT>

const AbstractNode * vlink::Node< ImplT, SecT >::get_abstract_node

inline

Returns the abstract-graph handle for runtime topology inspection.

The AbstractNode pointer is usable with AbstractFactory and the proxy monitoring API to enumerate peer nodes in the same transport graph.

Returns: Non-owning pointer to the AbstractNode, or nullptr if the transport does not expose one.

◆ get_cpu_usage()

template<typename ImplT , SecurityType SecT>

double vlink::Node< ImplT, SecT >::get_cpu_usage

inline

Returns the cumulative CPU-usage ratio sampled by the profiler.

Reports the percentage of wall-clock time this node has spent in active publish or receive code since the profiler was started. Available only when the CPU profiler is built in (VLINK_DISABLE_PROFILER not defined) and global profiling is enabled via the VLINK_PROFILER_ENABLE environment variable. Returns -1.0 if no profiler is attached.

Returns: CPU usage percentage (may exceed 100.0 on multi-core systems); -1.0 if unavailable.

◆ get_default_value()

template<typename ImplT , SecurityType SecT>

template<typename TypeT >

TypeT vlink::Node< ImplT, SecT >::get_default_value

inlineprotected

◆ get_discovery_enabled()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::get_discovery_enabled

inline

Reports whether peer-discovery is currently enabled.

Returns: true if discovery is active.

◆ get_message_loop()

template<typename ImplT , SecurityType SecT>

class MessageLoop * vlink::Node< ImplT, SecT >::get_message_loop

inline

Returns the MessageLoop this node is currently attached to.

Returns: Pointer to the attached MessageLoop, or nullptr.

◆ get_property()

template<typename ImplT , SecurityType SecT>

std::string vlink::Node< ImplT, SecT >::get_property ( const std::string & prop ) const

inline

Retrieves a previously set transport-specific property value.

Parameters

prop	Property key string.

Returns: Property value string; empty if the key is unknown.

◆ get_safety_quit()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::get_safety_quit

inline

Reports whether safe-quit mode is currently active.

Safe-quit mode holds a std::mutex around user callbacks and around deinit() to prevent use-after-free races when a node is destroyed while a callback is in flight.

Returns: true if the safe-quit mutex is engaged.

◆ get_schema_type()

template<typename ImplT , SecurityType SecT>

SchemaType vlink::Node< ImplT, SecT >::get_schema_type

inline

Returns the current coarse schema family.

Returns: The SchemaType stored on the implementation.

◆ get_ser_type()

template<typename ImplT , SecurityType SecT>

const std::string & vlink::Node< ImplT, SecT >::get_ser_type

inline

Returns the current concrete runtime type identifier.

Returns: Const reference to the type identifier string.

◆ get_status()

template<typename ImplT , SecurityType SecT>

Status::BasePtr vlink::Node< ImplT, SecT >::get_status ( Status::Type type ) const

inline

Retrieves the current status object for the requested category.

Returns a polymorphic shared pointer. The concrete type and set of supported categories depend on the active transport; an unsupported type yields a Status::Unknown instance and logs a warning.

Parameters

type	Status category to retrieve.

Returns: Shared pointer to status data, or Status::Unknown when unsupported.

◆ get_transport_type()

template<typename ImplT , SecurityType SecT>

TransportType vlink::Node< ImplT, SecT >::get_transport_type

inline

Returns the TransportType this node is bound to.

Returns: Enumerator such as kDds, kShm, kIntra, etc.

◆ get_url()

template<typename ImplT , SecurityType SecT>

const std::string & vlink::Node< ImplT, SecT >::get_url

inline

Returns the URL string used to construct this node.

Non-empty only when the node was constructed via a URL string or Url object; typed ConfT-based construction leaves this empty.

Returns: Const reference to the URL string.

◆ has_inited()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::has_inited

inline

Reports whether init() has been successfully called.

Returns: true when the node is currently in the initialised state.

◆ init()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::init

inlinevirtual

Initialises the node and its transport back-end.

Uses an atomic compare-exchange to guard against double-initialisation. On success the method runs impl_->init() then impl_->init_ext() and finally samples the transport's loan capability flag. Calling init() on an already-initialised node is a no-op.

Returns: true on first successful initialisation; false otherwise.

Reimplemented in vlink::Setter< ValueT, SecT >, vlink::Setter< ValueT, SecurityType::kWithSecurity >, vlink::Getter< ValueT, SecT >, and vlink::Getter< ValueT, SecurityType::kWithSecurity >.

Here is the caller graph for this function:

◆ interrupt()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::interrupt

inlinevirtual

Aborts any blocking wait on this node.

Signals the internal interrupted flag and notifies the condition variable so that wait_for_subscribers(), wait_for_connected(), and wait_for_value() return immediately with false. Getter overrides this to additionally wake its own condition variable used by wait_for_value().

Reimplemented in vlink::Getter< ValueT, SecT >, and vlink::Getter< ValueT, SecurityType::kWithSecurity >.

◆ invoke_callback()

template<typename ImplT , SecurityType SecT>

template<typename CallbackT , typename... ArgsT>

void vlink::Node< ImplT, SecT >::invoke_callback	(	const CallbackT &	callback,
		ArgsT &&...	args
	)

inlineprotected

◆ is_manual_unloan()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::is_manual_unloan

inlinevirtual

Reports whether manual-unloan mode is currently active.

Returns: true if set_manual_unloan(true) was invoked.

◆ is_support_loan()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::is_support_loan

inline

Reports whether the transport supports zero-copy loaned buffers.

Delegates to the transport implementation. When loans are supported, publish() / set() / reply() automatically use them to avoid an extra memory copy.

Returns: true if loan() / return_loan() are meaningful for this transport.

◆ is_suspend()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::is_suspend

inline

Reports whether the node is currently suspended.

Returns: true while suspend() is in effect.

◆ loan()

template<typename ImplT , SecurityType SecT>

Bytes vlink::Node< ImplT, SecT >::loan ( int64_t size )

inline

Allocates a loaned buffer from the transport memory pool.

Returns a Bytes backed by transport-managed memory of size bytes. The caller must either pass it to a publish/write call (which returns the loan automatically) or call return_loan() explicitly. Returns an empty Bytes on failure or when the transport has no loan pool.

Parameters

size	Requested byte count; `0` is valid for empty messages.

Returns: Loaned Bytes, or an empty Bytes on failure.

◆ register_status_handler()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::register_status_handler ( StatusCallback && callback )

inline

Registers a handler invoked whenever the node's status changes.

Only one handler can be registered at a time; subsequent calls replace the previous handler. The handler receives a Status::BasePtr describing the new state (connected, disconnected, error, etc.).

Parameters

callback void(const Status::BasePtr&) handler.

◆ resume()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::resume

inline

Resumes message delivery after a prior suspend().

Returns: true if resumption succeeded.

◆ return_loan()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::return_loan ( const Bytes & bytes )

inline

Returns a previously loaned buffer to the transport pool.

Must be called whenever a loan obtained via loan() is not consumed by a publish/write call; failing to return loans can exhaust the shared memory pool.

Parameters

bytes The loaned Bytes to return.

Returns: true on success; false if the buffer is not a valid loan.

◆ set_discovery_enabled()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_discovery_enabled ( bool enable )

inline

Toggles peer-discovery on this node.

Disabling discovery reduces CPU and network overhead for nodes that never need to locate peers. Reinitialises the transport extension if invoked post-init() so the change takes effect immediately.

Parameters

enable true (default) to enable discovery; false to disable.

◆ set_manual_unloan()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_manual_unloan ( bool manual_unloan )

inlinevirtual

Toggles manual-unloan mode for zero-copy receives.

In manual mode the user must call return_loan() after consuming each received buffer. The base implementation logs a warning; only Subscriber and Getter provide a meaningful override.

Parameters

manual_unloan true to enable; false for automatic (default).

Reimplemented in vlink::Subscriber< MsgT, SecT >, vlink::Subscriber< MsgT, SecurityType::kWithSecurity >, vlink::Getter< ValueT, SecT >, and vlink::Getter< ValueT, SecurityType::kWithSecurity >.

◆ set_property()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_property	(	const std::string &	prop,
		const std::string &	value
	)

inline

Sets a transport-specific string-keyed property.

Extensibility mechanism for back-end-specific tuning knobs that do not have a dedicated method. Recognised keys depend on the active transport.

Parameters

prop	Property key string.
value	Property value string.

◆ set_record_path()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_record_path ( const std::string & path )

inline

Enables recording of inbound or outbound messages to a bag file.

Not supported on intra:// or dds:// CDR nodes (triggers a fatal log). Supported file suffixes are .vdb, .vdbx, .vcap, and .vcapx; an unknown suffix logs an error and disables recording.

Parameters

path	Bag file path on disk.

◆ set_safety_quit()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_safety_quit ( bool safety_quit )

inline

Enables or disables safe-quit mode.

When enabled, an internal std::mutex is allocated and locked around every callback invocation and around deinit(). Enable when the node's lifetime is shorter than the callback scope. There is a small synchronisation overhead; avoid enabling it on hot paths.

Parameters

safety_quit true to enable; false to disable (default).

◆ set_ser_type()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_ser_type	(	const std::string &	ser_type,
		SchemaType	schema_type = `SchemaType::kUnknown`
	)

inline

Overrides the runtime wire-metadata identifiers for this node.

ser_type holds the concrete runtime type identifier; schema_type holds the coarse decoder family used by discovery, proxy, and bag metadata. When schema_type is SchemaType::kUnknown (the default) the family is inferred from ser_type: a "vlink::zerocopy::" prefix implies kZeroCopy, while values such as "raw", "string", "std::string", "text", or "json" imply kRaw. If no family can be inferred, an existing kRaw or kZeroCopy family is reset to kUnknown; any other existing family is preserved. Passing an empty ser_type clears both fields.

If invoked post-init() the transport extension is restarted so that external metadata stays in sync.

Parameters

ser_type	Concrete runtime type identifier, or empty to clear.
schema_type	Optional explicit schema family; default preserves the current family.

◆ set_ssl_options()

template<typename ImplT , SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_ssl_options ( const SslOptions & options )

inline

Configures transport-layer SSL/TLS encryption for this node.

Merges the fields of options into the node's internal property map via SslOptions::parse_to(). The transport reads the resulting ssl.* properties during init() to set up the TLS connection, so this method must be called before init() for the settings to take effect.

SSL is considered enabled when SslOptions::is_valid() returns true (i.e. at least ca_file or cert_file is non-empty). Not all back-ends support TLS; see SslOptions for the per-backend compatibility table. Thread-safe – the property map is updated under a mutex.

Example: vlink::Publisher<MyMsg> pub("mqtt://sensor/data", vlink::InitType::kWithoutInit);

vlink::SslOptions ssl;

ssl.ca_file = "/etc/certs/ca.pem";

ssl.cert_file = "/etc/certs/client.pem";

ssl.key_file = "/etc/certs/client-key.pem";

pub.set_ssl_options(ssl);

pub.init();

vlink::Publisher
Type-safe topic emitter for the VLink event communication model.
Definition: publisher.h:130

vlink::InitType::kWithoutInit
@ kWithoutInit
Defer initialisation; call init() manually.

vlink::SslOptions
Aggregate of SSL / TLS settings for transport-layer encryption.
Definition: ssl_options.h:119

vlink::SslOptions::cert_file
std::string cert_file
Path to the client certificate (PEM) used for mutual TLS.
Definition: ssl_options.h:146

vlink::SslOptions::key_file
std::string key_file
Path to the client private key (PEM) accompanying cert_file.
Definition: ssl_options.h:154

vlink::SslOptions::ca_file
std::string ca_file
Path to the CA certificate (PEM) used to validate the peer.
Definition: ssl_options.h:137

Parameters

options SSL/TLS configuration to apply.

See also: SslOptions, set_property()

◆ suspend()

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::suspend

inline

Suspends message delivery on this node.

Transport-dependent behaviour: some back-ends buffer incoming messages while suspended, others drop them. Pair with resume().

Returns: true if suspension succeeded.

Member Data Documentation

◆ has_inited_

template<typename ImplT , SecurityType SecT>

std::atomic_bool vlink::Node< ImplT, SecT >::has_inited_ {false}

protected

◆ impl_

template<typename ImplT , SecurityType SecT>

std::unique_ptr<ImplT> vlink::Node< ImplT, SecT >::impl_

protected

◆ is_manual_unloan_

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::is_manual_unloan_ {false}

protected

◆ is_support_loan_

template<typename ImplT , SecurityType SecT>

bool vlink::Node< ImplT, SecT >::is_support_loan_ {false}

protected

◆ proto_arena_

template<typename ImplT , SecurityType SecT>

void* vlink::Node< ImplT, SecT >::proto_arena_ {nullptr}

protected

◆ quit_mtx_

template<typename ImplT , SecurityType SecT>

std::optional<std::mutex> vlink::Node< ImplT, SecT >::quit_mtx_

protected

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

include/vlink/node.h
include/vlink/internal/node-inl.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

template<typename ImplT, SecurityType SecT> class vlink::Node< ImplT, SecT >

Member Typedef Documentation

◆ StatusCallback

Constructor & Destructor Documentation

◆ Node()

◆ ~Node()

Member Function Documentation

◆ attach()

◆ bind_proto_arena()

◆ deinit()

◆ detach()

◆ enable_security() [1/2]

◆ enable_security() [2/2]

◆ get_abstract_node()

◆ get_cpu_usage()

◆ get_default_value()

◆ get_discovery_enabled()

◆ get_message_loop()

◆ get_property()

◆ get_safety_quit()

◆ get_schema_type()

◆ get_ser_type()

◆ get_status()

◆ get_transport_type()

◆ get_url()

◆ has_inited()

◆ init()

◆ interrupt()

◆ invoke_callback()

◆ is_manual_unloan()

◆ is_support_loan()

◆ is_suspend()

◆ loan()

◆ register_status_handler()

◆ resume()

◆ return_loan()

◆ set_discovery_enabled()

◆ set_manual_unloan()

◆ set_property()

◆ set_record_path()

◆ set_safety_quit()

◆ set_ser_type()

◆ set_ssl_options()

◆ suspend()

Member Data Documentation

◆ has_inited_

◆ impl_

◆ is_manual_unloan_

◆ is_support_loan_

◆ proto_arena_

◆ quit_mtx_

template<typename ImplT, SecurityType SecT>
class vlink::Node< ImplT, SecT >