Type-safe subscriber for the VLink event communication model. More...

#include <subscriber.h>

Inheritance diagram for vlink::Subscriber< MsgT, SecT >:

Collaboration diagram for vlink::Subscriber< MsgT, SecT >:

Public Types
using	UniquePtr = std::unique_ptr<Subscriber<MsgT, SecT>>
	Unique-pointer alias for heap allocation.
using	SharedPtr = std::shared_ptr<Subscriber<MsgT, SecT>>
	Shared-pointer alias for heap allocation.
using	MsgCallback = std::function<void(const MsgT&)>
	User-facing callback type for received messages.
Public Types inherited from vlink::Node< SubscriberImpl, SecurityType::kWithoutSecurity >
using	StatusCallback
	Callback type for node status-change notifications.

Public Member Functions
template<typename ConfT, typename = std::enable_if_t<std::is_base_of_v<Conf, ConfT>>>
	Subscriber (const ConfT &conf, InitType type=InitType::kWithInit)
	Constructs a subscriber from a typed transport configuration object.
	Subscriber (const std::string &url_str, InitType type=InitType::kWithInit)
	Constructs a subscriber from a URL string.
bool	listen (MsgCallback &&callback)
	Registers the receive callback for incoming messages.
void	set_manual_unloan (bool manual_unloan) override
	Enables or disables manual-unloan mode for zero-copy receives.
void	set_latency_and_lost_enabled (bool enable)
	Enables or disables per-message latency and sample-loss tracking.
bool	is_latency_and_lost_enabled () const
	Returns `true` if latency and sample-loss tracking is active.
int64_t	get_latency () const
	Returns the most recently measured end-to-end message latency.
SampleLostInfo	get_lost () const
	Returns cumulative sample delivery statistics.
void	mark_as_getter ()
	Changes this subscriber's role to `kGetter` (field-reader).
Public Member Functions inherited from vlink::Node< SubscriberImpl, SecurityType::kWithoutSecurity >
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 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.

Static Public Member Functions
static UniquePtr	create_unique (const std::string &url_str, InitType type=InitType::kWithInit)
	Creates a `Subscriber` on the heap wrapped in a `unique_ptr`.
static SharedPtr	create_shared (const std::string &url_str, InitType type=InitType::kWithInit)
	Creates a `Subscriber` on the heap wrapped in a `shared_ptr`.

Static Public Attributes
static constexpr ImplType	kImplType = kSubscriber
	Node role identifier (`kSubscriber`).
static constexpr Serializer::Type	kMsgType = Serializer::get_type_of<MsgT>()
	Serializer type resolved at compile time from `MsgT`.

Additional Inherited Members
Protected Member Functions inherited from vlink::Node< SubscriberImpl, SecurityType::kWithoutSecurity >
	Node ()
virtual	~Node ()
void	enable_security ()
void	invoke_callback (const CallbackT &callback, ArgsT &&... args)
TypeT	get_default_value ()
Protected Attributes inherited from vlink::Node< SubscriberImpl, SecurityType::kWithoutSecurity >
std::atomic_bool	has_inited_
std::unique_ptr< SubscriberImpl >	impl_
std::optional< Security >	security_
std::optional< std::mutex >	quit_mtx_
void *	proto_arena_
bool	is_support_loan_
bool	is_manual_unloan_

Detailed Description

template<typename MsgT, SecurityType SecT = SecurityType::kWithoutSecurity>
class vlink::Subscriber< MsgT, SecT >

Type-safe subscriber for the VLink event communication model.

Template Parameters

MsgT	Message type.
SecT	Security mode.

Member Typedef Documentation

◆ MsgCallback

template<typename MsgT, SecurityType SecT = SecurityType::kWithoutSecurity>

using vlink::Subscriber< MsgT, SecT >::MsgCallback = std::function<void(const MsgT&)>

User-facing callback type for received messages.

◆ SharedPtr

template<typename MsgT, SecurityType SecT = SecurityType::kWithoutSecurity>

using vlink::Subscriber< MsgT, SecT >::SharedPtr = std::shared_ptr<Subscriber<MsgT, SecT>>

Shared-pointer alias for heap allocation.

◆ UniquePtr

template<typename MsgT, SecurityType SecT = SecurityType::kWithoutSecurity>

using vlink::Subscriber< MsgT, SecT >::UniquePtr = std::unique_ptr<Subscriber<MsgT, SecT>>

Unique-pointer alias for heap allocation.

Constructor & Destructor Documentation

◆ Subscriber() [1/2]

template<typename MsgT, SecurityType SecT>

template<typename ConfT, typename>

vlink::Subscriber< MsgT, SecT >::Subscriber	(	const ConfT &	conf,
		InitType	type = InitType::kWithInit )

inlineexplicit

Constructs a subscriber from a typed transport configuration object.

Accepts any Conf-derived configuration (e.g. DdsConf, ShmConf). A compile-time static_assert verifies the configuration supports the subscriber role.

Template Parameters

ConfT Conf-derived configuration type.

Parameters

conf	Populated configuration object.
type	`kWithInit` to call `init()` immediately (default).

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Subscriber() [2/2]

template<typename MsgT, SecurityType SecT>

vlink::Subscriber< MsgT, SecT >::Subscriber	(	const std::string &	url_str,
		InitType	type = InitType::kWithInit )

inlineexplicit

Constructs a subscriber from a URL string.

Parameters

url_str	Topic URL (e.g. `"shm://vehicle/speed"`).
type	`kWithInit` to call `init()` immediately (default).

Here is the call graph for this function:

Member Function Documentation

◆ create_shared()

template<typename MsgT, SecurityType SecT>

Subscriber< MsgT, SecT >::SharedPtr vlink::Subscriber< MsgT, SecT >::create_shared	(	const std::string &	url_str,
		InitType	type = InitType::kWithInit )

inlinestaticnodiscard

Creates a Subscriber on the heap wrapped in a shared_ptr.

Parameters

url_str	Topic URL string.
type	`kWithInit` to call `init()` immediately (default).

Returns: SharedPtr owning the new subscriber.

◆ create_unique()

template<typename MsgT, SecurityType SecT>

Subscriber< MsgT, SecT >::UniquePtr vlink::Subscriber< MsgT, SecT >::create_unique	(	const std::string &	url_str,
		InitType	type = InitType::kWithInit )

inlinestaticnodiscard

Creates a Subscriber on the heap wrapped in a unique_ptr.

Parameters

url_str	Topic URL string (e.g. `"dds://vehicle/speed"`).
type	`kWithInit` to call `init()` immediately (default).

Returns: UniquePtr owning the new subscriber.

◆ get_latency()

template<typename MsgT, SecurityType SecT>

int64_t vlink::Subscriber< MsgT, SecT >::get_latency ( ) const

inlinenodiscard

Returns the most recently measured end-to-end message latency.

Only meaningful when tracking is enabled. Measured from publication timestamp to receive timestamp.

Returns: Latency in microseconds; 0 if tracking is disabled.

◆ get_lost()

template<typename MsgT, SecurityType SecT>

SampleLostInfo vlink::Subscriber< MsgT, SecT >::get_lost ( ) const

inlinenodiscard

Returns cumulative sample delivery statistics.

Only meaningful when tracking is enabled.

Returns: SampleLostInfo with total expected and lost sample counts.

◆ is_latency_and_lost_enabled()

template<typename MsgT, SecurityType SecT>

bool vlink::Subscriber< MsgT, SecT >::is_latency_and_lost_enabled ( ) const

inlinenodiscard

Returns true if latency and sample-loss tracking is active.

Returns: true if set_latency_and_lost_enabled(true) was called.

◆ listen()

template<typename MsgT, SecurityType SecT>

bool vlink::Subscriber< MsgT, SecT >::listen ( MsgCallback && callback )

inline

Registers the receive callback for incoming messages.

The callback is invoked on every delivery, already deserialized into MsgT. For intra:// with an IntraDataType-derived shared pointer type (generated via VLINK_INTRA_DATA_DECLARE) the pointer is forwarded zero-copy. The callback runs on the transport thread unless the node is attach()ed to a MessageLoop.

Calling listen() more than once is a fatal error.

Warning: The deserialized message object is thread_local and reused across invocations. Do not store references or pointers to the callback argument beyond the callback scope; copy the data if you need to retain it. This does not apply to Bytes or IntraData message types, which are passed by value/shared pointer.

Note: The subscriber must be initialised (either via kWithInit in the constructor or by calling init() explicitly) before listen() is called. Calling listen() on an uninitialised subscriber triggers a fatal error.

Parameters

callback void(const MsgT&) invoked for each received message.

Returns: true if registered successfully; false on error.

Here is the call graph for this function:

◆ mark_as_getter()

template<typename MsgT, SecurityType SecT>

void vlink::Subscriber< MsgT, SecT >::mark_as_getter ( )

inline

Changes this subscriber's role to kGetter (field-reader).

Updates impl_->impl_type from kSubscriber to kGetter so that transport-specific field semantics (latest-value delivery) are applied. If called after init(), the extension is automatically reinitialised. Used internally by Getter.

◆ set_latency_and_lost_enabled()

template<typename MsgT, SecurityType SecT>

void vlink::Subscriber< MsgT, SecT >::set_latency_and_lost_enabled ( bool enable )

inline

Enables or disables per-message latency and sample-loss tracking.

Parameters

enable true to start tracking; false to stop.

◆ set_manual_unloan()

template<typename MsgT, SecurityType SecT>

void vlink::Subscriber< MsgT, SecT >::set_manual_unloan ( bool manual_unloan )

inlineoverridevirtual

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

When enabled, the user must call return_loan() after consuming a received loaned buffer. Only meaningful on loan-capable transports (e.g. shm://).

Parameters

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

Reimplemented from vlink::Node< SubscriberImpl, SecurityType::kWithoutSecurity >.

Member Data Documentation

◆ kImplType

template<typename MsgT, SecurityType SecT = SecurityType::kWithoutSecurity>

ImplType vlink::Subscriber< MsgT, SecT >::kImplType = kSubscriber

staticconstexpr

Node role identifier (kSubscriber).

◆ kMsgType

template<typename MsgT, SecurityType SecT = SecurityType::kWithoutSecurity>

Serializer::Type vlink::Subscriber< MsgT, SecT >::kMsgType = Serializer::get_type_of<MsgT>()

staticconstexpr

Serializer type resolved at compile time from MsgT.

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

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

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ MsgCallback

◆ SharedPtr

◆ UniquePtr

Constructor & Destructor Documentation

◆ Subscriber() [1/2]

◆ Subscriber() [2/2]

Member Function Documentation

◆ create_shared()

◆ create_unique()

◆ get_latency()

◆ get_lost()

◆ is_latency_and_lost_enabled()

◆ listen()

◆ mark_as_getter()

◆ set_latency_and_lost_enabled()

◆ set_manual_unloan()

Member Data Documentation

◆ kImplType

◆ kMsgType