Type-safe field reader for the VLink field communication model. More...

#include <getter.h>

Inheritance diagram for vlink::Getter< ValueT, SecT >:

Collaboration diagram for vlink::Getter< ValueT, SecT >:

Public Types
using	UniquePtr = std::unique_ptr<Getter<ValueT, SecT>>
	Unique-pointer alias.
using	SharedPtr = std::shared_ptr<Getter<ValueT, SecT>>
	Shared-pointer alias.
using	MsgCallback = std::function<void(const ValueT&)>
	User-facing callback type for value-change notifications.
Public Types inherited from vlink::Node< GetterImpl, 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>>>
	Getter (const ConfT &conf, InitType type=InitType::kWithInit)
	Constructs a getter from a typed transport configuration object.
	Getter (const std::string &url_str, InitType type=InitType::kWithInit)
	Constructs a getter from a URL string.
std::optional< ValueT >	get () const
	Returns the latest cached value, if one has been received.
bool	wait_for_value (std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Blocks until a value is received or the timeout expires.
bool	listen (MsgCallback &&callback)
	Registers a callback invoked whenever a new value arrives.
void	set_change_reporting (bool enable)
	Enables or disables change-reporting (suppress duplicate values).
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-value 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 value latency.
SampleLostInfo	get_lost () const
	Returns cumulative sample delivery statistics.
bool	get_change_reporting () const
	Returns `true` if change-reporting mode is currently active.
bool	init () override
	Initialises the getter and registers the internal delivery callback.
void	interrupt () override
	Interrupts any blocking `wait_for_value()` call.
void	mark_as_subscriber ()
	Changes this getter's role to `kSubscriber` (event-receiver).
Public Member Functions inherited from vlink::Node< GetterImpl, SecurityType::kWithoutSecurity >
virtual bool	deinit ()
	Shuts down the node and releases all transport resources.
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 `Getter` on the heap wrapped in a `unique_ptr`.
static SharedPtr	create_shared (const std::string &url_str, InitType type=InitType::kWithInit)
	Creates a `Getter` on the heap wrapped in a `shared_ptr`.

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

Additional Inherited Members
Protected Member Functions inherited from vlink::Node< GetterImpl, 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< GetterImpl, SecurityType::kWithoutSecurity >
std::atomic_bool	has_inited_
std::unique_ptr< GetterImpl >	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 ValueT, SecurityType SecT = SecurityType::kWithoutSecurity>
class vlink::Getter< ValueT, SecT >

Type-safe field reader for the VLink field communication model.

Template Parameters

ValueT	Value type to read.
SecT	Security mode.

Member Typedef Documentation

◆ MsgCallback

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

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

User-facing callback type for value-change notifications.

◆ SharedPtr

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

using vlink::Getter< ValueT, SecT >::SharedPtr = std::shared_ptr<Getter<ValueT, SecT>>

Shared-pointer alias.

◆ UniquePtr

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

using vlink::Getter< ValueT, SecT >::UniquePtr = std::unique_ptr<Getter<ValueT, SecT>>

Unique-pointer alias.

Constructor & Destructor Documentation

◆ Getter() [1/2]

template<typename ValueT, SecurityType SecT>

template<typename ConfT, typename>

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

inlineexplicit

Constructs a getter from a typed transport configuration object.

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:

◆ Getter() [2/2]

template<typename ValueT, SecurityType SecT>

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

inlineexplicit

Constructs a getter from a URL string.

Parameters

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

Here is the call graph for this function:

Member Function Documentation

◆ create_shared()

template<typename ValueT, SecurityType SecT>

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

inlinestaticnodiscard

Creates a Getter on the heap wrapped in a shared_ptr.

Parameters

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

Returns: SharedPtr owning the new getter.

◆ create_unique()

template<typename ValueT, SecurityType SecT>

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

inlinestaticnodiscard

Creates a Getter on the heap wrapped in a unique_ptr.

Parameters

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

Returns: UniquePtr owning the new getter.

◆ get()

template<typename ValueT, SecurityType SecT>

std::optional< ValueT > vlink::Getter< ValueT, SecT >::get ( ) const

inlinenodiscard

Returns the latest cached value, if one has been received.

Thread-safe. Returns std::nullopt if no Setter has written a value yet since this getter was initialised.

Returns: std::optional<ValueT> – holds the latest value, or empty.

◆ get_change_reporting()

template<typename ValueT, SecurityType SecT>

bool vlink::Getter< ValueT, SecT >::get_change_reporting ( ) const

inlinenodiscard

Returns true if change-reporting mode is currently active.

Returns: true if duplicate suppression is enabled.

◆ get_latency()

template<typename ValueT, SecurityType SecT>

int64_t vlink::Getter< ValueT, SecT >::get_latency ( ) const

inlinenodiscard

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

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

◆ get_lost()

template<typename ValueT, SecurityType SecT>

SampleLostInfo vlink::Getter< ValueT, SecT >::get_lost ( ) const

inlinenodiscard

Returns cumulative sample delivery statistics.

Returns: SampleLostInfo with total expected and lost value counts.

◆ init()

template<typename ValueT, SecurityType SecT>

bool vlink::Getter< ValueT, SecT >::init ( )

inlineoverridevirtual

Initialises the getter and registers the internal delivery callback.

Overrides Node::init() to also set up the internal listen_bytes() callback that receives raw bytes, deserialises them into ValueT, stores the result in value_, and fires the user listen() callback.

Returns: true on success; false if already initialised.

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ interrupt()

template<typename ValueT, SecurityType SecT>

void vlink::Getter< ValueT, SecT >::interrupt ( )

inlineoverridevirtual

Interrupts any blocking wait_for_value() call.

Overrides Node::interrupt() to additionally notify the getter's own condition variable, causing wait_for_value() to return false.

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

Here is the call graph for this function:

◆ is_latency_and_lost_enabled()

template<typename ValueT, SecurityType SecT>

bool vlink::Getter< ValueT, 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 ValueT, SecurityType SecT>

bool vlink::Getter< ValueT, SecT >::listen ( MsgCallback && callback )

inline

Registers a callback invoked whenever a new value arrives.

The callback receives a pre-deserialized ValueT reference. It is invoked on every setter write unless set_change_reporting(true) is active, in which case duplicate values (same raw bytes as the last) are suppressed before the callback is called.

Internally, Getter also maintains value_ and notifies wait_for_value(). The listen callback is stored once; calling listen() more than once is a fatal error.

Parameters

callback void(const ValueT&) invoked on each new value.

Returns: true always (registration is deferred to init()).

◆ mark_as_subscriber()

template<typename ValueT, SecurityType SecT>

void vlink::Getter< ValueT, SecT >::mark_as_subscriber ( )

inline

Changes this getter's role to kSubscriber (event-receiver).

Updates impl_->impl_type from kGetter to kSubscriber so that transport-specific event semantics are applied. If called after init(), the extension is automatically reinitialised. Used internally when routing a Getter through an event-capable transport.

◆ set_change_reporting()

template<typename ValueT, SecurityType SecT>

void vlink::Getter< ValueT, SecT >::set_change_reporting ( bool enable )

inline

Enables or disables change-reporting (suppress duplicate values).

When true, incoming values whose raw serialized bytes are identical to the previous delivery are silently dropped – neither the callback nor wait_for_value() is notified. Useful for reducing CPU load when a Setter writes the same value repeatedly.

Parameters

enable true to enable change-only reporting; false to disable.

◆ set_latency_and_lost_enabled()

template<typename ValueT, SecurityType SecT>

void vlink::Getter< ValueT, SecT >::set_latency_and_lost_enabled ( bool enable )

inline

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

Parameters

enable true to start tracking; false to stop.

◆ set_manual_unloan()

template<typename ValueT, SecurityType SecT>

void vlink::Getter< ValueT, SecT >::set_manual_unloan ( bool manual_unloan )

inlineoverridevirtual

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

Parameters

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

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

◆ wait_for_value()

template<typename ValueT, SecurityType SecT>

bool vlink::Getter< ValueT, SecT >::wait_for_value ( std::chrono::milliseconds timeout = Timeout::kDefaultInterval )

inline

Blocks until a value is received or the timeout expires.

Returns immediately if a value is already available. A timeout of 0 is treated as infinite (a warning is logged). Can be interrupted by interrupt(), which causes this method to return false.

After returning true, call get() to retrieve the value.

Parameters

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

Returns: true if a value was received; false on timeout or interrupt.

Member Data Documentation

◆ kImplType

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

ImplType vlink::Getter< ValueT, SecT >::kImplType = kGetter

staticconstexpr

Node role identifier (kGetter).

◆ kValueType

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

Serializer::Type vlink::Getter< ValueT, SecT >::kValueType = Serializer::get_type_of<ValueT>()

staticconstexpr

Serializer type resolved at compile time from ValueT.

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

include/vlink/getter.h
include/vlink/internal/getter-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

◆ Getter() [1/2]

◆ Getter() [2/2]

Member Function Documentation

◆ create_shared()

◆ create_unique()

◆ get()

◆ get_change_reporting()

◆ get_latency()

◆ get_lost()

◆ init()

◆ interrupt()

◆ is_latency_and_lost_enabled()

◆ listen()

◆ mark_as_subscriber()

◆ set_change_reporting()

◆ set_latency_and_lost_enabled()

◆ set_manual_unloan()

◆ wait_for_value()

Member Data Documentation

◆ kImplType

◆ kValueType