Abstract plugin base notified across a TriggerRecorder's life cycle and dump pipeline. More...

#include <trigger_plugin_interface.h>

Collaboration diagram for vlink::TriggerPluginInterface:

Classes
struct	DumpContext
	Describes the dump currently being written, delivered to `on_dump_started()` / `on_frame()`. More...

struct	DumpResult
	Final outcome of a dump, delivered to `on_dump_finished()` / `on_dump_failed()`. More...

struct	TriggerContext
	Describes an accepted trigger request, delivered to `on_trigger()`. More...

Public Member Functions
virtual bool	init (const std::string &config)=0
	Initialises the plugin with an opaque configuration string. More...

virtual void	on_start ()
	Notifies the plugin that the recorder has started. More...

virtual void	on_stop ()
	Notifies the plugin that the recorder is stopping. More...

virtual void	on_trigger (const TriggerContext &context)
	Notifies the plugin that a trigger was accepted and a dump is about to run. More...

virtual void	on_dump_started (const DumpContext &context)
	Notifies the plugin that the output file has been opened and writing is beginning. More...

virtual void	on_frame (const Frame &frame, const DumpContext &context)
	Inspects each frame as it is submitted to the writer (hot path). More...

virtual void	on_dump_finished (const DumpResult &result)=0
	Notifies the plugin that the dump file has been fully written and closed. More...

virtual void	on_dump_failed (const DumpResult &result)
	Notifies the plugin that a dump was aborted before completion. More...

virtual void	on_file_rotated (const std::string &path)
	Notifies the plugin that an old dump file was removed by rotation. More...

virtual void	flush ()
	Drains any plugin-internal asynchronous work before the host unbinds or tears down. More...

Protected Member Functions
	TriggerPluginInterface ()=default

virtual	~TriggerPluginInterface ()=default

Detailed Description

Abstract plugin base notified across a TriggerRecorder's life cycle and dump pipeline.

The host binds an instance through TriggerRecorder::bind_trigger_interface() and calls each hook at the corresponding stage. Implementations provide init() and on_dump_finished(); the remaining hooks have default no-op implementations. Implementations must follow the threading contract documented above.

Constructor & Destructor Documentation

◆ TriggerPluginInterface()

vlink::TriggerPluginInterface::TriggerPluginInterface ( )

protecteddefault

◆ ~TriggerPluginInterface()

virtual vlink::TriggerPluginInterface::~TriggerPluginInterface ( )

protectedvirtualdefault

Member Function Documentation

◆ flush()

void vlink::TriggerPluginInterface::flush ( )

inlinevirtual

Drains any plugin-internal asynchronous work before the host unbinds or tears down.

Invoked by the host while the plugin is still valid, right before it detaches this plugin (at recorder stop / teardown). A plugin that offloads work to a background worker (e.g. an upload queue) must override this to finish or checkpoint that work synchronously, so pending uploads are not lost. Default: no-op.

◆ init()

virtual bool vlink::TriggerPluginInterface::init ( const std::string & config )

pure virtual

Initialises the plugin with an opaque configuration string.

Called once by a plugin-loading host before the plugin is bound to a recorder. The string may be a file path, JSON document or any other format defined by the plugin. Programmatically constructed plugins call this method themselves when configuration is required.

Parameters

config Plugin-defined configuration; may be empty.

Returns: true on success; false makes the host reject the plugin.

◆ on_dump_failed()

void vlink::TriggerPluginInterface::on_dump_failed ( const DumpResult & result )

inlinevirtual

Notifies the plugin that a dump was aborted before completion.

Invoked on the recorder's loop thread when the writer could not be created, the write failed, or an accepted delayed dump was abandoned during shutdown. Default: no-op.

Parameters

result Dump outcome, with success set to false and error describing the failure.

◆ on_dump_finished()

virtual void vlink::TriggerPluginInterface::on_dump_finished ( const DumpResult & result )

pure virtual

Notifies the plugin that the dump file has been fully written and closed.

The primary lifecycle hook: invoked on the recorder's loop thread once the bag is finalised. The place to upload, archive, or notify. Slow work here blocks the next dump – offload to a worker and drain it in flush().

Parameters

result Final dump outcome, with success set to true.

◆ on_dump_started()

void vlink::TriggerPluginInterface::on_dump_started ( const DumpContext & context )

inlinevirtual

Notifies the plugin that the output file has been opened and writing is beginning.

Invoked on the recorder's loop thread after the bag writer is created, before frames are written. Default: no-op.

Parameters

context Dump-in-progress details.

◆ on_file_rotated()

void vlink::TriggerPluginInterface::on_file_rotated ( const std::string & path )

inlinevirtual

Notifies the plugin that an old dump file was removed by rotation.

Invoked on the recorder's loop thread each time file rotation deletes an aged-out dump, so a plugin mirroring files to a backend can mirror the deletion. Default: no-op.

Parameters

path	Path of the file that was deleted.

◆ on_frame()

void vlink::TriggerPluginInterface::on_frame	(	const Frame &	frame,
		const DumpContext &	context
	)

inlinevirtual

Inspects each frame as it is submitted to the writer (hot path).

Invoked on the recorder's loop thread once per frame successfully handed to the writer, in ascending capture-time order. A frame the writer fails to persist aborts the dump and is not reported here. This observes submission, not final persistence: a bound bag reorder plugin may still reorder or drop the frame downstream before it reaches disk. Runs for potentially many frames, so keep the implementation cheap; it cannot alter or drop the frame. Default: no-op.

Parameters

frame	Submitted frame (payload is a shallow view valid for the call).
context	Dump-in-progress details.

◆ on_start()

void vlink::TriggerPluginInterface::on_start ( )

inlinevirtual

Notifies the plugin that the recorder has started.

Details.

Invoked on the recorder's loop thread during TriggerRecorder::async_run(), after discovery is running. A place to acquire long-lived resources such as an upload session. Default: no-op.

◆ on_stop()

void vlink::TriggerPluginInterface::on_stop ( )

inlinevirtual

Notifies the plugin that the recorder is stopping.

Invoked on the recorder's loop thread during shutdown. A place to release resources acquired in on_start(). Default: no-op.

◆ on_trigger()

void vlink::TriggerPluginInterface::on_trigger ( const TriggerContext & context )

inlinevirtual

Notifies the plugin that a trigger was accepted and a dump is about to run.

Invoked on the recorder's loop thread after the requested window has been snapshotted and before the bag writer is opened. Slow work delays persistence but does not change the captured window. Default: no-op.

Parameters

context Accepted trigger request details.

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

include/vlink/extension/trigger_plugin_interface.h

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TriggerPluginInterface()

◆ ~TriggerPluginInterface()

Member Function Documentation

◆ flush()

◆ init()

◆ on_dump_failed()

◆ on_dump_finished()

◆ on_dump_started()

◆ on_file_rotated()

◆ on_frame()

◆ on_start()

◆ on_stop()

◆ on_trigger()