VLink 2.0.0
A high-performance communication middleware
Loading...
Searching...
No Matches
vlink::ProxyAPI Class Reference

Client-side proxy monitoring and control API backed by a MessageLoop. More...

#include <proxy_api.h>

Inheritance diagram for vlink::ProxyAPI:
Collaboration diagram for vlink::ProxyAPI:

Classes

struct  Process
 Describes a VLink node process attached to a topic endpoint. More...
struct  Info
 Statistics and metadata for a single discovered topic endpoint. More...
struct  UrlMeta
 Associates a topic URL with its serialisation type and node role. More...
struct  Control
 Control message sent from a kController client to ProxyServer. More...
struct  Data
 Raw message payload delivered via DataCallback or sent via send_data(). More...
struct  Config
 Construction-time configuration for ProxyAPI. More...

Public Types

enum  Mode : uint8_t {
  kOffline = 0 , kObserveOne = 1 , kObserveAll = 2 , kRecord = 3 ,
  kPlay = 4 , kEdit = 5 , kAuto = 6 , kAutoAndObserveAll = 7
}
 Proxy operation modes sent via send_control(). More...
enum  Error : uint8_t {
  kNoError = 0 , kModeError = 1 , kControlError = 2 , kReliableCompError = 3 ,
  kTcpCompError = 4 , kDirectCompError = 5 , kMultiProxyError = 7 , kVersionCompError = 8 ,
  kUnknownError = 9
}
 Compatibility and protocol error codes reported via ErrorCallback. More...
enum  Status : uint8_t { kActive = 0 , kInActive = 1 , kPending = 2 , kInvalid = 3 }
 Per-topic activity status reported in Info. More...
enum  Role : uint8_t { kController = 0 , kListener }
 Role of this ProxyAPI instance. More...
using ConnectCallback = std::function<void(bool connected)>
 Callback invoked when the connection state with ProxyServer changes.
using ErrorCallback = std::function<void(Error error)>
 Callback invoked when an error or error-clear event is detected.
using TimeCallback = std::function<void(uint64_t sys_time, uint64_t boot_time)>
 Callback delivering the server's wall-clock and boot-time from each heartbeat.
using InfoCallback = std::function<void(const std::vector<Info>& info_list)>
 Callback delivering the per-topic statistics list once per second.
using DataCallback = std::function<void(const Data& data)>
 Callback delivering raw message data relayed by ProxyServer.
 Queue implementation type. More...
 Idle strategy controlling CPU and latency trade-offs. More...
 Pre-defined task priority levels for kPriorityType loops. More...

Public Member Functions

 ProxyAPI (const Config &config)
 Constructs a ProxyAPI with the given configuration.
 ~ProxyAPI () override
 Destructor.
void register_connect_callback (ConnectCallback &&callback)
 Registers a callback for connection state changes.
void register_error_callback (ErrorCallback &&callback)
 Registers a callback for error state transitions.
void register_time_callback (TimeCallback &&callback)
 Registers a callback for heartbeat timestamp delivery.
void register_info_callback (InfoCallback &&callback)
 Registers a callback for per-topic statistics updates.
void register_data_callback (DataCallback &&callback)
 Registers a callback for raw message data relayed by the server.
bool send_control (const Control &control, bool async=true)
 Sends a Control message to the ProxyServer.
bool send_data (const Data &data)
 Sends raw message data to the ProxyServer for injection.
const Configget_current_config () const
 Returns the configuration passed at construction.
Mode get_current_mode () const
 Returns the current proxy operation mode.
Error get_current_error () const
 Returns the current error state.
std::string get_current_hostname () const
 Returns the hostname of the connected ProxyServer.
std::string get_current_machine_id () const
 Returns the machine ID of the connected ProxyServer.
uint64_t get_current_sys_time () const
 Returns the best estimate of the server's current wall-clock time.
uint64_t get_current_boot_time () const
 Returns the best estimate of the server's current boot time.
double get_current_cpu_usage () const
 Returns the server's most recently reported CPU utilisation.
double get_current_memory_usage () const
 Returns the server's most recently reported memory utilisation.
int64_t get_latency () const
 Returns the measured round-trip latency on the data channel.
