vlink::MessageLoop类 参考

Single-threaded serial task dispatcher with integrated timer support. 更多...

#include <message_loop.h>

类 vlink::MessageLoop 继承关系图:

vlink::MessageLoop 的协作图:

Public 类型
enum	Type : uint8_t { kNormalType = 0 , kLockfreeType = 1 , kPriorityType = 2 }
	Queue implementation type. 更多...
enum	Strategy : uint8_t { kOptimizationStrategy = 0 , kPopStrategy = 1 , kBlockStrategy = 2 }
	Idle strategy controlling CPU and latency trade-offs. 更多...
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. 更多...
using	Callback = std::function<void()>
	Callback type for tasks and event handlers.

Public 成员函数
	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.

Protected 成员函数
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().

详细描述

Single-threaded serial task dispatcher with integrated timer support.

All tasks and timer callbacks run on a single thread. Thread-safe posting of tasks is allowed from any thread via post_task().

成员类型定义说明

Callback

using vlink::MessageLoop::Callback = std::function<void()>

Callback type for tasks and event handlers.

成员枚举类型说明

Priority

enum vlink::MessageLoop::Priority : uint16_t

Pre-defined task priority levels for kPriorityType loops.

Higher numeric values are dispatched first. Custom priority values may be used between kLowestPriority and kHighestPriority.

枚举值
kNoPriority	No priority (FIFO order)
kLowestPriority	Lowest real priority
kTimerPriority	Used internally for timer callbacks
kNormalPriority	Default task priority
kHighestPriority	Highest available priority

Strategy

enum vlink::MessageLoop::Strategy : uint8_t

Idle strategy controlling CPU and latency trade-offs.

See class documentation for a comparison table.

枚举值
kOptimizationStrategy	Balance latency and CPU via yield
kPopStrategy	Busy-poll (lowest latency, highest CPU)
kBlockStrategy	Block on condition variable (lowest CPU)

Type

enum vlink::MessageLoop::Type : uint8_t

Queue implementation type.

Selects the internal task queue algorithm. See class documentation for a comparison table.

枚举值
kNormalType	Mutex-protected FIFO queue (default)
kLockfreeType	Lock-free MPMC queue
kPriorityType	Priority-ordered queue

构造及析构函数说明

MessageLoop() [1/2]

vlink::MessageLoop::MessageLoop

(

)

Constructs a MessageLoop with kNormalType queue.

这是这个函数的调用关系图:

MessageLoop() [2/2]

vlink::MessageLoop::MessageLoop ( Type type )

explicit

Constructs a MessageLoop with the specified queue type.

参数

type	Queue implementation to use.

~MessageLoop()

virtual vlink::MessageLoop::~MessageLoop ( )

virtual

Destructor. Calls quit(true) and waits for the background thread (if any).

成员函数说明

async_run()

bool vlink::MessageLoop::async_run

(

)

Starts the message loop on a new background thread (non-blocking).

Returns immediately. The background thread runs until quit() is called.

返回

true if the thread was started; false if already running.

exec_task() [1/2]

template<typename CallbackT, typename>

Schedule::RetStatus vlink::MessageLoop::exec_task	(	const Schedule::Config &	config,
		CallbackT &&	callback )

Posts a scheduled task and returns a Schedule::RetStatus for chaining callbacks.

This overload is for callbacks returning bool. Chain on_then (fires if true) and on_else (fires if false) on the returned status.

模板参数

CallbackT

Callable type returning bool.

参数

config	Scheduling configuration.
callback	Callable to execute.

返回

Schedule::RetStatus for chaining.

函数调用图:

exec_task() [2/2]

template<typename CallbackT, typename>

Schedule::Status vlink::MessageLoop::exec_task	(	const Schedule::Config &	config,
		CallbackT &&	callback )

Posts a scheduled task and returns a Schedule::Status for chaining callbacks.

Details

This overload is for callbacks returning void. The Schedule::Config can specify a delay, priority, schedule timeout and execution timeout. Chain on_schedule_timeout, on_execution_timeout or on_catch on the returned status.

模板参数

CallbackT

Callable type returning void.

参数

config	Scheduling configuration.
callback	Callable to execute.

返回

Schedule::Status for chaining.

函数调用图:

这是这个函数的调用关系图:

get_max_elapsed_time()

virtual uint32_t vlink::MessageLoop::get_max_elapsed_time ( ) const

nodiscardvirtual

Returns the maximum allowed task execution time in milliseconds.

When a task exceeds this duration, on_task_timeout() is called. Returns 0 to disable timeout checking.

返回

Maximum execution time in ms.

被 vlink::DiscoveryReporter, vlink::DiscoveryViewer, vlink::ProxyAPI , 以及 vlink::ProxyServer 重载.

get_max_task_count()

virtual size_t vlink::MessageLoop::get_max_task_count ( ) const

nodiscardvirtual

Returns the maximum queue depth.

返回

