|
VLink 2.0.0
A high-performance communication middleware
|
Transport-agnostic CRTP base for all VLink communication nodes. More...
#include <node.h>
Public Types | |
| using | StatusCallback = NodeImpl::StatusCallback |
| Callback type for node status-change notifications. | |
Public Member Functions | |
| 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 Member Functions | |
| 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 Attributes | |
| 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} |
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). |
| using vlink::Node< ImplT, SecT >::StatusCallback = NodeImpl::StatusCallback |
Callback type for node status-change notifications.
|
inlineprotected |
|
inlineprotectedvirtual |
|
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.
|
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*). |
|
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. Reimplemented in vlink::Setter< ValueT, SecT >, and vlink::Setter< ValueT, SecurityType::kWithSecurity >.
|
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.
|
inlineprotected |
|
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.
AbstractNode, or nullptr if the transport back-end does not expose an AbstractNode.
|
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.
-1.0 if unavailable.
|
inlineprotected |
|
inlinenodiscard |
Returns true if peer-discovery is currently enabled.
true if discovery is active.
|
inlinenodiscard |
Returns the MessageLoop this node is attached to.
MessageLoop, or nullptr.
|
inlinenodiscard |
Retrieves a transport-specific property value.
| prop | Property key string. |
|
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.
|
inlinenodiscard |
Returns the current coarse schema family.
|
inlinenodiscard |
Returns the current serialisation type string.
|
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. |
Status::Unknown when the transport does not support the query.
|
inlinenodiscard |
Returns the TransportType of the transport this node is bound to.
kDds, kShm, kIntra, etc.
|
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.
"dds://vehicle/speed").
|
inlinenodiscard |
Returns true if init() has been successfully called.
true when the node is in the initialised state.
|
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. Reimplemented in vlink::Getter< ValueT, SecT >, vlink::Getter< ValueT, SecurityType::kWithSecurity >, vlink::Setter< ValueT, SecT >, and vlink::Setter< ValueT, SecurityType::kWithSecurity >.
|
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.
Reimplemented in vlink::Getter< ValueT, SecT >, and vlink::Getter< ValueT, SecurityType::kWithSecurity >.
|
inlineprotected |
|
inlinenodiscardvirtual |
Returns true if manual-unloan mode is active.
true if set_manual_unloan(true) was called.
|
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.
|
inlinenodiscard |
Returns true if the node is currently suspended.
true while suspend() is in effect.
|
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). |
|
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. |
|
inline |
Resumes message delivery after a suspend().
true if resumption succeeded; false on error.
|
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.
|
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. |
|
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). |
Reimplemented in vlink::Getter< ValueT, SecT >, vlink::Getter< ValueT, SecurityType::kWithSecurity >, vlink::Subscriber< MsgT, SecT >, and vlink::Subscriber< MsgT, SecurityType::kWithSecurity >.
|
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. |
|
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. |
|
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). |
|
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. |
|
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. |
|
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. |
|
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.
| options | The SSL/TLS configuration to apply. |
|
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.
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |