|
VLink 2.0.0
A high-performance communication middleware
|
Client-side proxy monitoring and control API backed by a MessageLoop. 更多...
#include <proxy_api.h>
类 | |
| struct | Process |
| Describes a VLink node process attached to a topic endpoint. 更多... | |
| struct | Info |
| Statistics and metadata for a single discovered topic endpoint. 更多... | |
| struct | UrlMeta |
| Associates a topic URL with its serialisation type and node role. 更多... | |
| struct | Control |
Control message sent from a kController client to ProxyServer. 更多... | |
| struct | Data |
Raw message payload delivered via DataCallback or sent via send_data(). 更多... | |
| struct | Config |
Construction-time configuration for ProxyAPI. 更多... | |
Public 类型 | |
| 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(). 更多... | |
| 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. 更多... | |
| enum | Status : uint8_t { kActive = 0 , kInActive = 1 , kPending = 2 , kInvalid = 3 } |
Per-topic activity status reported in Info. 更多... | |
| enum | Role : uint8_t { kController = 0 , kListener } |
Role of this ProxyAPI instance. 更多... | |
| 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. | |
| Public 类型 继承自 vlink::MessageLoop | |
| enum | Type : uint8_t { kNormalType = 0 , kLockfreeType = 1 , kPriorityType = 2 } |
| Queue implementation type. 更多... | |
| enum | Strategy : uint8_t { kOptimizationStrategy = 0 , kPopStrategy = 1 , kBlockStrategy = 2 } |
| Idle strategy controlling CPU and latency trade-offs. 更多... | |
| enum | Priority : uint16_t { kNoPriority = 0 , kLowestPriority = 1 , kTimerPriority = 50 , kNormalPriority = 100 , kHighestPriority = std::numeric_limits<uint16_t>::max() } |
Pre-defined task priority levels for kPriorityType loops. 更多... | |
| using | Callback = std::function<void()> |
| Callback type for tasks and event handlers. | |
Public 成员函数 | |
| 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 Config & | get_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. | |
| Public 成员函数 继承自 vlink::MessageLoop | |
| MessageLoop () | |
Constructs a MessageLoop with kNormalType queue. | |
| MessageLoop (Type type) | |
Constructs a MessageLoop with the specified queue type. | |
| virtual | ~MessageLoop () |
Destructor. Calls quit(true) and waits for the background thread (if any). | |
| void | set_name (const std::string &name) |
| Sets a human-readable name for this loop (visible in profiling tools). | |
| const std::string & | get_name () const |
Returns the name set via set_name(). | |
| Type | get_type () const |
| Returns the queue type this loop was constructed with. | |
| Strategy | get_strategy () const |
| Returns the current idle dispatch strategy. | |
| void | set_strategy (Strategy strategy) |
| Changes the idle dispatch strategy. | |
| void | register_begin_handler (Callback &&callback) |
| Registers a callback invoked once when the loop thread starts. | |
| void | register_end_handler (Callback &&callback) |
| Registers a callback invoked once when the loop thread exits. | |
| void | register_idle_handler (Callback &&callback) |
| Registers a callback invoked each time the task queue becomes empty. | |
| bool | run () |
| Runs the message loop on the calling thread (blocking). | |
| bool | async_run () |
| Starts the message loop on a new background thread (non-blocking). | |
| bool | spin () |
| Runs the loop continuously in a spin mode (blocking; no background thread). | |
| bool | spin_once (bool block=true) |
| Processes one batch of pending tasks and timers. | |
| bool | quit (bool force=false) |
| Requests the loop to exit cleanly. | |
| bool | wait_for_idle (int ms=Timer::kInfinite, bool check=true) |
| Waits until the task queue is drained. | |
| bool | wait_for_quit (int ms=Timer::kInfinite, bool check=true) |
Waits until the loop has fully exited (after quit() was called). | |
| bool | post_task (Callback &&callback) |
| Posts a task to the queue for execution on the loop thread. | |
| bool | post_task_with_priority (Callback &&callback, uint16_t priority) |
Posts a task with an explicit priority (requires kPriorityType loop). | |
| template<typename CallbackT, typename = std::enable_if_t<!std::is_convertible_v<CallbackT, Schedule::RetCallback>>> | |
| Schedule::Status | exec_task (const Schedule::Config &config, CallbackT &&callback) |
Posts a scheduled task and returns a Schedule::Status for chaining callbacks. | |
| template<typename CallbackT, typename = std::enable_if_t<std::is_convertible_v<CallbackT, Schedule::RetCallback>>> | |
| Schedule::RetStatus | exec_task (const Schedule::Config &config, CallbackT &&callback) |
Posts a scheduled task and returns a Schedule::RetStatus for chaining callbacks. | |
| bool | wakeup () |
Wakes the loop thread if it is sleeping (e.g., in kBlockStrategy). | |
| void | reset_lockfree_capacity () |
| Resets the lock-free queue to its initial capacity. | |
| bool | is_running () const |
Returns true if the loop is currently running (started and not quit). | |
| bool | is_ready_to_quit () const |
Returns true if quit() has been called and the loop is winding down. | |
| bool | is_busy () const |
Returns true if the loop is currently executing a task. | |
| size_t | get_task_count () const |
| Returns the number of tasks currently in the queue. | |
| virtual size_t | get_max_timer_count () const |
| Returns the maximum number of timers that can be attached to this loop. | |
| virtual bool | is_in_same_thread () const |
Returns true if the calling thread is the same as the loop thread. | |
| template<class FunctionT, class... ArgsT, typename ResultT = std::invoke_result_t<FunctionT, ArgsT...>> | |
| std::future< ResultT > | invoke_task (FunctionT &&function, ArgsT &&... args) |
Dispatches a callable to the loop thread and returns a std::future for the result. | |
| template<class FunctionT, class... ArgsT, typename ResultT = std::invoke_result_t<FunctionT, ArgsT...>> | |
| std::future< ResultT > | invoke_task_with_priority (FunctionT &&function, uint16_t priority, ArgsT &&... args) |
Dispatches a callable with an explicit priority and returns a std::future. | |
静态 Public 成员函数 | |
| 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 成员函数 | |
| 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. | |
| Protected 成员函数 继承自 vlink::MessageLoop | |
| virtual void | on_idle () |
| Called from the loop thread each time the queue becomes empty. | |
| virtual void | on_task_changed (Callback &&callback, uint32_t start_time) |
| Called before each task is executed. | |
| virtual void | on_task_timeout (Callback &&callback, uint32_t elapsed_time) |
Called when a task's execution time exceeds get_max_elapsed_time(). | |
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.
| 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.
| 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.
| using vlink::ProxyAPI::ErrorCallback = std::function<void(Error error)> |
| using vlink::ProxyAPI::InfoCallback = std::function<void(const std::vector<Info>& info_list)> |
| using vlink::ProxyAPI::TimeCallback = std::function<void(uint64_t sys_time, uint64_t boot_time)> |
| 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.
| 枚举值 | |
|---|---|
| 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. |
| 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.
| 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. | 枚举值 | |
|---|---|
| kController | |
| kListener | |
| enum vlink::ProxyAPI::Status : uint8_t |
Per-topic activity status reported in Info.
|
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.
| config | Configuration for the proxy connection. |
|
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.
|
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.
|
nodiscard |
Returns the configuration passed at construction.
Config.
|
nodiscard |
Returns the server's most recently reported CPU utilisation.
|
nodiscard |
Returns the current error state.
Error value; kNoError when no error is active.
|
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.
|
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.
|
nodiscard |
Returns the server's most recently reported memory utilisation.
|
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.
Mode value.
|
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.
|
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".
| time | Microseconds since boot. |
|
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.
| time | Microseconds since the Unix epoch. |
| enable_utc | true for UTC; false for local time (default). |
|
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.
|
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.
SampleLostInfo with total and lost sample counts.
|
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.
重载 vlink::MessageLoop .
|
overrideprotectedvirtual |
|
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.
|
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.
|
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.
"2.0.0".
|
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.
true if connected, false otherwise.
|
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.
true when filtering is enabled.
|
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.
true when SHM support is compiled in.
|
overrideprotectedvirtual |
Called from the loop thread just before the first task is processed.
Override in subclasses to perform per-thread initialisation.
重载 vlink::MessageLoop .
|
overrideprotectedvirtual |
Called from the loop thread just after the last task has been processed.
Override in subclasses to perform per-thread cleanup.
重载 vlink::MessageLoop .
| 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.
| callback | Callable with signature void(bool connected). |
| 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).
| callback | Callable with signature void(const Data& data). |
| 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.
| callback | Callable with signature void(Error error). |
| 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.
| callback | Callable with signature void(const std::vector<Info>& info_list). |
| 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.
| callback | Callable with signature void(uint64_t sys_time, uint64_t boot_time). |
| 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.
| control | Control message to send. |
| async | true to post asynchronously (default); false to block. |
true on success; false if role is kListener or the API is shutting down. | 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.
| data | Data to inject, including URL, serialisation type, schema family, raw bytes, timestamp, and sequence number. |
true if data was published; false otherwise.