kMaxTaskSize (10000) by default.

被 vlink::DatabaseReader, vlink::DatabaseWriter, vlink::DiscoveryReporter, vlink::DiscoveryViewer, vlink::McapReader, vlink::McapWriter, vlink::ProxyAPI , 以及 vlink::ProxyServer 重载.

get_max_timer_count()

virtual size_t vlink::MessageLoop::get_max_timer_count ( ) const

nodiscardvirtual

Returns the maximum number of timers that can be attached to this loop.

返回

kMaxTimerSize (100) by default.

get_name()

const std::string & vlink::MessageLoop::get_name ( ) const

nodiscard

Returns the name set via set_name().

返回

Reference to the name string.

get_strategy()

Strategy vlink::MessageLoop::get_strategy ( ) const

nodiscard

Returns the current idle dispatch strategy.

返回

Current strategy.

get_task_count()

size_t vlink::MessageLoop::get_task_count ( ) const

nodiscard

Returns the number of tasks currently in the queue.

返回

Pending task count.

get_type()

Type vlink::MessageLoop::get_type ( ) const

nodiscard

Returns the queue type this loop was constructed with.

返回

Queue type.

这是这个函数的调用关系图:

invoke_task()

template<class FunctionT, class... ArgsT, typename ResultT>

std::future< ResultT > vlink::MessageLoop::invoke_task ( FunctionT && function, ArgsT &&... args )

inlinenodiscard

Dispatches a callable to the loop thread and returns a std::future for the result.

Thread-safe. The future becomes ready after the callable is executed on the loop thread.

警告

Do not call .get() on the future from the same thread as the loop; doing so will deadlock.

模板参数

FunctionT	Callable type.
ArgsT	Argument types.
ResultT	Return type (deduced).

参数

function	Callable to dispatch.
args	Arguments forwarded to the callable.

返回

std::future<ResultT> that becomes ready when the task completes.

函数调用图:

这是这个函数的调用关系图:

invoke_task_with_priority()

template<class FunctionT, class... ArgsT, typename ResultT>

std::future< ResultT > vlink::MessageLoop::invoke_task_with_priority ( FunctionT && function, uint16_t priority, ArgsT &&... args )

inlinenodiscard

Dispatches a callable with an explicit priority and returns a std::future.

Same as invoke_task() but the task is enqueued at priority level. Requires a kPriorityType loop for priority to take effect.

模板参数

FunctionT	Callable type.
ArgsT	Argument types.
ResultT	Return type (deduced).

参数

function	Callable to dispatch.
priority	Dispatch priority.
args	Arguments forwarded to the callable.

返回

std::future<ResultT>.

函数调用图:

这是这个函数的调用关系图:

is_busy()

bool vlink::MessageLoop::is_busy ( ) const

nodiscard

Returns true if the loop is currently executing a task.

返回

true if a task callback is in progress on the loop thread.

is_in_same_thread()

virtual bool vlink::MessageLoop::is_in_same_thread ( ) const

nodiscardvirtual

Returns true if the calling thread is the same as the loop thread.

Used internally to detect if a task is calling back into the loop synchronously. For MultiLoop, returns true if the caller is any of the worker threads.

返回

true if called from the loop's own thread.

被 vlink::MultiLoop 重载.

函数调用图:

is_ready_to_quit()

bool vlink::MessageLoop::is_ready_to_quit ( ) const

nodiscard

Returns true if quit() has been called and the loop is winding down.

返回

true if the loop is in the process of quitting.

is_running()

bool vlink::MessageLoop::is_running ( ) const

nodiscard

Returns true if the loop is currently running (started and not quit).

返回

true if the loop is active.

on_begin()

virtual void vlink::MessageLoop::on_begin ( )

protectedvirtual

Called from the loop thread just before the first task is processed.

Override in subclasses to perform per-thread initialisation.

被 vlink::DatabaseReader, vlink::DatabaseWriter, vlink::DiscoveryReporter, vlink::DiscoveryViewer, vlink::McapReader, vlink::McapWriter, vlink::MultiLoop, vlink::ProxyAPI , 以及 vlink::ProxyServer 重载.

on_end()

virtual void vlink::MessageLoop::on_end ( )

protectedvirtual

Called from the loop thread just after the last task has been processed.

Override in subclasses to perform per-thread cleanup.

被 vlink::DatabaseReader, vlink::DatabaseWriter, vlink::DiscoveryReporter, vlink::DiscoveryViewer, vlink::McapReader, vlink::McapWriter, vlink::MultiLoop, vlink::ProxyAPI , 以及 vlink::ProxyServer 重载.

on_idle()

virtual void vlink::MessageLoop::on_idle ( )

protectedvirtual

Called from the loop thread each time the queue becomes empty.

Override in subclasses to perform idle work (e.g., statistics updates).

on_task_changed()

virtual void vlink::MessageLoop::on_task_changed ( Callback && callback, uint32_t start_time )