SampleLostInfo get_lost () const
 Returns the sample loss statistics on the data channel.
bool is_connected () const
 Returns true when a valid connection to ProxyServer exists.
std::string get_proxy_version () const
 Returns the VLINK_VERSION string reported by the server.
std::unordered_set< std::string > get_proxy_hostnames () const
 Returns the set of all server hostnames seen during this session.
std::unordered_set< std::string > get_proxy_machine_ids () const
 Returns the set of all server machine IDs seen during this session.

Static Public Member Functions

static bool is_support_shm ()
 Returns true if the build includes SHM (Iceoryx) support.
static bool is_enable_filter ()
 Returns true if topic filtering support is compiled in.
static std::string get_format_sys_time (uint64_t time, bool enable_utc=false)
 Formats a microsecond wall-clock timestamp as a human-readable string.
static std::string get_format_boot_time (uint64_t time)
 Formats a microsecond boot-time duration as a human-readable string.

Protected Member Functions

size_t get_max_task_count () const override
 Returns the maximum queue depth.
uint32_t get_max_elapsed_time () const override
 Returns the maximum allowed task execution time in milliseconds.
void on_begin () override
 Called from the loop thread just before the first task is processed.
void on_end () override
 Called from the loop thread just after the last task has been processed.

Detailed Description

Client-side proxy monitoring and control API backed by a MessageLoop.

Connects to a ProxyServer daemon over DDS (or SHM in direct mode) and exposes callbacks for connection state, error codes, heartbeat timestamps, topic statistics, and raw data payloads. Inherits MessageLoop; start the loop explicitly if you need queued tasks, timers, or async control posts to execute on that loop.

Member Typedef Documentation

◆ ConnectCallback

using vlink::ProxyAPI::ConnectCallback = std::function<void(bool connected)>

Callback invoked when the connection state with ProxyServer changes.

connected is true when the first valid heartbeat is received; false when 5 seconds pass without a heartbeat or when the control channel disconnects.

◆ DataCallback

using vlink::ProxyAPI::DataCallback = std::function<void(const Data& data)>

Callback delivering raw message data relayed by ProxyServer.

Fired for every message forwarded by the server in observe, record, or play mode. The Data::raw bytes are shallow-borrowed; copy if you need to retain them beyond the callback.

◆ ErrorCallback

using vlink::ProxyAPI::ErrorCallback = std::function<void(Error error)>

Callback invoked when an error or error-clear event is detected.

Only fired when the Error state transitions (e.g. kNoError to kVersionCompError, or back to kNoError).

◆ InfoCallback

using vlink::ProxyAPI::InfoCallback = std::function<void(const std::vector<Info>& info_list)>

Callback delivering the per-topic statistics list once per second.

Parameters
info_listList of Info records for all currently observed topics.

◆ TimeCallback

using vlink::ProxyAPI::TimeCallback = std::function<void(uint64_t sys_time, uint64_t boot_time)>

Callback delivering the server's wall-clock and boot-time from each heartbeat.

Parameters
sys_timeServer system time in microseconds since the Unix epoch.
boot_timeServer uptime in microseconds since boot.

Member Enumeration Documentation

◆ Error

enum vlink::ProxyAPI::Error : uint8_t

Compatibility and protocol error codes reported via ErrorCallback.

Errors are detected when the client parses an incoming Time heartbeat. The callback fires only when the error state changes.

Enumerator
kNoError 

No error; connection is healthy.

kModeError 

Unsupported mode requested.

kControlError 

Server responded with a different control_id.

kReliableCompError 

Client and server have mismatched reliable setting.

kTcpCompError 

Client and server have mismatched enable_tcp setting.

kDirectCompError 

Client and server have mismatched direct setting.

kMultiProxyError 

Multiple proxy servers detected on the same domain.

kVersionCompError 

VLINK_VERSION string differs between client and server.

kUnknownError 

Unknown or unclassified error.

◆ Mode

enum vlink::ProxyAPI::Mode : uint8_t

Proxy operation modes sent via send_control().

The mode governs what the ProxyServer observes or replays. Only a kController client may change the mode.

Enumerator
kOffline 

Disconnected; server releases all subscriptions.

kObserveOne 

Observe a single topic from the URL list.

