Transport-agnostic CRTP base for all VLink communication nodes. 更多...

#include <node.h>

类 vlink::Node< ImplT, SecT > 继承关系图:

vlink::Node< ImplT, SecT > 的协作图:

Public 类型
using	StatusCallback = NodeImpl::StatusCallback
	Callback type for node status-change notifications.

Public 成员函数
virtual bool	init ()
	Initialises the node and its transport back-end.
virtual bool	deinit ()
	Shuts down the node and releases all transport resources.
virtual void	interrupt ()
	Unblocks any active blocking wait on this node.
bool	has_inited () const
	Returns `true` if `init()` has been successfully called.
bool	is_support_loan () const
	Returns `true` if the transport supports zero-copy loaned buffers.
Bytes	loan (int64_t size)
	Allocates a loaned buffer from the transport memory pool.
bool	return_loan (const Bytes &bytes)
	Returns a previously loaned buffer back to the transport pool.
virtual void	set_manual_unloan (bool manual_unloan)
	Enables or disables manual-unloan mode for zero-copy receives.
virtual bool	is_manual_unloan () const
	Returns `true` if manual-unloan mode is active.
bool	suspend ()
	Suspends message delivery on this node.
bool	resume ()
	Resumes message delivery after a `suspend()`.
bool	is_suspend () const
	Returns `true` if the node is currently suspended.
bool	attach (class MessageLoop *message_loop)
	Attaches the node to a `MessageLoop` for callback dispatching.
bool	detach ()
	Detaches the node from its current `MessageLoop`.
class MessageLoop *	get_message_loop () const
	Returns the `MessageLoop` this node is attached to.
const AbstractNode *	get_abstract_node () const
	Returns the abstract node handle for graph introspection.
Status::BasePtr	get_status (Status::Type type) const
	Returns the current status object for the specified status type.
void	register_status_handler (StatusCallback &&callback)
	Registers a handler called when the node's status changes.
void	set_property (const std::string &prop, const std::string &value)
	Sets a transport-specific key-value property on the node.
std::string	get_property (const std::string &prop) const
	Retrieves a transport-specific property value.
TransportType	get_transport_type () const
	Returns the `TransportType` of the transport this node is bound to.
const std::string &	get_url () const
	Returns the URL string used to construct this node.
void	set_security_key (const std::string &key)
	Sets the symmetric encryption key for message security.
void	set_record_path (const std::string &path)
	Sets the filesystem path for message bag recording.
void	set_security_callbacks (Security::Callback &&encrypt_callback, Security::Callback &&decrypt_callback)
	Installs custom encrypt and decrypt callbacks.
void	set_ser_type (const std::string &ser_type, SchemaType schema_type=SchemaType::kUnknown)
	Overrides the runtime wire metadata for this node.
const std::string &	get_ser_type () const
	Returns the current serialisation type string.
SchemaType	get_schema_type () const
	Returns the current coarse schema family.
void	set_discovery_enabled (bool enable)
	Enables or disables peer-discovery on this node.
bool	get_discovery_enabled () const
	Returns `true` if peer-discovery is currently enabled.
void	bind_proto_arena (void *proto_arena)
	Binds a Protobuf Arena for arena-allocated message objects.
double	get_cpu_usage () const
	Returns the cumulative CPU usage ratio for this node.
bool	get_safety_quit () const
	Returns `true` if safe-quit mode is currently active.
void	set_safety_quit (bool safety_quit)
	Enables or disables safe-quit mode.
void	set_ssl_options (const SslOptions &options)
	Configures transport-layer SSL/TLS encryption for this node.

Protected 成员函数
	Node ()
virtual	~Node ()
void	enable_security ()
template<typename CallbackT, typename... ArgsT>
void	invoke_callback (const CallbackT &callback, ArgsT &&... args)
template<typename TypeT>
TypeT	get_default_value ()

Protected 属性
std::atomic_bool	has_inited_ {false}
std::unique_ptr< ImplT >	impl_
std::optional< Security >	security_
std::optional< std::mutex >	quit_mtx_
void *	proto_arena_ {nullptr}
bool	is_support_loan_ {false}
bool	is_manual_unloan_ {false}

详细描述

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

Transport-agnostic CRTP base for all VLink communication nodes.

