MessageLoop-based rolling in-memory recorder that dumps a pre/post window to a bag on trigger. 更多...

#include <trigger_recorder.h>

类 vlink::TriggerRecorder 继承关系图:

vlink::TriggerRecorder 的协作图:

类
struct	Config
	Recorder-wide configuration; passed once to the constructor and read-only afterwards. 更多...

struct	TriggerParams
	Per-trigger parameters; a pure data struct with no RPC or protobuf dependency. 更多...

struct	UrlConfig
	Per-URL overrides; any field left negative falls back to the matching `Config` default. 更多...

Public 类型
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. 更多...

enum	FileType : uint8_t { kVdb = 0 , kVcap = 1 }
	On-disk container format for the dumped bag. 更多...

using	RawSub = Subscriber< Bytes >
	Raw byte subscriber owned by the recorder for one discovered URL. 更多...

using	RawSubFactory = Function< std::shared_ptr< RawSub >(const std::string &url, InitType type)>
	Caller-side constructor for raw subscribers. 更多...

Public 类型继承自 vlink::MessageLoop
enum	Type : uint8_t { kNormalType = 0 , kLockfreeType = 1 , kPriorityType = 2 }
	Internal queue implementation type. 更多...

enum	Strategy : uint8_t { kOptimizationStrategy = 0 , kPopStrategy = 1 , kBlockStrategy = 2 }
	Back-pressure strategy applied when the bounded queue is at capacity. 更多...

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. 更多...

using	Callback = MoveFunction< void()>
	Callback type for tasks and event handlers. 更多...

Public 成员函数
	TriggerRecorder (const Config &config, RawSubFactory &&factory)
	Builds the recorder and acquires every fallible resource; the loop is not running yet. 更多...

	~TriggerRecorder () override
	Requests quit and joins the recorder loop thread. 更多...

bool	dump (const TriggerParams &params={})
	Requests a dump of the pre/post window around the current instant. 更多...

bool	dump (const TriggerParams &params, std::string &out_file)
	Requests a dump and returns its selected output path when accepted. 更多...

bool	is_dumping () const noexcept
	Reports whether a dump is currently in flight. 更多...

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. 更多...

void	clear_trigger_interface ()
	Detaches the trigger plugin (equivalent to `bind_trigger_interface(nullptr)`). 更多...

void	bind_bag_interface (const std::shared_ptr< BagPluginInterface > &bag_interface)
	Binds the bag reorder plugin applied inside the write path of every dump. 更多...

void	clear_bag_interface ()
	Detaches the bag reorder plugin (equivalent to `bind_bag_interface(nullptr)`). 更多...

Public 成员函数继承自 vlink::MessageLoop
	MessageLoop ()
	Constructs a loop with the default `kNormalType` queue. 更多...

	MessageLoop (Type type)
	Constructs a loop with the given queue type. 更多...

virtual	~MessageLoop ()
	Destructor; requests quit and joins the dispatcher thread if needed. 更多...

void	set_name (const std::string &name)
	Sets a human-readable name visible to profiling tools. 更多...

const std::string &	get_name () const
	Returns the loop name set via `set_name`. 更多...

Type	get_type () const
	Returns the queue type this loop was constructed with. 更多...

Strategy	get_strategy () const
	Returns the active back-pressure strategy. 更多...

void	set_strategy (Strategy strategy)
	Replaces the back-pressure strategy. 更多...

void	register_begin_handler (Callback &&callback)
	Registers a callback fired once at loop thread startup. 更多...

void	register_end_handler (Callback &&callback)
	Registers a callback fired once when the loop thread exits. 更多...

void	register_idle_handler (Callback &&callback)
	Registers a callback fired every time the queue becomes empty. 更多...

bool	run ()
	Runs the loop on the calling thread until `quit` is requested. 更多...

bool	async_run ()
	Starts the loop on a new background thread. 更多...

bool	spin ()
	Alias of `run` blocking the calling thread. 更多...

bool	spin_once (bool block=true)
	Processes one batch of pending tasks and timers on the calling thread. 更多...

bool	quit (bool force=false)
	Requests the loop to exit. 更多...

bool	wait_for_quit (int ms=Timer::kInfinite, bool check=true)
	Waits until the loop has fully exited. 更多...

bool	post_task (Callback &&callback)
	Posts a task for execution on the loop thread. 更多...

TaskHandle	post_task_handle (Callback &&callback, const PostTaskOptions &options={})
	Tracked variant of `post_task` returning a `TaskHandle`. 更多...

bool	post_task_with_priority (Callback &&callback, uint16_t priority)
	Posts a task with an explicit priority on a `kPriorityType` loop. 更多...

TaskHandle	post_task_with_priority_handle (Callback &&callback, uint16_t priority, const PostTaskOptions &options={})
	Tracked variant of `post_task_with_priority` returning a `TaskHandle`. 更多...

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`. 更多...

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`. 更多...

bool	wakeup ()
	Wakes the loop thread if it is suspended in its idle wait. 更多...

void	reset_lockfree_capacity ()
	Recreates the lock-free queue, clearing all queued tasks and counters. 更多...

