Type-safe RPC caller for the VLink method 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 > >
	Owning unique-pointer alias. More...

using	SharedPtr = std::shared_ptr< Client< ReqT, RespT, SecT > >
	Owning shared-pointer alias. More...

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

using	RespCallback = Function< void(const RespT &)>
	Callback signature for asynchronous responses. More...

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

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

	~Client () override
	Destroys the client and tears down outstanding promises. More...

void	detect_connected (ConnectCallback &&callback)
	Registers a callback invoked when the server-presence state changes. More...

bool	wait_for_connected (std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Blocks until a server is discovered or `timeout` expires. More...

bool	is_connected () const
	Non-blocking query of server presence. More...

bool	invoke (const ReqT &req, RespT &resp, std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Synchronous request/response invocation with an output parameter. More...

std::optional< RespT >	invoke (const ReqT &req, std::chrono::milliseconds timeout=Timeout::kDefaultInterval)
	Synchronous request/response invocation returning a `std::optional`. More...

bool	invoke (const ReqT &req, RespCallback &&callback)
	Asynchronous callback-based invocation. More...

std::future< RespT >	async_invoke (const ReqT &req)
	Asynchronous future-based invocation. More...

bool	send (const ReqT &req)
	Fire-and-forget request emission. More...

Public Member Functions inherited from vlink::Node< ClientImpl, 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 `Client` 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 `Client` and wraps it in a `std::shared_ptr`. More...

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

static constexpr bool	kHasResp = !std::is_same_v<RespT, Traits::EmptyType>
	`true` when response expected. More...

static constexpr Serializer::Type	kReqType = Serializer::get_type_of<ReqT>()
	Codec for the request. More...

static constexpr Serializer::Type	kRespType = Serializer::get_type_of<RespT>()
	Codec for the response. More...

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

Detailed Description

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

Type-safe RPC caller for the VLink method communication model.

Inherits the full Node API and adds method-specific operations: connection detection, blocking and non-blocking invocation, future-based async invocation, and fire-and-forget send(). The transport implementation (ClientImpl) is selected by the URL scheme or by the typed configuration object supplied at construction time.

Template Parameters

ReqT	Request message type. Must satisfy `Serializer::is_supported()`.
RespT	Response message type. Defaults to `Traits::EmptyType` for fire-and-forget.
SecT	Security mode; defaults to `SecurityType::kWithoutSecurity`.

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 for server presence transitions.

◆ RespCallback

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

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

Callback signature for asynchronous responses.

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

Owning 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> >

Owning 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 check enforces that the configuration permits the client role.

Template Parameters

ConfT Concrete configuration type derived from Conf.

Parameters

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

◆ 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 such as `"someip://30490/0x1/my_method"`.
type	Whether to call `init()` inline; default is `InitType::kWithInit`.

◆ ~Client()

template<typename ReqT , typename RespT , SecurityType SecT>

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

inlineoverride

Destroys the client and tears down outstanding promises.

Required to drain any in-flight async_invoke() promises before this object's locks and maps are destroyed.

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 )

inline

Asynchronous future-based invocation.

Returns a std::future that is set when the response arrives. On serialisation, transport, or deserialisation failure the future's exception state is populated with Exception::RuntimeError. Only available when kHasResp is true.

Parameters

req	Request value.

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

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

inlinestatic

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

Parameters

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

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

inlinestatic

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

Parameters

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

Returns: Owning UniquePtr to 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-presence state changes.

Fires synchronously immediately if a server is already discovered at registration; otherwise fires asynchronously the first time a matching server appears, and again on disconnection.

Parameters

callback void(bool) callable – true means connected.

◆ invoke() [1/3]

template<typename ReqT , typename RespT , SecurityType SecT>

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

inline

Asynchronous callback-based invocation.

Only available when kHasResp is true. The method returns immediately; callback runs on the transport delivery thread or on the attached MessageLoop thread when the response arrives.

Parameters

req	Request value.
callback	`void(const RespT&)` invoked once the response arrives.

Returns: true if the transport accepted the request.

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

inline

Synchronous request/response invocation with an output parameter.

Only available when kHasResp is true. Serialises req, blocks for up to timeout, and deserialises the reply into resp. A timeout of 0 is treated as infinite.

Parameters

req	Request value.
resp	Output parameter receiving the deserialised response.
timeout	Maximum wait for the response.

Returns: true if the response was received in time.

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

inline

Synchronous request/response invocation returning a std::optional.

Convenience wrapper that returns std::nullopt on timeout, transport failure, or codec failure. Only available when kHasResp is true.

Parameters

req	Request value.
timeout	Maximum wait for the response.

Returns: std::optional<RespT>; empty on failure.

◆ is_connected()

template<typename ReqT , typename RespT , SecurityType SecT>

bool vlink::Client< ReqT, RespT, SecT >::is_connected

inline

Non-blocking query of server presence.

Returns: true when the transport currently has a matching server.

◆ send()

template<typename ReqT , typename RespT , SecurityType SecT>

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

inline

Fire-and-forget request emission.

Only available when RespT == EmptyType. Serialises req and passes it to the transport without waiting for or expecting a reply.

Parameters

req	Request value.

Returns: true if the transport accepted the request.

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

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

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

staticconstexpr

true when response expected.

◆ kImplType

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

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

staticconstexpr

Node role tag (kClient).

◆ kReqType

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

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

staticconstexpr

Codec for the request.

◆ kRespType

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

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

staticconstexpr

Codec for the response.

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

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

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

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