All six VLink communication primitives inherit from this template. It manages the ImplT implementation pointer and provides the shared API surface described in the file-level documentation above.

模板参数

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

成员类型定义说明

◆ StatusCallback

template<typename ImplT, SecurityType SecT>

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

Callback type for node status-change notifications.

构造及析构函数说明

◆ Node()

template<typename ImplT, SecurityType SecT>

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

inlineprotected

◆ ~Node()

template<typename ImplT, SecurityType SecT>

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

inlineprotectedvirtual

成员函数说明

◆ 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 dispatching.

After attachment, incoming-message callbacks are posted to message_loop rather than invoked on the transport thread. This serialises delivery to the loop's thread, which is useful for single-threaded application code.

参数

message_loop Non-null pointer to the target MessageLoop.

返回: true on success; false if a MessageLoop 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 for proto-pointer types causes a fatal log on the first received message.

参数

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

◆ deinit()

template<typename ImplT, SecurityType SecT>

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

inlinevirtual

Shuts down the node and releases all transport resources.

Uses an atomic compare-exchange to prevent double-deinit. Calls interrupt() first, then impl_->deinit() and impl_->deinit_ext(). When safe-quit mode is active the deinit sequence runs under the quit mutex. The destructor calls deinit() automatically, so explicit calls are only needed for early shutdown.

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

被 vlink::Setter< ValueT, SecT > , 以及 vlink::Setter< ValueT, SecurityType::kWithSecurity > 重载.

函数调用图:

这是这个函数的调用关系图:

◆ detach()

template<typename ImplT, SecurityType SecT>

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

inline

Detaches the node from its current MessageLoop.

After detachment, callbacks are again invoked on the transport thread.

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

◆ enable_security()

template<typename ImplT, SecurityType SecT>

void vlink::Node< ImplT, SecT >::enable_security ( )

inlineprotected

◆ get_abstract_node()

template<typename ImplT, SecurityType SecT>

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

inlinenodiscard

Returns the abstract node handle for graph introspection.

The AbstractNode pointer can be used with AbstractFactory to query peer nodes in the same transport graph, or passed to the proxy monitoring API for runtime topology inspection.

返回: Non-owning pointer to the AbstractNode, or nullptr if the transport back-end does not expose an AbstractNode.

◆ get_cpu_usage()

template<typename ImplT, SecurityType SecT>

double vlink::Node< ImplT, SecT >::get_cpu_usage ( ) const

inlinenodiscard

Returns the cumulative CPU usage ratio for this node.

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

返回: CPU usage percentage [0.0, 100.0], or -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 ( ) const

inlinenodiscard

Returns true if peer-discovery is currently enabled.

返回: true if discovery is active.

◆ get_message_loop()

template<typename ImplT, SecurityType SecT>

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

inlinenodiscard

Returns the MessageLoop this node is attached to.

返回: 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

inlinenodiscard

Retrieves a transport-specific property value.

参数

prop	Property key string.

返回: Property value string; empty if key is not recognised.

◆ get_safety_quit()

template<typename ImplT, SecurityType SecT>

bool vlink::Node< ImplT, SecT >::get_safety_quit ( ) const

inlinenodiscard

Returns true if safe-quit mode is currently active.

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

返回: true if the safe-quit mutex is engaged.

◆ get_schema_type()

template<typename ImplT, SecurityType SecT>

SchemaType vlink::Node< ImplT, SecT >::get_schema_type ( ) const

inlinenodiscard

Returns the current coarse schema family.

返回: The schema family stored in the node implementation.

◆ get_ser_type()

template<typename ImplT, SecurityType SecT>

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

inlinenodiscard

Returns the current serialisation type string.

返回: Reference to the type string stored in the impl.

◆ get_status()

template<typename ImplT, SecurityType SecT>

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

inlinenodiscard

Returns the current status object for the specified status type.

Returns a polymorphic status shared pointer. The concrete type and set of available types depend on the active transport. If the transport does not support the requested type, a Status::Unknown instance is returned and a warning is logged.

参数

type	Category of status to retrieve.

返回: Shared pointer to status data; returns Status::Unknown when the transport does not support the query.

◆ get_transport_type()

template<typename ImplT, SecurityType SecT>

TransportType vlink::Node< ImplT, SecT >::get_transport_type ( ) const

inlinenodiscard

Returns the TransportType of the transport this node is bound to.

返回: Enumerator such as kDds, kShm, kIntra, etc.

◆ get_url()

template<typename ImplT, SecurityType SecT>

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

inlinenodiscard

Returns the URL string used to construct this node.

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

返回: Reference to the URL (e.g. "dds://vehicle/speed").

◆ has_inited()

template<typename ImplT, SecurityType SecT>

bool vlink::Node< ImplT, SecT >::has_inited ( ) const

inlinenodiscard

Returns true if init() has been successfully called.

返回: true when the node is 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: calls impl_->init(), impl_->init_ext(), and queries the transport for zero-copy loan support. Calling init() on an already-initialised node is a no-op that returns false.

返回: true on first successful initialisation; false otherwise.

被 vlink::Getter< ValueT, SecT >, vlink::Getter< ValueT, SecurityType::kWithSecurity >, vlink::Setter< ValueT, SecT > , 以及 vlink::Setter< ValueT, SecurityType::kWithSecurity > 重载.

这是这个函数的调用关系图:

◆ interrupt()

template<typename ImplT, SecurityType SecT>

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

inlinevirtual

Unblocks any active blocking wait on this node.

Signals the internal interrupted flag and wakes the condition variable so that calls such as wait_for_subscribers(), wait_for_connected(), and wait_for_value() return immediately with false. Subclasses such as Getter, Publisher, and Client override this to also wake their own blocking condition variables.

被 vlink::Getter< ValueT, SecT > , 以及 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 ( ) const

inlinenodiscardvirtual

Returns true if manual-unloan mode is active.

返回: true if set_manual_unloan(true) was called.

◆ is_support_loan()

template<typename ImplT, SecurityType SecT>

bool vlink::Node< ImplT, SecT >::is_support_loan ( ) const

inlinenodiscard

Returns true if the transport supports zero-copy loaned buffers.

Currently the shm:// (Iceoryx) and shm2:// (Iceoryx2) back-ends return true here. When loans are supported, publish() / set() / reply() will automatically use them to avoid an extra memory copy.

返回: true if loan() / return_loan() are meaningful.

◆ is_suspend()

template<typename ImplT, SecurityType SecT>

bool vlink::Node< ImplT, SecT >::is_suspend ( ) const

inlinenodiscard

Returns true if the node is currently suspended.

返回: true while suspend() is in effect.

◆ loan()

template<typename ImplT, SecurityType SecT>

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

inlinenodiscard

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/reply call (which returns the loan automatically) or call return_loan() explicitly. Returns an empty Bytes on failure or if the transport has no loan pool.

参数

size	Requested size in bytes (`0` is valid for empty messages).

返回: Loaned Bytes, or 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 called when the node's status changes.

Only one handler can be registered; subsequent calls replace the previous one. The handler is invoked with a Status::BasePtr describing the new state (e.g. connected, disconnected, error).

参数

callback Callable void(Status::BasePtr) invoked on status changes.

◆ resume()

template<typename ImplT, SecurityType SecT>

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

inline

Resumes message delivery after a suspend().

返回: true if resumption succeeded; false on error.

◆ return_loan()

template<typename ImplT, SecurityType SecT>

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

inline

Returns a previously loaned buffer back to the transport pool.

Must be called if a loaned buffer obtained via loan() is not consumed by a publish/write call. Failing to return a loan can exhaust the shared memory pool.

参数

bytes The loaned Bytes to return.

返回: 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

Enables or disables peer-discovery on this node.

Disabling discovery reduces CPU and network overhead for nodes that never need to locate peers. If called after init(), the transport extension is automatically reinitialised to apply the change.

参数

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

Enables or disables manual-unloan mode for zero-copy receives.

In manual-unloan mode the user is responsible for calling return_loan() after consuming received data. The base implementation logs a warning; only Subscriber and Getter override this method.

参数

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

被 vlink::Getter< ValueT, SecT >, vlink::Getter< ValueT, SecurityType::kWithSecurity >, vlink::Subscriber< MsgT, SecT > , 以及 vlink::Subscriber< MsgT, 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 key-value property on the node.