bool	is_running () const
	Reports whether the loop is currently running. 更多...

bool	is_ready_to_quit () const
	Reports whether `quit` has been requested and the loop is winding down. 更多...

bool	is_busy () const
	Reports whether the loop is currently executing a task. 更多...

size_t	get_task_count () const
	Returns the current pending task count. 更多...

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. 更多...

virtual size_t	get_max_task_count () const
	Returns the maximum queue depth. 更多...

virtual size_t	get_max_timer_count () const
	Returns the maximum number of timers that can be attached. 更多...

virtual uint32_t	get_max_elapsed_time () const
	Returns the maximum allowed task execution time in milliseconds. 更多...

virtual bool	is_in_same_thread () const
	Reports whether the calling thread is owned by this loop. 更多...

std::shared_ptr< AliveState >	get_alive_state () const
	Returns the shared lifetime flag used by cross-thread bridges. 更多...

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)
	Priority variant of `invoke_task`; requires a `kPriorityType` loop. 更多...

静态 Public 属性
static constexpr int64_t	kMaxWindowMs = std::numeric_limits<int64_t>::max() / 4000
	Maximum accepted pre / post / retention-guard window length in milliseconds. 更多...

Protected 成员函数
void	on_begin () override
	Hook invoked once on the loop thread before the first task runs. 更多...

void	on_end () override
	Hook invoked once on the loop thread after the last task runs. 更多...

Protected 成员函数继承自 vlink::MessageLoop
bool	post_untracked_task (Callback &&callback, TaskOverflowPolicy overflow_policy, TaskDropPolicy drop_policy)
	Posts an untracked task with explicit overflow and drop policies. 更多...

virtual void	on_idle ()
	Hook invoked on the loop thread each time the queue becomes empty. 更多...

virtual void	on_task_changed (Callback &&callback, uint32_t start_time)
	Dispatches a ready task on the loop thread. 更多...

virtual void	on_task_timeout (Callback &&callback, uint32_t elapsed_time)
	Hook invoked when a task exceeds `get_max_elapsed_time()`. 更多...

详细描述

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.

成员类型定义说明

◆ RawSub

using vlink::TriggerRecorder::RawSub = Subscriber<Bytes>

Raw byte subscriber owned by the recorder for one discovered URL.

◆ RawSubFactory

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.

成员枚举类型说明

◆ FileType

enum vlink::TriggerRecorder::FileType : uint8_t

On-disk container format for the dumped bag.

枚举值
kVdb	SQLite-backed VDB container (.vdb).
kVcap	MCAP container (.vcap).

◆ OverflowPolicy

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.

枚举值
kCoverOldest	Evict the oldest buffered frame(s) to make room for the newest.
kDropNewest	Discard the incoming frame and keep the existing buffer.

构造及析构函数说明

◆ TriggerRecorder()

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.

◆ ~TriggerRecorder()

vlink::TriggerRecorder::~TriggerRecorder ( )

override

Requests quit and joins the recorder loop thread.

成员函数说明

◆ bind_bag_interface()

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.

◆ bind_trigger_interface()

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.

◆ clear_bag_interface()

void vlink::TriggerRecorder::clear_bag_interface ( )

Detaches the bag reorder plugin (equivalent to bind_bag_interface(nullptr)).

◆ clear_trigger_interface()

void vlink::TriggerRecorder::clear_trigger_interface ( )

Detaches the trigger plugin (equivalent to bind_trigger_interface(nullptr)).

◆ dump() [1/2]

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.

◆ dump() [2/2]

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.

◆ is_dumping()

bool vlink::TriggerRecorder::is_dumping ( ) const

noexcept

Reports whether a dump is currently in flight.

返回: true while a trigger's capture / write is running.

◆ on_begin()

void vlink::TriggerRecorder::on_begin ( )

overrideprotectedvirtual

Hook invoked once on the loop thread before the first task runs.

Subclasses override to perform per-thread initialisation.

重载 vlink::MessageLoop .

◆ on_end()

void vlink::TriggerRecorder::on_end ( )

overrideprotectedvirtual

Hook invoked once on the loop thread after the last task runs.

Subclasses override to perform per-thread cleanup.

重载 vlink::MessageLoop .

类成员变量说明

◆ kMaxWindowMs

constexpr int64_t vlink::TriggerRecorder::kMaxWindowMs = std::numeric_limits<int64_t>::max() / 4000

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.

该类的文档由以下文件生成:

include/vlink/extension/trigger_recorder.h

类

Public 类型

Public 成员函数

静态 Public 属性

Protected 成员函数

详细描述

成员类型定义说明

◆ RawSub

◆ RawSubFactory

成员枚举类型说明

◆ FileType

◆ OverflowPolicy

构造及析构函数说明

◆ TriggerRecorder()

◆ ~TriggerRecorder()

成员函数说明

◆ bind_bag_interface()

◆ bind_trigger_interface()

◆ clear_bag_interface()

◆ clear_trigger_interface()

◆ dump() [1/2]

◆ dump() [2/2]

◆ is_dumping()

◆ on_begin()

◆ on_end()

类成员变量说明

◆ kMaxWindowMs