Type-safe topic emitter 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 > >
	Owning unique-pointer alias. More...

using	SharedPtr = std::shared_ptr< Publisher< MsgT, SecT > >
	Owning shared-pointer alias. More...

using	ConnectCallback = NodeImpl::ConnectCallback
	Callback type for subscriber presence transitions. More...

Public Types inherited from vlink::Node< PublisherImpl, SecurityType::kWithoutSecurity >
using	StatusCallback = NodeImpl::StatusCallback
	Handler signature for status-change notifications. More...

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. More...

	Publisher (const std::string &url_str, InitType type=InitType::kWithInit)
	Constructs a publisher from a URL string. More...

void	detect_subscribers (ConnectCallback &&callback)
	Registers a callback invoked whenever subscriber presence transitions. More...

bool	wait_for_subscribers (std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Blocks until at least one subscriber is detected or `timeout` expires. More...

bool	has_subscribers () const
	Non-blocking query of subscriber presence. More...

bool	publish (const MsgT &msg, bool force=false)
	Serialises and emits `msg` to every connected subscriber. More...

bool	publish_fbb (const void *fbb, bool force=false)
	Publishes the raw payload of a pre-finished `flatbuffers::FlatBufferBuilder`. More...

void	mark_as_setter ()
	Promotes this publisher to behave as a `Setter` (field-writer) at the transport layer. More...

Public Member Functions inherited from vlink::Node< PublisherImpl, SecurityType::kWithoutSecurity >
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...

Static Public Member Functions
static UniquePtr	create_unique (const std::string &url_str, InitType type=InitType::kWithInit)
	Heap-allocates a `Publisher` and wraps it in a `std::unique_ptr`. More...

static SharedPtr	create_shared (const std::string &url_str, InitType type=InitType::kWithInit)
	Heap-allocates a `Publisher` and wraps it in a `std::shared_ptr`. More...

Static Public Attributes
static constexpr ImplType	kImplType = kPublisher
	Node role tag (`kPublisher`). More...

static constexpr Serializer::Type	kMsgType = Serializer::get_type_of<MsgT>()
	Codec resolved from `MsgT`. More...

Additional Inherited Members
Protected Member Functions inherited from vlink::Node< PublisherImpl, SecurityType::kWithoutSecurity >
	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...

void	invoke_callback (const CallbackT &callback, ArgsT &&... args)

TypeT	get_default_value ()

Protected Attributes inherited from vlink::Node< PublisherImpl, SecurityType::kWithoutSecurity >
void *	proto_arena_

bool	is_support_loan_

bool	is_manual_unloan_

std::atomic_bool	has_inited_

std::optional< std::mutex >	quit_mtx_

std::unique_ptr< PublisherImpl >	impl_

Detailed Description

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

Type-safe topic emitter for the VLink event communication model.

Inherits the full Node API (lifecycle, loans, properties, profiler) and adds publish-specific operations: subscriber detection, blocking wait, and the publish() entry point itself. The transport implementation (PublisherImpl) is selected by the URL scheme or by the typed configuration object supplied at construction time.

Template Parameters

MsgT	C++ message type. Must satisfy `Serializer::is_supported()`.
SecT	Security mode; defaults to `SecurityType::kWithoutSecurity`.

Member Typedef Documentation

◆ ConnectCallback

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

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

Callback type for subscriber presence transitions.

◆ SharedPtr

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

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

Owning shared-pointer alias.

◆ UniquePtr

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

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

Owning unique-pointer alias.

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 (DdsConf, ShmConf, ZenohConf, etc.). A compile-time check enforces that the chosen configuration permits the publisher role. Invalid configuration or a nullptr factory result triggers a fatal log.

Template Parameters

ConfT Concrete configuration type derived from Conf.

Parameters

conf	Populated configuration aggregate.
type	Whether to call `init()` inline; default is `InitType::kWithInit`.

◆ 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 URL scheme selects the transport (e.g. "shm://" maps to the Iceoryx back-end, "dds://" maps to FastDDS). Internally the string is parsed into a Url and dispatched to the matching ConfT.

Parameters

url_str	Topic URL such as `"shm://vehicle/speed"`.
type	Whether to call `init()` inline; default is `InitType::kWithInit`.

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`
	)

inlinestatic

Heap-allocates a Publisher and wraps it in a std::shared_ptr.

Parameters

url_str	Topic URL string.
type	Whether to call `init()` inline; default is `InitType::kWithInit`.

Returns: Owning SharedPtr to the newly constructed publisher.

◆ 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`
	)

inlinestatic

Heap-allocates a Publisher and wraps it in a std::unique_ptr.

Parameters

url_str	Topic URL string, e.g. `"dds://vehicle/speed"`.
type	Whether to call `init()` inline; default is `InitType::kWithInit`.

Returns: Owning UniquePtr to the newly constructed publisher.

◆ detect_subscribers()

template<typename MsgT , SecurityType SecT>

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

inline

Registers a callback invoked whenever subscriber presence transitions.

The callback fires synchronously immediately if a subscriber is already present at registration time, then asynchronously each time the matching subscriber set transitions between empty and non-empty. The boolean is true when at least one peer is present.

Parameters

callback void(bool) callable – true means at least one subscriber.

◆ has_subscribers()

template<typename MsgT , SecurityType SecT>

bool vlink::Publisher< MsgT, SecT >::has_subscribers

inline

Non-blocking query of subscriber presence.

Returns: true when the transport currently knows of at least one matching subscriber.

◆ mark_as_setter()

template<typename MsgT , SecurityType SecT>

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

inline

Promotes this publisher to behave as a Setter (field-writer) at the transport layer.

Switches the underlying impl_type from kPublisher to kSetter so that field-mode semantics (late-joiner sync, latest-value retention) are activated. When called post-init(), the transport extension is reinitialised automatically. 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 emits msg to every connected subscriber.

Serialisation is dispatched to the codec selected by kMsgType. On loan-capable transports the output buffer is a loaned segment in transport-managed memory; the loan is returned automatically once the publish completes. Loans are skipped when SecT == kWithSecurity because the ciphertext size is unknown ahead of encryption.

When force is false (the default) the call is skipped and returns false if no subscribers are present. Pass force=true to write unconditionally, e.g. for bag recording or field-style semantics.

Over intra:// with a message whose element_type derives from IntraDataType (declared via VLINK_INTRA_DATA_DECLARE) the shared pointer is forwarded zero-copy and no serialisation occurs.

Parameters

msg	Message to publish.
force	`true` to publish even when no subscribers are connected.

Returns: true if the transport accepted the message.

Here is the call graph for this function:

◆ publish_fbb()

template<typename MsgT , SecurityType SecT>

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

Publishes the raw payload of a pre-finished flatbuffers::FlatBufferBuilder.

Useful in pipelines where the FlatBuffer is constructed externally and the bytes can be shallow-borrowed without re-serialisation. The pointer must reference a builder on which Finish() has been called.

Parameters

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

Returns: true on success.

◆ 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 detected or timeout expires.

A timeout of 0 is interpreted as infinite (with a warning log). A negative value also waits indefinitely. Calling interrupt() causes the wait to abort and 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>

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

staticconstexpr

Node role tag (kPublisher).

◆ kMsgType

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

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

staticconstexpr

Codec resolved 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

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

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

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