Provides an extensibility mechanism for back-end-specific tuning knobs that do not have dedicated API methods. Recognised keys depend on the active transport.

参数

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

Sets the filesystem path for message bag recording.

Enables recording of each published/received message to a bag file. Not supported on intra:// or dds:// CDR nodes (triggers fatal log).

参数

path	Path to the recording directory or file.

◆ 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 safety_quit is true, an internal std::mutex is allocated and locked around every callback invocation and around deinit(). Enable this when the node's lifetime is shorter than the callback's scope. There is a small synchronisation overhead; avoid enabling it on hot paths.

参数

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

◆ set_security_callbacks()

template<typename ImplT, SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_security_callbacks	(	Security::Callback &&	encrypt_callback,
		Security::Callback &&	decrypt_callback )

inline

Installs custom encrypt and decrypt callbacks.

Alternative to set_security_key() for custom cipher implementations. Requires SecT == kWithSecurity (enforced by static_assert).

参数

encrypt_callback	`bool(const Bytes& in, Bytes& out)` – encrypts a message, returns true on success.
decrypt_callback	`bool(const Bytes& in, Bytes& out)` – decrypts a message, returns true on success.

◆ set_security_key()

template<typename ImplT, SecurityType SecT>

void vlink::Node< ImplT, SecT >::set_security_key ( const std::string & key )

inline

Sets the symmetric encryption key for message security.

Requires SecT == kWithSecurity (enforced by static_assert). Not supported for intra:// or dds:// CDR nodes (triggers fatal log).

参数

key	Encryption key string; interpretation depends on the security impl.

◆ 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 for this node.

ser_type stores the concrete runtime type identifier, while schema_type stores the coarse decoder family used by discovery, proxy, and bag metadata. When schema_type is SchemaType::kUnknown (the default), the node does not explicitly override the current family; in that mode it keeps the existing protobuf / flatbuffers family unless the new ser_type itself clearly implies kRaw or kZeroCopy. Passing an empty ser_type clears both fields.

If called after init(), the transport extension is restarted once so external metadata stays in sync.

参数

ser_type	Concrete serialisation type identifier, or empty to clear the current metadata.
schema_type	Explicit coarse schema family to expose; default `kUnknown` preserves the current family unless `ser_type` implies a different one.

◆ 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 back-end reads the resulting ssl.* properties during init() to set up a TLS connection. 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 the SslOptions file-level documentation for the per-backend compatibility table.

This call is thread-safe; the property map is updated under a mutex.

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

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 publisher for the VLink event communication model.
定义 publisher.h:102

vlink::InitType::kWithoutInit
@ kWithoutInit
Defer initialisation; call init() manually.
定义 types.h:133

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

vlink::SslOptions::cert_file
std::string cert_file
Path to the client certificate file (PEM format).
定义 ssl_options.h:149

vlink::SslOptions::key_file
std::string key_file
Path to the client private key file (PEM format).
定义 ssl_options.h:158

vlink::SslOptions::ca_file
std::string ca_file
Path to the CA certificate file (PEM format).
定义 ssl_options.h:139

参数

options The SSL/TLS configuration to apply.

参见: SslOptions, set_property()

◆ suspend()

template<typename ImplT, SecurityType SecT>

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

inline

Suspends message delivery on this node.

Behaviour is transport-dependent: some back-ends buffer incoming messages while suspended; others drop them. Pair with resume() to re-enable.

返回: true if suspension succeeded; false on error.

类成员变量说明

◆ 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

◆ security_

template<typename ImplT, SecurityType SecT>

std::optional<Security> vlink::Node< ImplT, SecT >::security_

protected

该类的文档由以下文件生成:

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

Public 类型

Public 成员函数

Protected 成员函数

Protected 属性

详细描述

成员类型定义说明

◆ StatusCallback

构造及析构函数说明

◆ Node()

◆ ~Node()

成员函数说明

◆ attach()

◆ bind_proto_arena()

◆ deinit()

◆ detach()

◆ enable_security()

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

◆ set_security_key()

◆ set_ser_type()

◆ set_ssl_options()

◆ suspend()

类成员变量说明

◆ has_inited_

◆ impl_

◆ is_manual_unloan_

◆ is_support_loan_

◆ proto_arena_

◆ quit_mtx_

◆ security_