Abstract VLink bag file player with time control, seeking, and integrity tools. More...

#include <bag_reader.h>

Inheritance diagram for vlink::BagReader:

Collaboration diagram for vlink::BagReader:

Classes
struct	Info
	Metadata extracted from the bag file header and index. More...
struct	Config
	Playback configuration passed to `play()`. More...

Public Types
enum	Status : uint8_t { kStoped = 0 , kPaused = 1 , kPlaying = 2 }
	Playback state of the reader. More...
using	OutputCallback
	Callback type fired for each replayed message.
using	StatusCallback = std::function<void(Status status)>
	Callback fired whenever the playback `Status` changes.
using	ReadyCallback = std::function<void()>
	Callback fired when the reader has opened the file and is ready to start playing.
using	FinishCallback = std::function<void(bool is_interrupted)>
	Callback fired when playback has finished (or was interrupted).
Public Types inherited from vlink::MessageLoop
enum	Type : uint8_t { kNormalType = 0 , kLockfreeType = 1 , kPriorityType = 2 }
	Queue implementation type. More...
enum	Strategy : uint8_t { kOptimizationStrategy = 0 , kPopStrategy = 1 , kBlockStrategy = 2 }
	Idle strategy controlling CPU and latency trade-offs. More...
enum	Priority : uint16_t { kNoPriority = 0 , kLowestPriority = 1 , kTimerPriority = 50 , kNormalPriority = 100 , kHighestPriority = std::numeric_limits<uint16_t>::max() }
	Pre-defined task priority levels for `kPriorityType` loops. More...
using	Callback = std::function<void()>
	Callback type for tasks and event handlers.

Public Member Functions
	BagReader (const std::string &path, bool read_only=true, bool try_to_fix=false)
	Constructs the reader for `path`.
virtual	~BagReader ()
	Destructor – stops playback and releases file resources.
virtual void	bind_plugin_interface (const std::shared_ptr< BagReaderPluginInterface > &plugin_interface)
	Attaches a `BagReaderPluginInterface` for custom URL/type conversion.
virtual void	register_status_callback (StatusCallback &&status_callback)
	Registers a callback fired whenever the playback status changes.
virtual void	register_ready_callback (ReadyCallback &&ready_callback)
	Registers a callback fired when the reader is ready to start playing.
virtual void	register_finish_callback (FinishCallback &&finish_callback)
	Registers a callback fired when playback ends or is interrupted.
virtual void	register_output_callback (OutputCallback &&output_callback)
	Registers the callback that receives replayed messages.
virtual void	play (const Config &config)=0
	Starts playback with the given `config`.
virtual void	stop ()=0
	Stops playback and resets the reader to the beginning.
virtual void	pause ()=0
	Pauses playback at the current position.
virtual void	resume ()=0
	Resumes a paused playback from the current position.
virtual void	pause_to_next ()=0
	Advances one message while paused, then pauses again.
virtual void	jump (int64_t begin_time, double rate, int times, bool force_to_play=false)=0
	Seeks to `begin_time` and resumes playback at `rate` with `times` loops.
virtual std::future< bool >	check ()=0
	Verifies the integrity of the bag file asynchronously.
virtual std::future< bool >	reindex ()=0
	Rebuilds the index tables asynchronously.
virtual std::future< bool >	fix (bool rebuild=false)=0
	Repairs a corrupt bag file asynchronously.
virtual void	tag (const std::string &tag_name)=0
	Updates the tag name stored in the bag's metadata.
virtual int64_t	get_timestamp () const =0
	Returns the current playback position as a recording timestamp.
virtual int64_t	get_real_timestamp () const =0
	Returns the current playback position in real elapsed time.
virtual Status	get_status () const =0
	Returns the current playback status.
virtual const Info &	get_info () const =0
	Returns the bag file metadata and per-URL statistics.
virtual std::vector< SchemaData >	detect_schema ()=0
	Scans the bag and returns all embedded schemas.
virtual std::string	get_ser_type (const std::string &url) const =0
	Returns the serialisation type string for a given `url`.
virtual SchemaType	get_schema_type (const std::string &url) const =0
	Returns the coarse schema family for a given `url`.
virtual bool	is_split_mode () const =0
	Returns `true` if the bag spans multiple split files.
virtual int	get_split_index () const =0
	Returns the zero-based index of the current split file being read.
virtual bool	is_jumping () const =0
	Returns `true` if a jump-to-timestamp seek is currently in progress.
Public Member Functions inherited from vlink::MessageLoop
	MessageLoop ()
	Constructs a `MessageLoop` with `kNormalType` queue.
	MessageLoop (Type type)
	Constructs a `MessageLoop` with the specified queue type.
virtual	~MessageLoop ()
	Destructor. Calls `quit(true)` and waits for the background thread (if any).
void	set_name (const std::string &name)
	Sets a human-readable name for this loop (visible in profiling tools).
const std::string &	get_name () const
	Returns the name set via `set_name()`.
Type	get_type () const
	Returns the queue type this loop was constructed with.
Strategy	get_strategy () const
	Returns the current idle dispatch strategy.
void	set_strategy (Strategy strategy)
	Changes the idle dispatch strategy.
void	register_begin_handler (Callback &&callback)
	Registers a callback invoked once when the loop thread starts.
void	register_end_handler (Callback &&callback)
	Registers a callback invoked once when the loop thread exits.
void	register_idle_handler (Callback &&callback)
	Registers a callback invoked each time the task queue becomes empty.
bool	run ()
	Runs the message loop on the calling thread (blocking).
bool	async_run ()
	Starts the message loop on a new background thread (non-blocking).
bool	spin ()
	Runs the loop continuously in a spin mode (blocking; no background thread).
bool	spin_once (bool block=true)
	Processes one batch of pending tasks and timers.
bool	quit (bool force=false)
	Requests the loop to exit cleanly.
bool	wait_for_idle (int ms=Timer::kInfinite, bool check=true)
	Waits until the task queue is drained.
bool	wait_for_quit (int ms=Timer::kInfinite, bool check=true)
	Waits until the loop has fully exited (after `quit()` was called).
bool	post_task (Callback &&callback)
	Posts a task to the queue for execution on the loop thread.
bool	post_task_with_priority (Callback &&callback, uint16_t priority)
	Posts a task with an explicit priority (requires `kPriorityType` loop).
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)
	Posts a scheduled task and returns a `Schedule::Status` for chaining callbacks.
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)
	Posts a scheduled task and returns a `Schedule::RetStatus` for chaining callbacks.
bool	wakeup ()
	Wakes the loop thread if it is sleeping (e.g., in `kBlockStrategy`).
void	reset_lockfree_capacity ()
	Resets the lock-free queue to its initial capacity.
bool	is_running () const
	Returns `true` if the loop is currently running (started and not quit).
bool	is_ready_to_quit () const
	Returns `true` if `quit()` has been called and the loop is winding down.
bool	is_busy () const
	Returns `true` if the loop is currently executing a task.
size_t	get_task_count () const
	Returns the number of tasks currently in the queue.
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 to this loop.
virtual uint32_t	get_max_elapsed_time () const
	Returns the maximum allowed task execution time in milliseconds.
virtual bool	is_in_same_thread () const
	Returns `true` if the calling thread is the same as the loop thread.
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)
	Dispatches a callable with an explicit priority and returns a `std::future`.

Static Public Member Functions
static std::shared_ptr< BagReader >	create (const std::string &path, bool read_only=true, bool try_to_fix=false)
	Creates a concrete `BagReader` for `path`, selecting the implementation by extension.

Static Public Attributes
static constexpr int	kInfinite {-1}
	Sentinel value for the `Config::times` field to indicate endless loop playback.

Protected Member Functions
void	process_output (int64_t timestamp, const std::string &url, ActionType action_type, const Bytes &data)
void	process_url_metas (std::vector< Info::UrlMeta > &url_metas)
Protected Member Functions inherited from vlink::MessageLoop
virtual void	on_begin ()
	Called from the loop thread just before the first task is processed.
virtual void	on_end ()
	Called from the loop thread just after the last task has been processed.
virtual void	on_idle ()
	Called from the loop thread each time the queue becomes empty.