kObserveAll 

Observe all discovered topics on the network.

kRecord 

Record data from topics in the URL list.

kPlay 

Replay: inject previously recorded data.

kEdit 

Edit: forward data injected by the controller.

kAuto 

Auto: observe specified URLs and forward to subscribers.

kAutoAndObserveAll 

Auto + observe every discovered topic.

◆ Role

enum vlink::ProxyAPI::Role : uint8_t

Role of this ProxyAPI instance.

  • kController can call send_control() and send_data().
  • kListener is a passive observer; control/data send calls return false.
Enumerator
kController 
kListener 

◆ Status

enum vlink::ProxyAPI::Status : uint8_t

Per-topic activity status reported in Info.

Enumerator
kActive 

Topic is actively receiving data.

kInActive 

Topic exists but has not received data recently.

kPending 

Topic was just discovered; statistics are still accumulating.

kInvalid 

Topic type does not support observation (e.g., subscriber-only).

Constructor & Destructor Documentation

◆ ProxyAPI()

vlink::ProxyAPI::ProxyAPI ( const Config & config)
explicit

Constructs a ProxyAPI with the given configuration.

Initialises all DDS/SHM channels based on config. A unique control_id is derived from the CPU timestamp at construction time so that the server can distinguish simultaneous controllers. The inherited MessageLoop is not started automatically; call run() or async_run() yourself if you need timer-driven reconnect logic or queued control posts to execute.

Parameters
configConfiguration for the proxy connection.
Here is the caller graph for this function:

◆ ~ProxyAPI()

vlink::ProxyAPI::~ProxyAPI ( )
override

Destructor.

Quits the inherited MessageLoop (if it is running), waits for it to stop, and then releases DDS/SHM handles. Destruction does not publish an extra kOffline control message.

Member Function Documentation

◆ get_current_boot_time()

uint64_t vlink::ProxyAPI::get_current_boot_time ( ) const
nodiscard

Returns the best estimate of the server's current boot time.

Computed as the last received boot_time plus the elapsed microseconds since that heartbeat, extrapolated via an ElapsedTimer.

Returns
Estimated server uptime in microseconds since boot.

◆ get_current_config()

const Config & vlink::ProxyAPI::get_current_config ( ) const
nodiscard

Returns the configuration passed at construction.

Returns
Const reference to the internal Config.

◆ get_current_cpu_usage()

double vlink::ProxyAPI::get_current_cpu_usage ( ) const
nodiscard

Returns the server's most recently reported CPU utilisation.

Returns
CPU usage as a percentage in the range [0, 100]. Returns 0 when disconnected.

◆ get_current_error()

Error vlink::ProxyAPI::get_current_error ( ) const
nodiscard

Returns the current error state.

Returns
Current Error value; kNoError when no error is active.

◆ get_current_hostname()

std::string vlink::ProxyAPI::get_current_hostname ( ) const
nodiscard

Returns the hostname of the connected ProxyServer.

Populated from the server's Time heartbeat. Returns an empty string before the first heartbeat is received or after disconnection.

Returns
Hostname string, or empty if not yet connected.

◆ get_current_machine_id()

std::string vlink::ProxyAPI::get_current_machine_id ( ) const
nodiscard

Returns the machine ID of the connected ProxyServer.

Populated from the server's Time heartbeat. Returns an empty string before the first heartbeat is received.

Returns
Machine ID string, or empty if not yet connected.

◆ get_current_memory_usage()

double vlink::ProxyAPI::get_current_memory_usage ( ) const
nodiscard

Returns the server's most recently reported memory utilisation.

Returns
Memory usage as a percentage in the range [0, 100]. Returns 0 when disconnected.

◆ get_current_mode()

Mode vlink::ProxyAPI::get_current_mode ( ) const
nodiscard

Returns the current proxy operation mode.

Reflects the mode most recently set by send_control(). Updated immediately on the calling thread before any async DDS publish.

Returns
Current Mode value.

◆ get_current_sys_time()

uint64_t vlink::ProxyAPI::get_current_sys_time ( ) const
nodiscard

Returns the best estimate of the server's current wall-clock time.