protectedvirtual

Called before each task is executed.

Provides the task callback and the monotonic start timestamp (in milliseconds). Override to implement per-task tracing or accounting.

参数

callback	The task about to be executed.
start_time	Millisecond timestamp at which the task was dequeued.

被 vlink::MultiLoop 重载.

on_task_timeout()

virtual void vlink::MessageLoop::on_task_timeout ( Callback && callback, uint32_t elapsed_time )

protectedvirtual

Called when a task's execution time exceeds get_max_elapsed_time().

Override to log or handle slow tasks.

参数

callback	The task that timed out.
elapsed_time	Actual execution time in milliseconds.

函数调用图:

post_task()

bool vlink::MessageLoop::post_task

(

Callback &&

callback

)

Posts a task to the queue for execution on the loop thread.

Thread-safe. Returns false if the loop is shutting down or the queue is full (kMaxTaskSize).

参数

callback

Task to execute.

返回

true if the task was successfully enqueued.

这是这个函数的调用关系图:

post_task_with_priority()

bool vlink::MessageLoop::post_task_with_priority	(	Callback &&	callback,
		uint16_t	priority )

Posts a task with an explicit priority (requires kPriorityType loop).

Tasks with higher priority values are dispatched before lower-priority tasks. For kNormalType and kLockfreeType loops, priority is ignored and the task is enqueued in FIFO order.

参数

callback	Task to execute.
priority	Dispatch priority.

返回

true if enqueued successfully.

函数调用图:

这是这个函数的调用关系图:

quit()

bool vlink::MessageLoop::quit

(

bool

force = false

)

Requests the loop to exit cleanly.

Signals the loop to stop after finishing the current task. If force is true, remaining queued tasks are discarded.

参数

force

If true, discard pending tasks. Default: false.

返回

true on success.

register_begin_handler()

void vlink::MessageLoop::register_begin_handler

(

Callback &&

callback

)

Registers a callback invoked once when the loop thread starts.

参数

callback

Called from the loop thread before the first task is processed.

register_end_handler()

void vlink::MessageLoop::register_end_handler

(

Callback &&

callback

)

Registers a callback invoked once when the loop thread exits.

参数

callback

Called from the loop thread after the last task has been processed.

register_idle_handler()

void vlink::MessageLoop::register_idle_handler

(

Callback &&

callback

)

Registers a callback invoked each time the task queue becomes empty.

参数

callback

Called from the loop thread on each idle cycle.

reset_lockfree_capacity()

void vlink::MessageLoop::reset_lockfree_capacity

(

)

Resets the lock-free queue to its initial capacity.

Only applicable to kLockfreeType loops. Useful after a large burst of tasks to reclaim internal capacity bookkeeping.

run()

bool vlink::MessageLoop::run

(

)

Runs the message loop on the calling thread (blocking).

Processes tasks and fires timers until quit() is called.

返回

true if the loop ran and exited normally; false if already running.

set_name()

void vlink::MessageLoop::set_name

(

const std::string &

name

)

Sets a human-readable name for this loop (visible in profiling tools).

参数

name	Name string.

set_strategy()

void vlink::MessageLoop::set_strategy

(

Strategy

strategy

)

Changes the idle dispatch strategy.

参数

strategy

New strategy. Takes effect on the next idle cycle.

spin()

bool vlink::MessageLoop::spin

(

)

Runs the loop continuously in a spin mode (blocking; no background thread).

Calls spin_once() repeatedly until quit() is called.

返回

true on normal exit.

spin_once()

bool vlink::MessageLoop::spin_once

(

bool

block = true

)

Processes one batch of pending tasks and timers.

Intended for integration into an existing event loop.

参数

block

If true and the queue is empty, blocks until a task arrives. If false, returns immediately if the queue is empty. Default: true.

返回

true if at least one task was processed; false if the loop should quit.

wait_for_idle()

bool vlink::MessageLoop::wait_for_idle	(	int	ms = Timer::kInfinite,
		bool	check = true )

Waits until the task queue is drained.

参数

ms	Maximum wait time in milliseconds. Timer::kInfinite for unlimited. Default: kInfinite.
check	If true, also verify the loop is in the idle state. Default: true.

返回

true if the queue drained within the timeout.

wait_for_quit()

bool vlink::MessageLoop::wait_for_quit	(	int	ms = Timer::kInfinite,
		bool	check = true )

Waits until the loop has fully exited (after quit() was called).

参数

ms	Maximum wait time in milliseconds. Timer::kInfinite for unlimited. Default: kInfinite.
check	If true, also verify the loop thread has joined. Default: true.

返回

true if the loop exited within the timeout.

wakeup()

bool vlink::MessageLoop::wakeup

(

)

Wakes the loop thread if it is sleeping (e.g., in kBlockStrategy).

返回

true if the wakeup signal was sent.

---

该类的文档由以下文件生成:

• include/vlink/base/message_loop.h