virtual void	on_task_changed (Callback &&callback, uint32_t start_time)
	Called before each task is executed.
virtual void	on_task_timeout (Callback &&callback, uint32_t elapsed_time)
	Called when a task's execution time exceeds `get_max_elapsed_time()`.

Static Protected Member Functions
static void	rebuild_url_meta_maps (const std::vector< Info::UrlMeta > &url_metas, std::unordered_map< std::string, std::string > &ser_map, std::unordered_map< std::string, SchemaType > &schema_type_map)
	Rebuilds URL metadata lookup maps after plugin remapping.
static ActionType	convert_action (std::string_view str)

Detailed Description

Abstract VLink bag file player with time control, seeking, and integrity tools.

Inherits MessageLoop to drive playback on a dedicated thread. Concrete subclasses (DatabaseReader, McapReader) implement format-specific I/O.

Member Typedef Documentation

◆ FinishCallback

using vlink::BagReader::FinishCallback = std::function<void(bool is_interrupted)>

Callback fired when playback has finished (or was interrupted).

Parameters

is_interrupted true if stop() was called before natural end.

◆ OutputCallback

using vlink::BagReader::OutputCallback

Initial value:

std::function<void(int64_t microseconds_timestamp, const std::string& url,

ActionType action_type, const Bytes& data)>

vlink::Bytes

Versatile 128-byte byte buffer with SBO, five ownership modes and compression helpers.

Definition bytes.h:113

vlink::ActionType

ActionType

Identifies the type of message action for recording purposes.

Definition types.h:162

Callback type fired for each replayed message.

Called on the BagReader's loop thread. The data reference is valid only for the duration of the callback.

Parameters

microseconds_timestamp	Message timestamp in microseconds.
url	Topic URL string.
action_type	Action type (kPublish, kRequest, etc.).
data	Serialized message payload.

◆ ReadyCallback

using vlink::BagReader::ReadyCallback = std::function<void()>

Callback fired when the reader has opened the file and is ready to start playing.

◆ StatusCallback

using vlink::BagReader::StatusCallback = std::function<void(Status status)>

Callback fired whenever the playback Status changes.

Parameters

status New playback status.

Member Enumeration Documentation

◆ Status

enum vlink::BagReader::Status : uint8_t

Playback state of the reader.

State	Description
kStopped	Not playing; reset to beginning
kPaused	Playback suspended; can be resumed
kPlaying	Actively delivering messages to the callback

Enumerator
kStoped	Stopped (not playing).
kPaused	Paused mid-playback.
kPlaying	Actively playing.

Constructor & Destructor Documentation

◆ BagReader()

vlink::BagReader::BagReader	(	const std::string &	path,
		bool	read_only = true,
		bool	try_to_fix = false )

explicit

Constructs the reader for path.

Parameters

path	Path to the bag file.
read_only	Open in read-only mode.
try_to_fix	Attempt repair if the file is corrupt.

Here is the caller graph for this function:

◆ ~BagReader()

virtual vlink::BagReader::~BagReader ( )

virtual

Destructor – stops playback and releases file resources.

Member Function Documentation

◆ bind_plugin_interface()

virtual void vlink::BagReader::bind_plugin_interface ( const std::shared_ptr< BagReaderPluginInterface > & plugin_interface )

virtual

Attaches a BagReaderPluginInterface for custom URL/type conversion.

The plugin's convert_url_meta() is called for each URL in the bag to allow remapping before messages are dispatched to OutputCallback.

Parameters

plugin_interface Plugin to bind. May be nullptr to detach.

Reimplemented in vlink::DatabaseReader, and vlink::McapReader.

◆ check()

virtual std::future< bool > vlink::BagReader::check ( )

pure virtual

Verifies the integrity of the bag file asynchronously.

Returns: std::future<bool> that resolves to true if the file is intact.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ convert_action()

ActionType vlink::BagReader::convert_action ( std::string_view str )

staticprotected

Here is the call graph for this function:

◆ create()

std::shared_ptr< BagReader > vlink::BagReader::create	(	const std::string &	path,
		bool	read_only = true,
		bool	try_to_fix = false )

staticnodiscard

Creates a concrete BagReader for path, selecting the implementation by extension.