Computed as the last received sys_time plus the elapsed microseconds since that heartbeat, extrapolated via an ElapsedTimer. Returns the raw sys_time field if the timer is not yet running.

Returns
Estimated server system time in microseconds since the Unix epoch.

◆ get_format_boot_time()

std::string vlink::ProxyAPI::get_format_boot_time ( uint64_t time)
staticnodiscard

Formats a microsecond boot-time duration as a human-readable string.

Converts time (microseconds since boot) to a formatted elapsed-time string, e.g. "0d 01:23:45.678".

Parameters
timeMicroseconds since boot.
Returns
Formatted elapsed-time string.

◆ get_format_sys_time()

std::string vlink::ProxyAPI::get_format_sys_time ( uint64_t time,
bool enable_utc = false )
staticnodiscard

Formats a microsecond wall-clock timestamp as a human-readable string.

Output format: "YYYY/MM/DD HH:MM:SS:mmm" where mmm is milliseconds. Uses localtime_r by default; gmtime_r when enable_utc is true.

Parameters
timeMicroseconds since the Unix epoch.
enable_utctrue for UTC; false for local time (default).
Returns
Formatted timestamp string, or empty on conversion error.

◆ get_latency()

int64_t vlink::ProxyAPI::get_latency ( ) const
nodiscard

Returns the measured round-trip latency on the data channel.

In direct (SHM) mode this always returns 0 because latency measurement is not available on the SHM data channel. In DDS mode it delegates to the underlying data subscriber's latency tracker.

Returns
Latency in microseconds, or 0 in direct mode.

◆ get_lost()

SampleLostInfo vlink::ProxyAPI::get_lost ( ) const
nodiscard

Returns the sample loss statistics on the data channel.

In direct (SHM) mode returns a default-constructed (zero) SampleLostInfo. In DDS mode it delegates to the underlying data subscriber.

Returns
SampleLostInfo with total and lost sample counts.

◆ get_max_elapsed_time()

uint32_t vlink::ProxyAPI::get_max_elapsed_time ( ) const
overrideprotectedvirtual

Returns the maximum allowed task execution time in milliseconds.

When a task exceeds this duration, on_task_timeout() is called. Returns 0 to disable timeout checking.

Returns
Maximum execution time in ms.

Reimplemented from vlink::MessageLoop.

◆ get_max_task_count()

size_t vlink::ProxyAPI::get_max_task_count ( ) const
overrideprotectedvirtual

Returns the maximum queue depth.

Returns
kMaxTaskSize (10000) by default.

Reimplemented from vlink::MessageLoop.

◆ get_proxy_hostnames()

std::unordered_set< std::string > vlink::ProxyAPI::get_proxy_hostnames ( ) const
nodiscard

Returns the set of all server hostnames seen during this session.

Hostnames are accumulated over the lifetime of the connection; they are NOT cleared on disconnection, only when a new reset_handle() is triggered.

Returns
Unordered set of hostname strings.

◆ get_proxy_machine_ids()

std::unordered_set< std::string > vlink::ProxyAPI::get_proxy_machine_ids ( ) const
nodiscard

Returns the set of all server machine IDs seen during this session.

Analogous to get_proxy_hostnames(); accumulated over the lifetime of the connection.

Returns
Unordered set of machine ID strings.

◆ get_proxy_version()

std::string vlink::ProxyAPI::get_proxy_version ( ) const
nodiscard

Returns the VLINK_VERSION string reported by the server.

Populated from the first valid heartbeat. Returns an empty string before connection or after disconnection.

Returns
Server VLink version string, e.g. "2.0.0".

◆ is_connected()

bool vlink::ProxyAPI::is_connected ( ) const
nodiscard

Returns true when a valid connection to ProxyServer exists.

Set to true on receipt of a valid Time heartbeat; set to false when 5 seconds elapse without a heartbeat or when the control channel reports disconnection.

Returns
true if connected, false otherwise.

◆ is_enable_filter()

bool vlink::ProxyAPI::is_enable_filter ( )
staticnodiscard

Returns true if topic filtering support is compiled in.

Determined at compile time by VLINK_PROXY_ENABLE_FILTER. When false the filter_str and filter_by_process fields in Control are ignored by the server.

Returns
true when filtering is enabled.

◆ is_support_shm()

