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

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

using	MsgCallback = Function< void(const ValueT &)>
	User callback signature for value updates. More...

Public Types inherited from vlink::Node< GetterImpl, 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>>>
	Getter (const ConfT &conf, InitType type=InitType::kWithInit)
	Constructs a getter from a typed transport configuration object. More...

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

	~Getter () override
	Destroys the getter and drains in-flight transport callbacks. More...

std::optional< ValueT >	get () const
	Returns the most recent cached value, if any has been received. More...

bool	wait_for_value (std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Blocks until a value is received or `timeout` expires. More...

bool	listen (MsgCallback &&callback)
	Installs a callback invoked whenever a new value arrives. More...

void	set_change_reporting (bool enable)
	Toggles change-only reporting (duplicate suppression). More...

void	set_manual_unloan (bool manual_unloan) override
	Enables or disables manual-unloan mode for zero-copy receives. More...

void	set_latency_and_lost_enabled (bool enable)
	Toggles per-value latency and sample-loss measurement. More...

bool	is_latency_and_lost_enabled () const
	Reports whether latency and sample-loss tracking is currently active. More...

int64_t	get_latency () const
	Returns the most recent end-to-end latency measurement. More...

SampleLostInfo	get_lost () const
	Returns cumulative sample-delivery statistics. More...

bool	get_change_reporting () const
	Reports whether change-only reporting is currently active. More...

bool	init () override
	Initialises the getter and installs the internal delivery hook. More...

void	interrupt () override
	Aborts any blocking `wait_for_value()` call. More...

void	mark_as_subscriber ()
	Promotes this getter to behave as a `Subscriber` at the transport layer. More...

Public Member Functions inherited from vlink::Node< GetterImpl, SecurityType::kWithoutSecurity >
virtual bool	deinit ()
	Tears the node down and releases all transport resources. 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 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 `Getter` 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 `Getter` and wraps it in a `std::shared_ptr`. More...

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

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

Additional Inherited Members
Protected Member Functions inherited from vlink::Node< GetterImpl, 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< GetterImpl, 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< GetterImpl >	impl_

Detailed Description

template<typename ValueT, SecurityType SecT = SecurityType::kWithoutSecurity>
class vlink::Getter< ValueT, SecT >

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

Inherits the full Node API and adds field-specific operations: cached get(), blocking wait_for_value(), single-shot listen() callback, change-reporting filter, and latency / sample-loss tracking.

Template Parameters

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

Member Typedef Documentation

◆ MsgCallback

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

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

User callback signature for value updates.

◆ SharedPtr

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

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

Owning shared-pointer alias.

◆ UniquePtr

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

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

Owning 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 Concrete configuration type derived from Conf.

Parameters

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

◆ 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 such as `"shm://vehicle/gear"`.
type	Whether to call `init()` inline; default is `InitType::kWithInit`.

◆ ~Getter()

template<typename ValueT , SecurityType SecT>

vlink::Getter< ValueT, SecT >::~Getter

inlineoverride

Destroys the getter and drains in-flight transport callbacks.

Required so the internal delivery callback installed by init() cannot fire on the transport thread after this getter's mutex and value have already been destroyed.

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

inlinestatic

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

Parameters

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

Returns: Owning SharedPtr to 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`
	)

inlinestatic

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

Parameters

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

Returns: Owning UniquePtr to the new getter.

◆ get()

template<typename ValueT , SecurityType SecT>

std::optional< ValueT > vlink::Getter< ValueT, SecT >::get

inline

Returns the most recent cached value, if any has been received.

Thread-safe. Returns std::nullopt before the first matching Setter write reaches this getter.

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

◆ get_change_reporting()

template<typename ValueT , SecurityType SecT>

bool vlink::Getter< ValueT, SecT >::get_change_reporting

inline

Reports whether change-only reporting 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

inline

Returns the most recent end-to-end latency measurement.

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

◆ get_lost()

template<typename ValueT , SecurityType SecT>

SampleLostInfo vlink::Getter< ValueT, SecT >::get_lost

inline

Returns cumulative sample-delivery statistics.

Returns: SampleLostInfo with total expected and total lost counts.

◆ init()

template<typename ValueT , SecurityType SecT>

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

inlineoverridevirtual

Initialises the getter and installs the internal delivery hook.

Overrides Node::init() to additionally register a bytes-level callback that deserialises each delivery, invokes the user listen() callback (if installed), then updates value_ and wakes the condition variable used by wait_for_value().

Returns: true on first successful initialisation; false otherwise.

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

◆ interrupt()

template<typename ValueT , SecurityType SecT>

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

inlineoverridevirtual

Aborts any blocking wait_for_value() call.

Overrides Node::interrupt() to additionally notify the local condition variable so that the blocking wait returns false promptly.

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

◆ is_latency_and_lost_enabled()

template<typename ValueT , SecurityType SecT>

bool vlink::Getter< ValueT, SecT >::is_latency_and_lost_enabled

inline

Reports whether latency and sample-loss tracking is currently active.

Returns: true if set_latency_and_lost_enabled(true) was invoked.

◆ listen()

template<typename ValueT , SecurityType SecT>

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

inline

Installs a callback invoked whenever a new value arrives.

The callback receives a deserialised ValueT reference. It runs for every setter write unless set_change_reporting(true) is active, in which case duplicate consecutive payloads are filtered out. Internally the getter first fires the callback, then updates value_ and wakes wait_for_value().

Note: Calling listen() more than once is fatal.

Parameters

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

Returns: true on successful installation; a second call is fatal and never returns.

◆ mark_as_subscriber()

template<typename ValueT , SecurityType SecT>

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

inline

Promotes this getter to behave as a Subscriber at the transport layer.

Switches impl_type from kGetter to kSubscriber so that event-style semantics (no latest-value retention) are applied. Reinitialises the transport extension if called post-init(). Used when bridging a getter through event-only transports.

◆ set_change_reporting()

template<typename ValueT , SecurityType SecT>

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

inline

Toggles change-only reporting (duplicate suppression).

When enabled, incoming payloads whose raw serialised bytes match the previous delivery are dropped before any caching or callback dispatch. Useful when a Setter repeatedly writes the same value.

Parameters

enable true to suppress duplicates; false (default) to deliver all.

◆ set_latency_and_lost_enabled()

template<typename ValueT , SecurityType SecT>

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

inline

Toggles per-value latency and sample-loss measurement.

Parameters

enable true to begin 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 manual return; false for auto-return.

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 timeout expires.

Returns immediately if a value is already cached. A timeout of 0 is treated as infinite (with a warning). interrupt() causes the wait to abort and return false. Use get() afterwards to retrieve the value when this method returns true.

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>

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

staticconstexpr

Node role tag (kGetter).

◆ kValueType

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

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

staticconstexpr

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

template<typename ValueT, SecurityType SecT = SecurityType::kWithoutSecurity> class vlink::Getter< ValueT, SecT >

Member Typedef Documentation

◆ MsgCallback

◆ SharedPtr

◆ UniquePtr

Constructor & Destructor Documentation

◆ Getter() [1/2]

◆ Getter() [2/2]

◆ ~Getter()

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

template<typename ValueT, SecurityType SecT = SecurityType::kWithoutSecurity>
class vlink::Getter< ValueT, SecT >