 |
VLink
2.1.0
A high-performance communication middleware
|
|
VLink
2.1.0
A high-performance communication middleware
|
MessageLoop-based rolling in-memory recorder that dumps a pre/post window to a bag on trigger.
More...
#include <trigger_recorder.h>
Classes | |
| struct | Config |
| Recorder-wide configuration; passed once to the constructor and read-only afterwards. More... | |
| struct | TriggerParams |
| Per-trigger parameters; a pure data struct with no RPC or protobuf dependency. More... | |
| struct | UrlConfig |
Per-URL overrides; any field left negative falls back to the matching Config default. More... | |
Public Types | |
| enum | OverflowPolicy : uint8_t { kCoverOldest = 0 , kDropNewest = 1 } |
What to do when a byte cap (per-URL max_size or global max_cache_size) would be exceeded. More... | |
| enum | FileType : uint8_t { kVdb = 0 , kVcap = 1 } |
| On-disk container format for the dumped bag. More... | |
| using | RawSub = Subscriber< Bytes > |
| Raw byte subscriber owned by the recorder for one discovered URL. More... | |
| using | RawSubFactory = Function< std::shared_ptr< RawSub >(const std::string &url, InitType type)> |
| Caller-side constructor for raw subscribers. More... | |
 Public Types inherited from vlink::MessageLoop | |