bool vlink::ProxyAPI::is_support_shm ( )
staticnodiscard

Returns true if the build includes SHM (Iceoryx) support.

Determined at compile time by the VLINK_SUPPORT_SHM macro. Useful for checking whether Config::direct can be used.

Returns
true when SHM support is compiled in.

◆ on_begin()

void vlink::ProxyAPI::on_begin ( )
overrideprotectedvirtual

Called from the loop thread just before the first task is processed.

Override in subclasses to perform per-thread initialisation.

Reimplemented from vlink::MessageLoop.

◆ on_end()

void vlink::ProxyAPI::on_end ( )
overrideprotectedvirtual

Called from the loop thread just after the last task has been processed.

Override in subclasses to perform per-thread cleanup.

Reimplemented from vlink::MessageLoop.

Here is the call graph for this function:

◆ register_connect_callback()

void vlink::ProxyAPI::register_connect_callback ( ConnectCallback && callback)

Registers a callback for connection state changes.

If the API is already connected when this method is called the callback is invoked immediately with connected = true inside this call. The callback is replaced atomically; only one callback is active at a time.

Parameters
callbackCallable with signature void(bool connected).

◆ register_data_callback()

void vlink::ProxyAPI::register_data_callback ( DataCallback && callback)

Registers a callback for raw message data relayed by the server.

No immediate invocation occurs at registration. Data arrives when the server is in a mode that forwards messages (kObserveOne, kObserveAll, kRecord, kAuto, kAutoAndObserveAll).

Parameters
callbackCallable with signature void(const Data& data).

◆ register_error_callback()

void vlink::ProxyAPI::register_error_callback ( ErrorCallback && callback)

Registers a callback for error state transitions.

If a non-zero error is already active when this method is called the callback is invoked immediately with the current error inside this call.

Parameters
callbackCallable with signature void(Error error).

◆ register_info_callback()

void vlink::ProxyAPI::register_info_callback ( InfoCallback && callback)

Registers a callback for per-topic statistics updates.

Invoked once per second with the full Info list from the server. No immediate invocation occurs at registration; data arrives on the next server broadcast cycle.

Parameters
callbackCallable with signature void(const std::vector<Info>& info_list).

◆ register_time_callback()

void vlink::ProxyAPI::register_time_callback ( TimeCallback && callback)

Registers a callback for heartbeat timestamp delivery.

If timestamps have already been received (timers are active) the callback is invoked immediately with the latest extrapolated times inside this call.

Parameters
callbackCallable with signature void(uint64_t sys_time, uint64_t boot_time).

◆ send_control()

bool vlink::ProxyAPI::send_control ( const Control & control,
bool async = true )

Sends a Control message to the ProxyServer.

Only valid when the role is kController; returns false immediately for kListener. The control is cached internally and automatically re-sent if the server reconnects after a dropout.

When async is true (default) the DDS publish is posted to the MessageLoop thread; when false it is executed synchronously on the calling thread.

Every entry in control.url_meta_list must provide both ser and a known schema value. Proxy no longer back-fills missing routing metadata from discovery caches because that would hide broken schema-propagation paths.

If direct mode is configured, corresponding SHM publishers are created or destroyed to match publisher entries in url_meta_list. Direct subscribers are synchronised either from subscriber entries in url_meta_list or, for kObserveAll / kAutoAndObserveAll, from the latest Info list reported by the server.

Parameters
controlControl message to send.
asynctrue to post asynchronously (default); false to block.
Returns
true on success; false if role is kListener or the API is shutting down.

◆ send_data()

bool vlink::ProxyAPI::send_data ( const Data & data)

Sends raw message data to the ProxyServer for injection.

Only valid when the role is kController; returns false for kListener. In direct mode the data is published directly on the SHM publisher corresponding to data.url. In non-direct mode it is wrapped in a ProxyData envelope and forwarded over the DDS data channel.

Returns false if no subscribers are listening on the target channel.

The caller must provide both data.ser and a known data.schema. Proxy no longer guesses the decode stack from cached discovery metadata.

Parameters
dataData to inject, including URL, serialisation type, schema family, raw bytes, timestamp, and sequence number.
Returns
true if data was published; false otherwise.

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