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

#include <publisher.h>

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

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

Public Types
using	UniquePtr = std::unique_ptr<Publisher<MsgT, SecT>>
	Unique-pointer alias for heap allocation.
using	SharedPtr = std::shared_ptr<Publisher<MsgT, SecT>>
	Shared-pointer alias for heap allocation.
using	ConnectCallback = NodeImpl::ConnectCallback
	Callback type fired when subscriber presence changes.
Public Types inherited from vlink::Node< PublisherImpl, 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>>>
	Publisher (const ConfT &conf, InitType type=InitType::kWithInit)
	Constructs a publisher from a typed transport configuration object.
	Publisher (const std::string &url_str, InitType type=InitType::kWithInit)
	Constructs a publisher from a URL string.
void	detect_subscribers (ConnectCallback &&callback)
	Registers a callback invoked when subscriber presence changes.
bool	wait_for_subscribers (std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Blocks until at least one subscriber is present or the timeout expires.
bool	has_subscribers () const
	Returns `true` if at least one subscriber is currently present.
bool	publish (const MsgT &msg, bool force=false)
	Serialises and publishes `msg` to all current subscribers.
bool	publish_fbb (const void *fbb, bool force=false)
	Publishes a pre-finished `FlatBufferBuilder` buffer directly.
void	mark_as_setter ()
	Changes this publisher's role to `kSetter` (field-writer).
Public Member Functions inherited from vlink::Node< PublisherImpl, 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 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.

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

Static Public Attributes
static constexpr ImplType	kImplType = kPublisher
	Node role identifier (`kPublisher`).
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< PublisherImpl, 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< PublisherImpl, SecurityType::kWithoutSecurity >
std::atomic_bool	has_inited_
std::unique_ptr< PublisherImpl >	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::Publisher< MsgT, SecT >

Type-safe publisher for the VLink event communication model.

Template Parameters

MsgT	Message type.
SecT	Security mode.

Member Typedef Documentation

◆ ConnectCallback

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

using vlink::Publisher< MsgT, SecT >::ConnectCallback = NodeImpl::ConnectCallback

Callback type fired when subscriber presence changes.

◆ SharedPtr

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

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

Shared-pointer alias for heap allocation.

◆ UniquePtr

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

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

Unique-pointer alias for heap allocation.

Constructor & Destructor Documentation

◆ Publisher() [1/2]

template<typename MsgT, SecurityType SecT>

template<typename ConfT, typename>

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

inlineexplicit

Constructs a publisher from a typed transport configuration object.

Accepts any Conf-derived configuration (e.g. DdsConf, ShmConf). A compile-time static_assert checks that the Conf supports the publisher role. Parses and validates the conf; logs a fatal error if the conf is invalid or if the transport factory returns nullptr.

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:

◆ Publisher() [2/2]

template<typename MsgT, SecurityType SecT>

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

inlineexplicit

Constructs a publisher from a URL string.

The transport prefix in the URL selects the transport back-end automatically (e.g. "shm://" => Iceoryx, "dds://" => FastDDS). Internally wraps the string in a Url object and delegates to the ConfT constructor.

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>

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

inlinestaticnodiscard

Creates a Publisher 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 publisher instance.

◆ create_unique()

template<typename MsgT, SecurityType SecT>

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

inlinestaticnodiscard

Creates a Publisher 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 publisher instance.

◆ detect_subscribers()

template<typename MsgT, SecurityType SecT>

void vlink::Publisher< MsgT, SecT >::detect_subscribers ( ConnectCallback && callback )

inline

Registers a callback invoked when subscriber presence changes.

Fires immediately (synchronously) if a subscriber is already present at registration time. Otherwise fires asynchronously the first time a subscriber appears. The callback receives true when at least one subscriber is present and false when the last subscriber disconnects.

Parameters

callback void(bool) callable – true = subscriber(s) present.

◆ has_subscribers()

template<typename MsgT, SecurityType SecT>

bool vlink::Publisher< MsgT, SecT >::has_subscribers ( ) const

inlinenodiscard

Returns true if at least one subscriber is currently present.

Non-blocking poll; reflects the transport's last known peer state.

Returns: true when one or more subscribers are known to exist.

◆ mark_as_setter()

template<typename MsgT, SecurityType SecT>

void vlink::Publisher< MsgT, SecT >::mark_as_setter ( )

inline

Changes this publisher's role to kSetter (field-writer).

Updates impl_->impl_type from kPublisher to kSetter so that transport-specific field semantics are applied (e.g. last-value retention for late-joining getters). If called after init() the extension is automatically reinitialised. Used internally by Setter.

◆ publish()

template<typename MsgT, SecurityType SecT>

bool vlink::Publisher< MsgT, SecT >::publish	(	const MsgT &	msg,
		bool	force = false )

inline

Serialises and publishes msg to all current subscribers.

Serialization is performed according to kMsgType. On loan-capable transports (e.g. shm://) the output buffer is a loaned segment to avoid an extra copy. Loaned buffers are not used when security is enabled (kWithSecurity) because the encrypted payload size differs from the serialized size.

By default (force = false) the call is a no-op when no subscribers are present; pass true to force-write regardless (useful for field-mode or recording-only scenarios).

For intra:// with a message type whose element_type derives from IntraDataType (generated via VLINK_INTRA_DATA_DECLARE), the pointer is forwarded zero-copy and no serialization occurs.

Parameters

msg	Message value to publish.
force	`true` to publish even with no subscribers.

Returns: true if the transport accepted the message; false on error.

◆ publish_fbb()

template<typename MsgT, SecurityType SecT>

bool vlink::Publisher< MsgT, SecT >::publish_fbb	(	const void *	fbb,
		bool	force = false )

Publishes a pre-finished FlatBufferBuilder buffer directly.

Accepts a pointer to a flatbuffers::FlatBufferBuilder whose Finish() has already been called. The raw bytes are shallow-copied and sent without re-serialisation. Useful in pipeline scenarios where the FlatBuffers object is constructed externally.

Parameters

fbb	Pointer to a finished `flatbuffers::FlatBufferBuilder`.
force	`true` to publish even with no subscribers.

Returns: true on success; false on error.

◆ wait_for_subscribers()

template<typename MsgT, SecurityType SecT>

bool vlink::Publisher< MsgT, SecT >::wait_for_subscribers ( std::chrono::milliseconds timeout = Timeout::kDefaultInterval )

inline

Blocks until at least one subscriber is present or the timeout expires.

A timeout of 0 is treated as infinite (a warning is logged). A negative timeout also waits indefinitely. Can be interrupted by calling interrupt(), which causes this method to return false.

Parameters

timeout Maximum wait duration. Default: Timeout::kDefaultInterval.

Returns: true if a subscriber appeared; false on timeout or interrupt.

Member Data Documentation

◆ kImplType

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

ImplType vlink::Publisher< MsgT, SecT >::kImplType = kPublisher

staticconstexpr

Node role identifier (kPublisher).

◆ kMsgType

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

Serializer::Type vlink::Publisher< 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/publisher.h
include/vlink/internal/publisher-inl.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ConnectCallback

◆ SharedPtr

◆ UniquePtr

Constructor & Destructor Documentation

◆ Publisher() [1/2]

◆ Publisher() [2/2]

Member Function Documentation

◆ create_shared()

◆ create_unique()

◆ detect_subscribers()

◆ has_subscribers()

◆ mark_as_setter()

◆ publish()

◆ publish_fbb()

◆ wait_for_subscribers()

Member Data Documentation

◆ kImplType

◆ kMsgType