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_bag_interface() or BagWriter::bind_bag_interface(). At bind time the host calls bind_direction() to record which side the plugin serves and register_callback() to supply the forwarding sink. The frame hooks on_read() and on_write() are pure and must both be defined; convert_url_meta(), on_reset(), and flush() carry defaults. 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, after each naturally completed read-side playback pass and right before either side detaches the plugin. An interrupted pass skips this boundary call. 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 and cannot leak into the next playback pass. The default implementation is a no-op (a synchronous plugin holds nothing back). On detach, 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.
◆ on_read()
| virtual void vlink::BagPluginInterface::on_read |
( |
const Frame & |
frame | ) |
|
|
pure virtual |
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.
- Note
Frame::ser_type and Frame::schema_type contain the effective URL metadata, including overrides made by convert_url_meta(). The payload is a shallow view valid for the duration of the call; copy it before buffering for asynchronous emit.-
Prefer
convert_url_meta() for stable URL remapping. If this hook emits a frame under a different URL, existing type fields remain authoritative because the plugin may have renamed a TypeA payload or transcoded it intentionally. To resolve metadata registered for the emitted URL, clear ser_type and set schema_type to SchemaType::kUnknown before calling do_callback(); otherwise update both fields to describe the emitted payload explicitly.
- Parameters
-
◆ on_reset()
| void vlink::BagPluginInterface::on_reset |
( |
| ) |
|
|
inlinevirtual |
Discards state retained from an earlier read-side playback session.
Called synchronously before a reader starts each top-level playback session and before its ready callback. A plugin that buffers frames must override this to discard the cache and reset all time anchors without emitting frames, typically with processor_.reset(). This isolates a new play or jump from frames retained when the preceding session was interrupted. The default implementation is a no-op for synchronous plugins. The writer does not call this hook.
◆ on_write()
| virtual void vlink::BagPluginInterface::on_write |
( |
const Frame & |
frame | ) |
|
|
pure virtual |
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.
- 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_bag_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