Concrete MCAP-format BagReader implementation with index-driven seek. More...

#include <vcap_reader.h>

Inheritance diagram for vlink::VCAPReader:

Collaboration diagram for vlink::VCAPReader:

Public Member Functions
	VCAPReader (const std::string &path, bool read_only=true, bool try_to_fix=false)
	Opens an MCAP file for playback. More...

	~VCAPReader () override
	Stops playback and releases the MCAP file handle. More...

void	bind_plugin_interface (const std::shared_ptr< BagPluginInterface > &plugin_interface) override
	Attaches a `BagPluginInterface` for custom URL or type rewriting. More...

void	register_status_callback (StatusCallback &&status_callback) override
	Registers a callback invoked on every playback state transition. More...

void	register_ready_callback (ReadyCallback &&ready_callback) override
	Registers a callback fired once the file is open, parsed, and ready to play. More...

void	register_finish_callback (FinishCallback &&finish_callback) override
	Registers a callback fired when playback ends naturally or is interrupted. More...

void	register_output_callback (OutputCallback &&output_callback) override
	Registers the message-delivery callback consumed during playback. More...

void	play (const Config &config) override
	Starts playback with the given configuration. More...

void	stop () override
	Stops playback and rewinds to the recording start. More...

void	pause () override
	Pauses playback at the current position. More...

void	resume () override
	Resumes paused playback from the current position. More...

void	pause_to_next () override
	Emits one more message and then pauses again. More...

void	jump (int64_t begin_time, double rate, int times, bool force_to_play=false) override
	Seeks to `begin_time` and resumes playback at the new position. More...

std::future< bool >	check () override
	Verifies the integrity of the MCAP file asynchronously. More...

std::future< bool >	reindex () override
	Unsupported MCAP reindex operation. More...

std::future< bool >	fix (bool rebuild=false) override
	Unsupported MCAP repair operation. More...

void	tag (const std::string &tag_name) override
	Updates the .vcapx manifest tag. Single .vcap files are left untouched. More...

int64_t	get_timestamp () const override
	Returns the current playback cursor in milliseconds. More...

int64_t	get_real_timestamp () const override
	Returns the timestamp of the last delivered message. More...

Status	get_status () const override
	Returns the playback status. More...

const Info &	get_info () const override
	Returns the bag metadata populated when the file was opened. More...

std::vector< SchemaData >	detect_schema () override
	Enumerates every schema embedded in the MCAP file. More...

bool	is_split_mode () const override
	Reports whether the bag is split across multiple .vcap files. More...

int	get_split_index () const override
	Returns the index of the split part currently under playback. More...

bool	is_jumping () const override
	Reports whether a `jump()` seek is currently being processed. More...

Public Member Functions inherited from vlink::BagReader
	BagReader (const std::string &path, bool read_only=true, bool try_to_fix=false)
	Constructs the base reader and stores construction-time options. More...

virtual	~BagReader ()
	Stops the loop, closes the file and releases backend resources. More...

virtual void	clear_plugin_interface ()
	Detaches the currently bound plugin, if any. More...

bool	open_cursor (const Config &config)
	Opens (or rewinds) a synchronous sequential read cursor over the bag. More...

bool	open_cursor ()
	Opens (or rewinds) a full, unfiltered sequential read cursor over the bag. More...

bool	read_next (Frame &out)
	Reads the next frame in recorded order into `out`. More...

BagReader &	operator>> (Frame &out)
	Stream-style alias for `read_next()`, enabling `while` (reader >> frame). More...

bool	eof () const noexcept
	Returns whether the cursor has reached the end of the bag. More...

bool	fail () const noexcept
	Returns whether the last cursor operation failed (open or backend read error). More...

	operator bool () const noexcept
	Reports whether the cursor is still in a readable state (not at end, not failed). More...

virtual std::string	get_ser_type (const std::string &url) const
	Resolves the serialisation type associated with `url`. More...

virtual SchemaType	get_schema_type (const std::string &url) const
	Resolves the schema family associated with `url`. More...

Public Member Functions inherited from vlink::MessageLoop
	MessageLoop ()
	Constructs a loop with the default `kNormalType` queue. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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`. More...

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`. More...

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

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

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

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

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

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

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. More...

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

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

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

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

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. More...

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. More...

Protected Member Functions
size_t	get_max_task_count () const override
	Returns the maximum queue depth. More...

void	on_begin () override
	Hook invoked once on the loop thread before the first task runs. More...

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

bool	do_open_cursor (const Config &config) override

bool	do_read_next (Frame &out, bool &is_error) override

Protected Member Functions inherited from vlink::BagReader
void	process_output (Frame &frame)

void	fill_frame_meta (Frame &frame) const

void	flush_plugin ()

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

void	rebuild_url_meta_lookup (const std::vector< Info::UrlMeta > &url_metas)

std::unordered_map< std::string, std::string > &	url_ser_map ()

std::unordered_map< std::string, SchemaType > &	url_schema_type_map ()

bool	convert_playback_url (const std::string &input_url, std::string &output_url) const

bool	match_playback_url_filter (std::string_view input_url, const std::unordered_set< std::string > &filter_urls) const

void	detach_plugin ()

Protected Member Functions inherited from vlink::MessageLoop
virtual void	on_idle ()
	Hook invoked on the loop thread each time the queue becomes empty. More...

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

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

Additional Inherited Members
Public Types inherited from vlink::BagReader
enum	Status : uint8_t { kStopped = 0 , kPaused = 1 , kPlaying = 2 }
	Coarse playback state observable through `get_status()`. More...

using	OutputCallback = FrameCallback
	Callback signature receiving one replayed `Frame`. More...

using	StatusCallback = MoveFunction< void(Status status)>
	Callback fired on every transition of `Status`. More...

using	ReadyCallback = MoveFunction< void()>
	Callback fired once after the bag has been opened and indexed. More...

using	FinishCallback = MoveFunction< void(bool is_interrupted)>
	Callback fired when the current play session ends. More...

Public Types inherited from vlink::MessageLoop
enum	Type : uint8_t { kNormalType = 0 , kLockfreeType = 1 , kPriorityType = 2 }
	Internal queue implementation type. More...

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

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. More...

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

Static Public Member Functions inherited from vlink::BagReader
static std::shared_ptr< BagReader >	create (const std::string &path, bool read_only=true, bool try_to_fix=false)
	Builds the concrete reader matching the extension of `path`. More...

Static Public Attributes inherited from vlink::BagReader
static constexpr int	kInfinite {-1}
	Sentinel for `Config::times` that requests endless loop playback. More...

Static Protected Member Functions inherited from vlink::BagReader
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)

static ActionType	convert_action (std::string_view str)

Detailed Description

Concrete MCAP-format BagReader implementation with index-driven seek.

Prefer BagReader::create() for format-agnostic instantiation; instantiate this class directly only when an MCAP-specific feature is required.

Constructor & Destructor Documentation

◆ VCAPReader()

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

explicit

Opens an MCAP file for playback.

Parameters

path	Filesystem path of the .vcap or .vcapx file.
read_only	`true` blocks any in-place modification (default).
try_to_fix	`true` enables a fallback summary scan when the indexed summary is unreadable.

◆ ~VCAPReader()

vlink::VCAPReader::~VCAPReader ( )

override

Stops playback and releases the MCAP file handle.

Member Function Documentation

◆ bind_plugin_interface()

void vlink::VCAPReader::bind_plugin_interface ( const std::shared_ptr< BagPluginInterface > & plugin_interface )

overridevirtual

Attaches a BagPluginInterface for custom URL or type rewriting.

Parameters

plugin_interface Plugin instance; pass nullptr to detach.

Reimplemented from vlink::BagReader.

◆ check()

std::future<bool> vlink::VCAPReader::check ( )

overridevirtual

Verifies the integrity of the MCAP file asynchronously.

Returns: Future resolving to true when the file passes the integrity check.

Implements vlink::BagReader.

◆ detect_schema()

std::vector<SchemaData> vlink::VCAPReader::detect_schema ( )

overridevirtual

Enumerates every schema embedded in the MCAP file.

Returns: Vector of SchemaData descriptors.

Implements vlink::BagReader.

◆ do_open_cursor()

bool vlink::VCAPReader::do_open_cursor ( const Config & config )

overrideprotectedvirtual

Reimplemented from vlink::BagReader.

◆ do_read_next()

bool vlink::VCAPReader::do_read_next	(	Frame &	out,
		bool &	is_error
	)

overrideprotectedvirtual

Reimplemented from vlink::BagReader.

◆ fix()

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

overridevirtual

Unsupported MCAP repair operation.

Parameters

rebuild Ignored.

Returns: Future that always resolves to false.

Implements vlink::BagReader.

◆ get_info()

const Info& vlink::VCAPReader::get_info ( ) const

overridevirtual

Returns the bag metadata populated when the file was opened.

Returns: Const reference to the Info struct.

Implements vlink::BagReader.

◆ get_max_task_count()

size_t vlink::VCAPReader::get_max_task_count ( ) const

overrideprotectedvirtual

Returns the maximum queue depth.

Returns: kMaxTaskSize (10000) by default.

Reimplemented from vlink::MessageLoop.

◆ get_real_timestamp()

int64_t vlink::VCAPReader::get_real_timestamp ( ) const

overridevirtual

Returns the timestamp of the last delivered message.

Returns: Last data timestamp in milliseconds, or 0 when stopped.

Implements vlink::BagReader.

◆ get_split_index()

int vlink::VCAPReader::get_split_index ( ) const

overridevirtual

Returns the index of the split part currently under playback.

Returns: Zero-based split index.

Implements vlink::BagReader.

◆ get_status()

Status vlink::VCAPReader::get_status ( ) const

overridevirtual

Returns the playback status.

Returns: One of kStopped, kPaused, or kPlaying.

Implements vlink::BagReader.

◆ get_timestamp()

int64_t vlink::VCAPReader::get_timestamp ( ) const

overridevirtual

Returns the current playback cursor in milliseconds.

Returns: Position relative to the recording start.

Implements vlink::BagReader.

◆ is_jumping()

bool vlink::VCAPReader::is_jumping ( ) const

overridevirtual

Reports whether a jump() seek is currently being processed.

Returns: true while a seek is in flight.

Implements vlink::BagReader.

◆ is_split_mode()

bool vlink::VCAPReader::is_split_mode ( ) const

overridevirtual

Reports whether the bag is split across multiple .vcap files.

Returns: true when reading a .vcapx manifest with multiple parts.

Implements vlink::BagReader.

◆ jump()

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

overridevirtual

Seeks to begin_time and resumes playback at the new position.

Parameters

begin_time	Target timestamp in milliseconds, relative to recording start.
rate	Playback rate multiplier applied after the seek.
times	Number of loop iterations after the jump.
force_to_play	`true` forces play state even if currently paused.

Implements vlink::BagReader.

◆ on_begin()

void vlink::VCAPReader::on_begin ( )

overrideprotectedvirtual

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

Subclasses override to perform per-thread initialisation.

Reimplemented from vlink::MessageLoop.

◆ on_end()

void vlink::VCAPReader::on_end ( )

overrideprotectedvirtual

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

Subclasses override to perform per-thread cleanup.

Reimplemented from vlink::MessageLoop.

◆ pause()

void vlink::VCAPReader::pause ( )

overridevirtual

Pauses playback at the current position.

std::future<bool> vlink::VCAPReader::reindex ( )

overridevirtual

Unsupported MCAP reindex operation.

Returns: Future that always resolves to false.

Implements vlink::BagReader.

◆ resume()

void vlink::VCAPReader::resume ( )

overridevirtual

Resumes paused playback from the current position.

Implements vlink::BagReader.

◆ stop()

void vlink::VCAPReader::stop ( )

overridevirtual

Stops playback and rewinds to the recording start.

Implements vlink::BagReader.

◆ tag()

void vlink::VCAPReader::tag ( const std::string & tag_name )

overridevirtual

Updates the .vcapx manifest tag. Single .vcap files are left untouched.

Parameters

tag_name New tag string.

Implements vlink::BagReader.

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

include/vlink/extension/vcap_reader.h

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ VCAPReader()

◆ ~VCAPReader()

Member Function Documentation

◆ bind_plugin_interface()

◆ check()

◆ detect_schema()

◆ do_open_cursor()

◆ do_read_next()

◆ fix()

◆ get_info()

◆ get_max_task_count()

◆ get_real_timestamp()

◆ get_split_index()

◆ get_status()

◆ get_timestamp()

◆ is_jumping()

◆ is_split_mode()

◆ jump()

◆ on_begin()

◆ on_end()

◆ pause()

◆ pause_to_next()

◆ play()

◆ register_finish_callback()

◆ register_output_callback()

◆ register_ready_callback()

◆ register_status_callback()

◆ reindex()

◆ resume()

◆ stop()

◆ tag()