| enum | Type : uint8_t { kNormalType = 0 , kLockfreeType = 1 , kPriorityType = 2 } |
| Internal queue implementation type. More... | |
| enum | Strategy : uint8_t { kOptimizationStrategy = 0 , kPopStrategy = 1 , kBlockStrategy = 2 } |
| Back-pressure strategy applied when the bounded queue is at capacity. More... | |
| enum | Priority : uint16_t { kNoPriority = 0 , kLowestPriority = 1 , kTimerPriority = 50 , kNormalPriority = 100 , kHighestPriority = std::numeric_limits<uint16_t>::max() } |
Built-in priority levels for kPriorityType loops; higher values dispatch first. More... | |
| using | Callback = MoveFunction< void()> |
| Callback type for tasks and event handlers. More... | |
Public Member Functions | |
| TriggerRecorder (const Config &config, RawSubFactory &&factory) | |
| Builds the recorder and acquires every fallible resource; the loop is not running yet. More... | |
| ~TriggerRecorder () override | |
| Requests quit and joins the recorder loop thread. More... | |
| bool | dump (const TriggerParams ¶ms={}) |
| Requests a dump of the pre/post window around the current instant. More... | |
| bool | dump (const TriggerParams ¶ms, std::string &out_file) |
| Requests a dump and returns its selected output path when accepted. More... | |
| bool | is_dumping () const noexcept |
| Reports whether a dump is currently in flight. More... | |
| void | bind_trigger_interface (const std::shared_ptr< TriggerPluginInterface > &trigger_interface) |
| Binds the trigger plugin notified across the recorder's life cycle and dump pipeline. More... | |
| void | clear_trigger_interface () |
Detaches the trigger plugin (equivalent to bind_trigger_interface(nullptr)). More... | |
| void | bind_bag_interface (const std::shared_ptr< BagPluginInterface > &bag_interface) |
| Binds the bag reorder plugin applied inside the write path of every dump. More... | |
| void | clear_bag_interface () |
Detaches the bag reorder plugin (equivalent to bind_bag_interface(nullptr)). More... | |
| Public Member Functions inherited from vlink::MessageLoop | |
| MessageLoop () | |
Constructs a loop with the default kNormalType queue. More... | |
| MessageLoop (Type type) | |
| Constructs a loop with the given queue type. More... | |
| virtual | ~MessageLoop () |
| Destructor; requests quit and joins the dispatcher thread if needed. More... | |
| void | set_name (const std::string &name) |
| Sets a human-readable name visible to profiling tools. More... | |
| const std::string & | get_name () const |
Returns the loop name set via set_name. More... | |
| Type | get_type () const |
| Returns the queue type this loop was constructed with. More... | |
| Strategy | get_strategy () const |
| Returns the active back-pressure strategy. More... | |
| void | set_strategy (Strategy strategy) |
| Replaces the back-pressure strategy. More... | |
| void | register_begin_handler (Callback &&callback) |
| Registers a callback fired once at loop thread startup. More... | |
| void | register_end_handler (Callback &&callback) |
| Registers a callback fired once when the loop thread exits. More... | |
| void | register_idle_handler (Callback &&callback) |
| Registers a callback fired every time the queue becomes empty. More... | |
| bool | run () |
Runs the loop on the calling thread until quit is requested. More... | |
| bool | async_run () |
| Starts the loop on a new background thread. More... | |
| bool | spin () |
Alias of run blocking the calling thread. More... | |
| bool | spin_once (bool block=true) |
| Processes one batch of pending tasks and timers on the calling thread. More... | |
| bool | quit (bool force=false) |
| Requests the loop to exit. More... | |
| bool | wait_for_quit (int ms=Timer::kInfinite, bool check=true) |
| Waits until the loop has fully exited. More... | |
| bool | post_task (Callback &&callback) |
| Posts a task for execution on the loop thread. More... | |
| TaskHandle | post_task_handle (Callback &&callback, const PostTaskOptions &options={}) |
Tracked variant of post_task returning a TaskHandle. More... | |
| bool | post_task_with_priority (Callback &&callback, uint16_t priority) |
Posts a task with an explicit priority on a kPriorityType loop. More... | |
| TaskHandle | post_task_with_priority_handle (Callback &&callback, uint16_t priority, const PostTaskOptions &options={}) |
Tracked variant of post_task_with_priority returning a TaskHandle. More... | |
| 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) |
Schedules a void-returning callable and returns a chainable Schedule::Status. More... | |
| 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) |
Schedules a bool-returning callable and returns a chainable Schedule::RetStatus. More... | |
| bool | wakeup () |
| Wakes the loop thread if it is suspended in its idle wait. More... | |
| void | reset_lockfree_capacity () |
| Recreates the lock-free queue, clearing all queued tasks and counters. More... | |
| bool | is_running () const |
| Reports whether the loop is currently running. More... | |
| bool | is_ready_to_quit () const |
Reports whether quit has been requested and the loop is winding down. More... | |
| bool | is_busy () const |
| Reports whether the loop is currently executing a task. More... | |
| size_t | get_task_count () const |
| Returns the current pending task count. More... | |
| virtual bool | wait_for_idle (int ms=Timer::kInfinite, bool check=true) |
| Waits until the loop has drained its queue and is not executing a task. More... | |
| virtual size_t | get_max_task_count () const |
| Returns the maximum queue depth. More... | |
| virtual size_t | get_max_timer_count () const |
| Returns the maximum number of timers that can be attached. More... | |
| virtual uint32_t | get_max_elapsed_time () const |
| Returns the maximum allowed task execution time in milliseconds. More... | |
| virtual bool | is_in_same_thread () const |
| Reports whether the calling thread is owned by this loop. More... | |
| std::shared_ptr< AliveState > | get_alive_state () const |
| Returns the shared lifetime flag used by cross-thread bridges. More... | |
| 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. More... | |
| 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) |
Priority variant of invoke_task; requires a kPriorityType loop. More... | |
Static Public Attributes | |
| static constexpr int64_t | kMaxWindowMs = std::numeric_limits<int64_t>::max() / 4000 |
| Maximum accepted pre / post / retention-guard window length in milliseconds. More... | |
Protected Member Functions | |
| void | on_begin () override |
| Hook invoked once on the loop thread before the first task runs. More... | |
| void | on_end () override |
| Hook invoked once on the loop thread after the last task runs. More... | |
| Protected Member Functions inherited from vlink::MessageLoop | |
| bool | post_untracked_task (Callback &&callback, TaskOverflowPolicy overflow_policy, TaskDropPolicy drop_policy) |
| Posts an untracked task with explicit overflow and drop policies. More... | |
| virtual void | on_idle () |
| Hook invoked on the loop thread each time the queue becomes empty. More... | |
| virtual void | on_task_changed (Callback &&callback, uint32_t start_time) |
| Dispatches a ready task on the loop thread. More... | |
| virtual void | on_task_timeout (Callback &&callback, uint32_t elapsed_time) |
Hook invoked when a task exceeds get_max_elapsed_time(). More... | |
MessageLoop-based rolling in-memory recorder that dumps a pre/post window to a bag on trigger.
Construct with a Config and RawSubFactory, call async_run(), then wait for on_begin() to complete (for example with invoke_task([](){}).wait()) before using dump(). Dumps are serialised and execute on the recorder loop. Wait for is_dumping() to become false before shutdown when an accepted dump must be preserved; quit() abandons a dump that is still waiting for its post-trigger window.
Raw byte subscriber owned by the recorder for one discovered URL.
| using vlink::TriggerRecorder::RawSubFactory = Function<std::shared_ptr<RawSub>(const std::string& url, InitType type)> |
Caller-side constructor for raw subscribers.
The factory must return a fresh subscriber for url using the supplied type. It may apply caller-side transport properties that must precede init(), but must not initialize or start listening; the recorder applies getter semantics, loss tracking, schema metadata and discovery settings before it calls init() and listen(). The callable runs synchronously on the discovery-viewer thread and therefore must be short, non-blocking and must not re-enter this recorder.
Keeping construction in the caller's translation unit is significant: the transport modules linked by the caller propagate their VLINK_SUPPORT_* definitions there, allowing the header-only URL dispatcher to select those linked backends.
| enum vlink::TriggerRecorder::FileType : uint8_t |
| enum vlink::TriggerRecorder::OverflowPolicy : uint8_t |
What to do when a byte cap (per-URL max_size or global max_cache_size) would be exceeded.
Eviction is always local to the URL receiving the incoming frame: even when the global cap is the one exceeded, kCoverOldest only reclaims space from that URL's own ring, so pressure from one URL never evicts another URL's buffered history. When the ingesting URL's ring cannot free enough space, the incoming frame is dropped.
| Enumerator | |
|---|---|
| kCoverOldest | Evict the oldest buffered frame(s) to make room for the newest. |
| kDropNewest | Discard the incoming frame and keep the existing buffer. |
| vlink::TriggerRecorder::TriggerRecorder | ( | const Config & | config, |
| RawSubFactory && | factory | ||
| ) |
Builds the recorder and acquires every fallible resource; the loop is not running yet.
Validates the configuration and factory, creates Config::dump_dir and constructs the discovery viewer. Buffering begins only after async_run().
| config | Recorder-wide configuration, copied and validated internally. |
| factory | Factory that constructs a fresh, uninitialized subscriber for each discovered URL. |
| Exception::RuntimeError | When the configuration or factory is invalid, dump_dir cannot be created, or discovery setup fails. |
|
override |
Requests quit and joins the recorder loop thread.
| void vlink::TriggerRecorder::bind_bag_interface | ( | const std::shared_ptr< BagPluginInterface > & | bag_interface | ) |
Binds the bag reorder plugin applied inside the write path of every dump.
This is the data-plane reorder plugin, distinct from the trigger plugin bound by bind_trigger_interface(). The recorder attaches it to the internal BagWriter of each dump via BagWriter::bind_bag_interface(); its on_write() hook parses the true data-plane time out of each payload and re-emits frames reordered by that time before they are persisted. The host owns plugin loading and lifetime, then supplies the resulting interface here. Passing nullptr detaches it, so dumps fall back to capture-time order. Bind before async_run() or after the recorder has stopped.
| bag_interface | Bag reorder plugin interface instance to bind, or nullptr to detach. |
| void vlink::TriggerRecorder::bind_trigger_interface | ( | const std::shared_ptr< TriggerPluginInterface > & | trigger_interface | ) |
Binds the trigger plugin notified across the recorder's life cycle and dump pipeline.
This is the post-dump behaviour plugin, distinct from the bag reorder plugin bound by bind_bag_interface(). Its hooks (see TriggerPluginInterface) fire as the recorder starts / stops, on each trigger, and around each dump – most importantly on_dump_finished() once a bag is written, the place to upload or archive it. It never rewrites frames. Passing nullptr detaches the current plugin. Bind before async_run() or after the recorder has stopped; binding while it is running is rejected so one recorder run always has one stable lifecycle observer.
| trigger_interface | Trigger plugin interface instance to bind, or nullptr to detach. |
| void vlink::TriggerRecorder::clear_bag_interface | ( | ) |
Detaches the bag reorder plugin (equivalent to bind_bag_interface(nullptr)).
| void vlink::TriggerRecorder::clear_trigger_interface | ( | ) |
Detaches the trigger plugin (equivalent to bind_trigger_interface(nullptr)).
| bool vlink::TriggerRecorder::dump | ( | const TriggerParams & | params, |
| std::string & | out_file | ||
| ) |
Requests a dump and returns its selected output path when accepted.
| params | Per-trigger overrides. |
| out_file | Selected path on success; cleared when the request is rejected. |
true when the dump was accepted and out_file was set. | bool vlink::TriggerRecorder::dump | ( | const TriggerParams & | params = {} | ) |
Requests a dump of the pre/post window around the current instant.
Non-blocking: it timestamps the trigger, rejects the call if a dump is already in flight, and enqueues the actual capture / reorder / write onto the recorder loop. When the selected URLs have a positive effective post window, execution is delayed by their largest effective post plus retention_guard_ms; otherwise it is enqueued immediately. The dump completes asynchronously. The set of participating URLs is selected and frozen when the call is accepted: topics discovered afterwards do not contribute to this dump, and a topic going offline (Config::destroy_on_offline) still contributes its already-buffered window. Calling quit() does not drain a dump that is still waiting for its post-trigger window.
| params | Optional per-trigger overrides (reason, file name, shrunk windows). |
true when the dump was accepted and enqueued; false for an invalid window, before on_begin() completes, when stopped or already dumping, or when the dump task cannot be enqueued.
|
noexcept |
Reports whether a dump is currently in flight.
true while a trigger's capture / write is running.
|
overrideprotectedvirtual |
Hook invoked once on the loop thread before the first task runs.
Subclasses override to perform per-thread initialisation.
Reimplemented from vlink::MessageLoop.
|
overrideprotectedvirtual |
Hook invoked once on the loop thread after the last task runs.
Subclasses override to perform per-thread cleanup.
Reimplemented from vlink::MessageLoop.
|
staticconstexpr |
Maximum accepted pre / post / retention-guard window length in milliseconds.
Chosen so that the largest retention sum, pre + max_post_all + 2*retention_guard (four terms, each at most this bound), still converts to microseconds without overflowing int64_t. Config values and per-trigger TriggerParams windows beyond this bound are rejected; control-plane frontends (e.g. vlink-trigger) validate user input against the same constant.
1.9.1