Abstract plugin base shared by bag playback and bag recording.
More...
#include <bag_plugin_interface.h>
Abstract plugin base shared by bag playback and bag recording.
The host binds an instance through BagReader::bind_plugin_interface() or BagWriter::bind_plugin_interface(). At bind time the host calls bind_direction() to record which side the plugin serves and register_callback() to supply the forwarding sink. Every hook carries a default implementation, so an implementation overrides only the hooks relevant to its direction (plus the mandatory get_version_info()). Implementations are expected to be thread-compatible with the host's loop thread.
◆ Callback
Forwarding sink used by do_callback() to re-emit a frame downstream.
Supplied by the host (BagReader or BagWriter) at bind time and stored internally. A single const Frame& sink serves both directions: read plugins re-emit toward playback, write plugins toward persistence.
◆ Direction
Identifies whether the plugin is bound to a reader or a writer.
| Enumerator |
|---|
| kRead | Bound to a BagReader; the plugin forwards replayed frames.
|
| kWrite | Bound to a BagWriter; the plugin forwards frames before they are persisted.
|
◆ BagPluginInterface()
| vlink::BagPluginInterface::BagPluginInterface |
( |
| ) |
|
|
protecteddefault |
◆ ~BagPluginInterface()
| virtual vlink::BagPluginInterface::~BagPluginInterface |
( |
| ) |
|
|
protectedvirtualdefault |
◆ bind_direction()
| void vlink::BagPluginInterface::bind_direction |
( |
Direction |
direction | ) |
|
|
inline |
Records the binding direction so the plugin can branch on read vs write.
Details.
Invoked by the host at attach time before any other hook. The value is observable from the hooks through get_direction().
- Parameters
-
| direction | Side the plugin is being bound to. |
◆ convert_url_meta()
| bool vlink::BagPluginInterface::convert_url_meta |
( |
std::string & |
url, |
|
|
std::string & |
ser_type, |
|
|
SchemaType & |
schema_type |
|
) |
| |
|
inlinevirtual |
Rewrites or filters a stored URL before playback begins (read side).
Called once per URL contained in the bag when the reader opens the file. Implementations may modify any of the three parameters in place to remap topics or override schema metadata. The default implementation keeps every URL unchanged.
- Parameters
-
| url | URL string; may be modified in place. |
| ser_type | Serialisation type; may be modified in place. |
| schema_type | Coarse schema family; may be modified in place. |
- Returns
true to retain the URL in playback; false to exclude it.
◆ do_callback()
| void vlink::BagPluginInterface::do_callback |
( |
const Frame & |
frame | ) |
|
|
inline |
Forwards one frame downstream through the registered sink.
The emit helper a plugin calls – typically from on_read() / on_write() or from a reorder buffer's output callback – to deliver a frame downstream without touching callback_ directly. Invokes callback_ when one is registered and is otherwise a no-op.
- Parameters
-
| frame | Frame to forward to the sink. |
◆ flush()
| void vlink::BagPluginInterface::flush |
( |
| ) |
|
|
inlinevirtual |
Drains any internally-buffered frames downstream before the host unbinds and tears down.
Called by the host on its own thread, while its sink is still valid, right before it detaches this plugin (read side: at reader teardown; write side: at writer teardown, before the recording loop is stopped). A plugin that buffers frames for asynchronous re-emit (e.g. a BagProcessor reorder buffer) must override this to flush those frames synchronously – typically processor_.flush() – so a buffered tail is recorded / replayed instead of dropped. The default implementation is a no-op (a synchronous plugin holds nothing back). After flush() returns the host stops delivering this plugin's emitted frames, so any frame produced afterwards is ignored.
◆ get_direction()
Returns the side this plugin is currently bound to.
- Returns
Direction::kRead when bound to a reader, Direction::kWrite when bound to a writer.
◆ get_version_info()
| virtual VersionInfo vlink::BagPluginInterface::get_version_info |
( |
| ) |
const |
|
pure virtual |
Returns the build identity used by the host for logging and diagnostics.
- Returns
- Populated
VersionInfo describing this plugin.
◆ on_read()
| void vlink::BagPluginInterface::on_read |
( |
const Frame & |
frame | ) |
|
|
inlinevirtual |
Intercepts a replayed frame on its way to the user (read side).
Called for every replayed frame after timing pacing. Forward it downstream by calling do_callback(); transforming the payload, dropping the frame (by not emitting), fanning it out (emitting several), or buffering and re-emitting frames reordered by data-plane time (e.g. via BagProcessor) is permitted. The default implementation forwards the frame unchanged.
- Note
frame::ser_type / schema_type are empty on the read side; query BagReader::get_ser_type() / get_schema_type() (or stash them from convert_url_meta()) if needed. The payload is a shallow view valid for the duration of the call; copy it before buffering for asynchronous emit.
- Parameters
-
◆ on_write()
| void vlink::BagPluginInterface::on_write |
( |
const Frame & |
frame | ) |
|
|
inlinevirtual |
Intercepts a frame before it is persisted (write side).
Called for every frame handed to the writer, before it is recorded. Re-emit it by calling do_callback(). Transcoding (rewrite frame.data plus frame.ser_type / schema_type, e.g. raw image to JPEG), dropping the frame (by not emitting), fanning it out, or buffering and re-emitting frames reordered by data-plane time (a sliding-window reorder, e.g. via BagProcessor) is permitted. The default implementation forwards the frame unchanged.
- Note
- The payload is a view valid for the duration of the call; a plugin that emits asynchronously must copy it before buffering.
-
When a plugin renames the URL, the recorder learns the source-to-recorded mapping only for synchronous emits (within this
on_write() call) and only when the rewrite is one-to-one, so URL-level metadata such as loss stays correctly attributed. A plugin that both renames and emits asynchronously is responsible for any loss attribution itself.
-
BagWriter::push() resolves a negative Frame::timestamp to the writer clock before calling this hook; that auto-assignment does not re-run on the frames a plugin emits. A re-emitted frame is persisted with its own Frame::timestamp verbatim, so a plugin that constructs a fresh frame must set a resolved (non-negative) timestamp on it.
- Parameters
-
◆ register_callback()
| void vlink::BagPluginInterface::register_callback |
( |
Callback && |
callback | ) |
|
|
inline |
Stores the forwarding sink used by do_callback().
Invoked by the host's bind_plugin_interface() at attach time. The plugin keeps callback in callback_ and calls it from do_callback() to deliver a frame downstream – toward the user's playback callback on the read side, or toward persistence on the write side. Cleared (with an empty callable) on rebind and at host teardown, so a plugin-owned worker thread cannot reach a destroyed host.
- Parameters
-
| callback | Sink that forwards a frame downstream. |
◆ direction_
| Direction vlink::BagPluginInterface::direction_ {Direction::kRead} |
|
protected |
The documentation for this class was generated from the following file:
1.9.1