.vcap / .vcapx – McapReader (MCAP format)
All other extensions – DatabaseReader (SQLite)

Parameters

path	Path to the bag file.
read_only	If `true`, open in read-only mode (no write operations).
try_to_fix	If `true`, attempt to repair a corrupt bag on open.

Returns: Shared pointer to the new reader.

◆ detect_schema()

virtual std::vector< SchemaData > vlink::BagReader::detect_schema ( )

nodiscardpure virtual

Scans the bag and returns all embedded schemas.

Returns: Vector of SchemaData descriptors found in the bag.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ fix()

virtual std::future< bool > vlink::BagReader::fix ( bool rebuild = false )

pure virtual

Repairs a corrupt bag file asynchronously.

Parameters

rebuild If true, rebuilds the entire index from scratch.

Returns: std::future<bool> that resolves to true if repair succeeded.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ get_info()

virtual const Info & vlink::BagReader::get_info ( ) const

nodiscardpure virtual

Returns the bag file metadata and per-URL statistics.

Returns: Const reference to the Info struct populated at open time.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ get_real_timestamp()

virtual int64_t vlink::BagReader::get_real_timestamp ( ) const

nodiscardpure virtual

Returns the current playback position in real elapsed time.

Returns: Elapsed time since playback started (milliseconds).

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ get_schema_type()

virtual SchemaType vlink::BagReader::get_schema_type ( const std::string & url ) const

nodiscardpure virtual

Returns the coarse schema family for a given url.

Parameters

url	Topic URL to look up.

Returns: Schema family, or SchemaType::kUnknown if unavailable.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ get_ser_type()

virtual std::string vlink::BagReader::get_ser_type ( const std::string & url ) const

nodiscardpure virtual

Returns the serialisation type string for a given url.

Parameters

url	Topic URL to look up.

Returns: Serialisation type (e.g., "demo.proto.PointCloud"), or an empty string if unknown.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ get_split_index()

virtual int vlink::BagReader::get_split_index ( ) const

nodiscardpure virtual

Returns the zero-based index of the current split file being read.

Returns: Current split file index, or 0 for single-file bags.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ get_status()

virtual Status vlink::BagReader::get_status ( ) const

nodiscardpure virtual

Returns the current playback status.

Returns: One of kStopped, kPaused, or kPlaying.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ get_timestamp()

virtual int64_t vlink::BagReader::get_timestamp ( ) const

nodiscardpure virtual

Returns the current playback position as a recording timestamp.

Returns: Current message timestamp in milliseconds (recording time, relative to start).

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ is_jumping()

virtual bool vlink::BagReader::is_jumping ( ) const

nodiscardpure virtual

Returns true if a jump-to-timestamp seek is currently in progress.

Returns: true while seeking.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ is_split_mode()

virtual bool vlink::BagReader::is_split_mode ( ) const

nodiscardpure virtual

Returns true if the bag spans multiple split files.

Returns: true when reading a split bag.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ jump()

virtual void vlink::BagReader::jump	(	int64_t	begin_time,
		double	rate,
		int	times,
		bool	force_to_play = false )

pure virtual

Seeks to begin_time and resumes playback at rate with times loops.

Parameters

begin_time	Seek target timestamp in milliseconds (relative to recording start).
rate	New playback rate multiplier.
times	Number of loops after the jump.
force_to_play	If `true`, forces play state even if currently paused.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ pause()

virtual void vlink::BagReader::pause ( )

pure virtual

Pauses playback at the current position.

Transitions from kPlaying to kPaused.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ pause_to_next()

virtual void vlink::BagReader::pause_to_next ( )

pure virtual

Advances one message while paused, then pauses again.

Useful for single-stepping through a bag in debug sessions.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ play()

virtual void vlink::BagReader::play ( const Config & config )

pure virtual

Starts playback with the given config.

Must be called after async_run(). The reader transitions to kPlaying.

Parameters

config Playback configuration.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ process_output()

void vlink::BagReader::process_output	(	int64_t	timestamp,
		const std::string &	url,
		ActionType	action_type,
		const Bytes &	data )

protected

◆ process_url_metas()

