Type-safe client for the VLink method (RPC) communication model. More...

#include <client.h>

Inheritance diagram for vlink::Client< ReqT, RespT, SecT >:

Collaboration diagram for vlink::Client< ReqT, RespT, SecT >:

Public Types
using	UniquePtr = std::unique_ptr<Client<ReqT, RespT, SecT>>
	Unique-pointer alias.
using	SharedPtr = std::shared_ptr<Client<ReqT, RespT, SecT>>
	Shared-pointer alias.
using	ConnectCallback = NodeImpl::ConnectCallback
	Callback type fired when server connection state changes.
using	RespCallback = std::function<void(const RespT&)>
	Callback type for async response delivery.
Public Types inherited from vlink::Node< ClientImpl, 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>>>
	Client (const ConfT &conf, InitType type=InitType::kWithInit)
	Constructs a client from a typed transport configuration object.
	Client (const std::string &url_str, InitType type=InitType::kWithInit)
	Constructs a client from a URL string.
	~Client () override
void	detect_connected (ConnectCallback &&callback)
	Registers a callback invoked when the server connection state changes.
bool	wait_for_connected (std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Blocks until a server is available or the timeout expires.
bool	is_connected () const
	Returns `true` if a server is currently available.
bool	invoke (const ReqT &req, RespT &resp, std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Sends a request and blocks until the response is received.
std::optional< RespT >	invoke (const ReqT &req, std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Sends a request and returns the response as `std::optional`.
bool	invoke (const ReqT &req, RespCallback &&callback)
	Sends a request and invokes `callback` asynchronously on the response.
std::future< RespT >	async_invoke (const ReqT &req)
	Sends a request and returns a `std::future` for the response.
bool	send (const ReqT &req)
	Sends a fire-and-forget request with no response.
Public Member Functions inherited from vlink::Node< ClientImpl, 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 `Client` on the heap wrapped in a `unique_ptr`.
static SharedPtr	create_shared (const std::string &url_str, InitType type=InitType::kWithInit)
	Creates a `Client` on the heap wrapped in a `shared_ptr`.

Static Public Attributes
static constexpr ImplType	kImplType = kClient
	Node role identifier (`kClient`).
static constexpr bool	kHasResp = !std::is_same_v<RespT, Traits::EmptyType>
	`true` when `RespT` is not `EmptyType` (client expects a response).
static constexpr Serializer::Type	kReqType = Serializer::get_type_of<ReqT>()
	Serializer type for `ReqT`.
static constexpr Serializer::Type	kRespType = Serializer::get_type_of<RespT>()
	Serializer type for `RespT`.

Additional Inherited Members
Protected Member Functions inherited from vlink::Node< ClientImpl, 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< ClientImpl, SecurityType::kWithoutSecurity >
std::atomic_bool	has_inited_
std::unique_ptr< ClientImpl >	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 ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>
class vlink::Client< ReqT, RespT, SecT >

Type-safe client for the VLink method (RPC) communication model.

Template Parameters

ReqT	Request type.
RespT	Response type (defaults to `Traits::EmptyType` – fire-and-forget).
SecT	Security mode.

Member Typedef Documentation

◆ ConnectCallback

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

using vlink::Client< ReqT, RespT, SecT >::ConnectCallback = NodeImpl::ConnectCallback

Callback type fired when server connection state changes.

◆ RespCallback

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

using vlink::Client< ReqT, RespT, SecT >::RespCallback = std::function<void(const RespT&)>

Callback type for async response delivery.

◆ SharedPtr

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

using vlink::Client< ReqT, RespT, SecT >::SharedPtr = std::shared_ptr<Client<ReqT, RespT, SecT>>

Shared-pointer alias.

◆ UniquePtr

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

using vlink::Client< ReqT, RespT, SecT >::UniquePtr = std::unique_ptr<Client<ReqT, RespT, SecT>>

Unique-pointer alias.

Constructor & Destructor Documentation

◆ Client() [1/2]

template<typename ReqT, typename RespT, SecurityType SecT>

template<typename ConfT, typename>

vlink::Client< ReqT, RespT, SecT >::Client	(	const ConfT &	conf,
		InitType	type = InitType::kWithInit )

inlineexplicit

Constructs a client from a typed transport configuration object.

Accepts any Conf-derived configuration. A compile-time static_assert verifies the configuration supports the client 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:

◆ Client() [2/2]

template<typename ReqT, typename RespT, SecurityType SecT>

vlink::Client< ReqT, RespT, SecT >::Client	(	const std::string &	url_str,
		InitType	type = InitType::kWithInit )

inlineexplicit

Constructs a client from a URL string.

Parameters

url_str	Service URL (e.g. `"someip://30490/0x1/my_method"`).
type	`kWithInit` to call `init()` immediately (default).

Here is the call graph for this function:

◆ ~Client()

template<typename ReqT, typename RespT, SecurityType SecT>

vlink::Client< ReqT, RespT, SecT >::~Client ( )

inlineoverride

Here is the call graph for this function:

Member Function Documentation

◆ async_invoke()

template<typename ReqT, typename RespT, SecurityType SecT>

std::future< RespT > vlink::Client< ReqT, RespT, SecT >::async_invoke ( const ReqT & req )

inlinenodiscard

Sends a request and returns a std::future for the response.

Only valid when kHasResp is true (enforced by static_assert). The future is set when the response arrives. If the call fails (serialisation error, transport error, or deserialisation failure) the future's exception is set with an Exception::RuntimeError.

Parameters

req	Request value to send.

Returns: std::future<RespT> resolved when the response arrives.

◆ create_shared()

template<typename ReqT, typename RespT, SecurityType SecT>

Client< ReqT, RespT, SecT >::SharedPtr vlink::Client< ReqT, RespT, SecT >::create_shared	(	const std::string &	url_str,
		InitType	type = InitType::kWithInit )

inlinestaticnodiscard

Creates a Client on the heap wrapped in a shared_ptr.

Parameters

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

Returns: SharedPtr owning the new client.

◆ create_unique()

template<typename ReqT, typename RespT, SecurityType SecT>

Client< ReqT, RespT, SecT >::UniquePtr vlink::Client< ReqT, RespT, SecT >::create_unique	(	const std::string &	url_str,
		InitType	type = InitType::kWithInit )

inlinestaticnodiscard

Creates a Client on the heap wrapped in a unique_ptr.

Parameters

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

Returns: UniquePtr owning the new client.

◆ detect_connected()

template<typename ReqT, typename RespT, SecurityType SecT>

void vlink::Client< ReqT, RespT, SecT >::detect_connected ( ConnectCallback && callback )

inline

Registers a callback invoked when the server connection state changes.

Fires immediately (synchronously) if the server is already connected. Otherwise fires asynchronously when the server first becomes available.

Parameters

callback void(bool) – true when connected to a server.

◆ invoke() [1/3]

template<typename ReqT, typename RespT, SecurityType SecT>

bool vlink::Client< ReqT, RespT, SecT >::invoke	(	const ReqT &	req,
		RespCallback &&	callback )

inline

Sends a request and invokes callback asynchronously on the response.

Only valid when kHasResp is true. The call returns immediately; the callback is invoked on the transport thread (or on the attached MessageLoop thread) when the response arrives.

Parameters

req	Request value to send.
callback	`void(const RespT&)` invoked with the response.

Returns: true if the request was accepted by the transport; false on error.

◆ invoke() [2/3]

template<typename ReqT, typename RespT, SecurityType SecT>

bool vlink::Client< ReqT, RespT, SecT >::invoke	(	const ReqT &	req,
		RespT &	resp,
		std::chrono::milliseconds	timeout = Timeout::kDefaultInterval )

inlinenodiscard

Sends a request and blocks until the response is received.

Only valid when kHasResp is true (enforced by static_assert). Serialises req, sends it to the server, blocks for up to timeout, and deserialises the response into resp. A timeout of 0 is treated as infinite.

Parameters

req	Request value to send.
resp	Output parameter filled with the deserialised response.
timeout	Maximum wait for the response.

Returns: true if the response was received in time; false otherwise.

◆ invoke() [3/3]

template<typename ReqT, typename RespT, SecurityType SecT>

std::optional< RespT > vlink::Client< ReqT, RespT, SecT >::invoke	(	const ReqT &	req,
		std::chrono::milliseconds	timeout = Timeout::kDefaultInterval )

inlinenodiscard

Sends a request and returns the response as std::optional.

Convenience overload that returns std::nullopt on timeout or error instead of requiring an output parameter. Only valid when kHasResp is true. A timeout of 0 is treated as infinite.

Parameters

req	Request value to send.
timeout	Maximum wait for the response.

Returns: std::optional<RespT> – nullopt on timeout/error.

◆ is_connected()

template<typename ReqT, typename RespT, SecurityType SecT>

bool vlink::Client< ReqT, RespT, SecT >::is_connected ( ) const

inlinenodiscard

Returns true if a server is currently available.

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

Returns: true when connected to a server.

◆ send()

template<typename ReqT, typename RespT, SecurityType SecT>

bool vlink::Client< ReqT, RespT, SecT >::send ( const ReqT & req )

inline

Sends a fire-and-forget request with no response.

Only valid when RespT == EmptyType (enforced by static_assert). The call returns immediately after the transport has accepted the request; no response is expected or awaited.

Parameters

req	Request value to send.

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

Here is the call graph for this function:

◆ wait_for_connected()

template<typename ReqT, typename RespT, SecurityType SecT>

bool vlink::Client< ReqT, RespT, SecT >::wait_for_connected ( std::chrono::milliseconds timeout = Timeout::kDefaultInterval )

inline

Blocks until a server is available 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 interrupt(), which causes this method to return false.

Parameters

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

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

Member Data Documentation

◆ kHasResp

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

bool vlink::Client< ReqT, RespT, SecT >::kHasResp = !std::is_same_v<RespT, Traits::EmptyType>

staticconstexpr

true when RespT is not EmptyType (client expects a response).

◆ kImplType

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

ImplType vlink::Client< ReqT, RespT, SecT >::kImplType = kClient

staticconstexpr

Node role identifier (kClient).

◆ kReqType

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

Serializer::Type vlink::Client< ReqT, RespT, SecT >::kReqType = Serializer::get_type_of<ReqT>()

staticconstexpr

Serializer type for ReqT.

◆ kRespType

template<typename ReqT, typename RespT = Traits::EmptyType, SecurityType SecT = SecurityType::kWithoutSecurity>

Serializer::Type vlink::Client< ReqT, RespT, SecT >::kRespType = Serializer::get_type_of<RespT>()

staticconstexpr

Serializer type for RespT.

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

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

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ConnectCallback

◆ RespCallback

◆ SharedPtr

◆ UniquePtr

Constructor & Destructor Documentation

◆ Client() [1/2]

◆ Client() [2/2]

◆ ~Client()

Member Function Documentation

◆ async_invoke()

◆ create_shared()

◆ create_unique()

◆ detect_connected()

◆ invoke() [1/3]

◆ invoke() [2/3]

◆ invoke() [3/3]

◆ is_connected()

◆ send()

◆ wait_for_connected()

Member Data Documentation

◆ kHasResp

◆ kImplType

◆ kReqType

◆ kRespType