void vlink::BagReader::process_url_metas ( std::vector< Info::UrlMeta > & url_metas )

protected

◆ rebuild_url_meta_maps()

void vlink::BagReader::rebuild_url_meta_maps	(	const std::vector< Info::UrlMeta > &	url_metas,
		std::unordered_map< std::string, std::string > &	ser_map,
		std::unordered_map< std::string, SchemaType > &	schema_type_map )

staticprotected

Rebuilds URL metadata lookup maps after plugin remapping.

Reader implementations call this after process_url_metas() mutates the per-URL metadata list, ensuring get_ser_type() and get_schema_type() both observe the remapped metadata instead of stale pre-plugin entries.

Parameters

url_metas	Remapped URL metadata list.
ser_map	Output lookup map: URL -> serialisation type.
schema_type_map	Output lookup map: URL -> coarse schema family.

◆ register_finish_callback()

virtual void vlink::BagReader::register_finish_callback ( FinishCallback && finish_callback )

virtual

Registers a callback fired when playback ends or is interrupted.

Parameters

finish_callback Callback receiving is_interrupted flag.

Reimplemented in vlink::DatabaseReader, and vlink::McapReader.

◆ register_output_callback()

virtual void vlink::BagReader::register_output_callback ( OutputCallback && output_callback )

virtual

Registers the callback that receives replayed messages.

Parameters

output_callback Called for each message during playback.

Reimplemented in vlink::DatabaseReader, and vlink::McapReader.

◆ register_ready_callback()

virtual void vlink::BagReader::register_ready_callback ( ReadyCallback && ready_callback )

virtual

Registers a callback fired when the reader is ready to start playing.

Parameters

ready_callback Callback invoked once the file is open and parsed.

Reimplemented in vlink::DatabaseReader, and vlink::McapReader.

◆ register_status_callback()

virtual void vlink::BagReader::register_status_callback ( StatusCallback && status_callback )

virtual

Registers a callback fired whenever the playback status changes.

Parameters

status_callback Callback receiving the new Status value.

Reimplemented in vlink::DatabaseReader, and vlink::McapReader.

◆ reindex()

virtual std::future< bool > vlink::BagReader::reindex ( )

pure virtual

Rebuilds the index tables asynchronously.

Returns: std::future<bool> that resolves to true on success.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ resume()

virtual void vlink::BagReader::resume ( )

pure virtual

Resumes a paused playback from the current position.

Transitions from kPaused to kPlaying.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ stop()

virtual void vlink::BagReader::stop ( )

pure virtual

Stops playback and resets the reader to the beginning.

Transitions the reader to kStopped. The FinishCallback is fired with is_interrupted = true.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

◆ tag()

virtual void vlink::BagReader::tag ( const std::string & tag_name )

pure virtual

Updates the tag name stored in the bag's metadata.

Parameters

tag_name New tag name string.

Implemented in vlink::DatabaseReader, and vlink::McapReader.

Member Data Documentation

◆ kInfinite

int vlink::BagReader::kInfinite {-1}

staticconstexpr

Sentinel value for the Config::times field to indicate endless loop playback.

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

include/vlink/extension/bag_reader.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ FinishCallback

◆ OutputCallback

◆ ReadyCallback

◆ StatusCallback

Member Enumeration Documentation

◆ Status

Constructor & Destructor Documentation

◆ BagReader()

◆ ~BagReader()

Member Function Documentation

◆ bind_plugin_interface()

◆ check()

◆ convert_action()

◆ create()

◆ detect_schema()

◆ fix()

◆ get_info()

◆ get_real_timestamp()

◆ get_schema_type()

◆ get_ser_type()

◆ get_split_index()

◆ get_status()

◆ get_timestamp()

◆ is_jumping()

◆ is_split_mode()

◆ jump()

◆ pause()

◆ pause_to_next()

◆ play()

◆ process_output()

◆ process_url_metas()

◆ rebuild_url_meta_maps()

◆ register_finish_callback()

◆ register_output_callback()

◆ register_ready_callback()

◆ register_status_callback()

◆ reindex()

◆ resume()

◆ stop()

◆ tag()

Member Data Documentation

◆ kInfinite