MessageLoop subclass that forwards every task to an internal ThreadPool. More...

#include <multi_loop.h>

Inheritance diagram for vlink::MultiLoop:

Collaboration diagram for vlink::MultiLoop:

Public Member Functions
	MultiLoop (size_t thread_num=4U)
	Constructs a `MultiLoop` with the default `kNormalType` queue and `thread_num` workers. More...

	MultiLoop (size_t thread_num, Type type)
	Constructs a `MultiLoop` with a specific queue type. More...

	~MultiLoop () override
	Defaulted destructor. More...

bool	is_in_same_thread () const override
	Reports whether the calling thread belongs to this loop. More...

bool	wait_for_idle (int ms=Timer::kInfinite, bool check=true) override
	Waits until both the dispatcher queue and the worker pool reach idle. 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 size_t	get_max_task_count () const
	Returns the maximum queue depth. 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...

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
void	on_begin () override
	Hook invoked once on the dispatcher when the loop starts; constructs the worker pool. More...

void	on_end () override
	Hook invoked once on the dispatcher when the loop exits; shuts the worker pool down. More...

void	on_task_changed (Callback &&callback, uint32_t start_time) override
	Forwards a task to the internal pool, falling back to the inline base implementation when the pool rejects the post. More...

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_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::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...

Detailed Description

MessageLoop subclass that forwards every task to an internal ThreadPool.

Inherits every posting API from MessageLoop. The dispatcher pulls tasks from the queue in FIFO order; the worker pool runs them concurrently so execution order is not guaranteed even though enqueue order is.

Constructor & Destructor Documentation

◆ MultiLoop() [1/2]

vlink::MultiLoop::MultiLoop ( size_t thread_num = 4U )

explicit

Constructs a MultiLoop with the default kNormalType queue and thread_num workers.

Parameters

thread_num Worker count. Default: 4. A zero-worker pool rejects forwarded posts, so tasks fall back to inline execution on the dispatcher.

◆ MultiLoop() [2/2]

vlink::MultiLoop::MultiLoop	(	size_t	thread_num,
		Type	type
	)

explicit

Constructs a MultiLoop with a specific queue type.

Parameters

thread_num	Worker count.
type	Queue implementation type from `MessageLoop::Type`.

◆ ~MultiLoop()

vlink::MultiLoop::~MultiLoop ( )

override

Defaulted destructor.

Warning: Call quit and wait_for_quit before destruction; the base MessageLoop destructor runs after MultiLoop's members are already torn down and cannot guarantee the worker pool is reset.

Member Function Documentation

◆ is_in_same_thread()

bool vlink::MultiLoop::is_in_same_thread ( ) const

overridevirtual

Reports whether the calling thread belongs to this loop.

Returns: true on the dispatcher or any worker thread of the internal pool.

Reimplemented from vlink::MessageLoop.

◆ on_begin()

void vlink::MultiLoop::on_begin ( )

overrideprotectedvirtual

Hook invoked once on the dispatcher when the loop starts; constructs the worker pool.

Reimplemented from vlink::MessageLoop.

◆ on_end()

void vlink::MultiLoop::on_end ( )

overrideprotectedvirtual

Hook invoked once on the dispatcher when the loop exits; shuts the worker pool down.

Reimplemented from vlink::MessageLoop.

◆ on_task_changed()

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

overrideprotectedvirtual

Forwards a task to the internal pool, falling back to the inline base implementation when the pool rejects the post.

Parameters

callback	Task to dispatch.
start_time	Millisecond `steady_clock` timestamp captured at enqueue time.

Reimplemented from vlink::MessageLoop.

◆ wait_for_idle()

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

overridevirtual

Waits until both the dispatcher queue and the worker pool reach idle.

Parameters

ms	Maximum wait in milliseconds; `Timer::kInfinite` means no limit.
check	When `true`, rejects calls from threads owned by this loop.

Returns: true when both queues drained before the timeout.

Reimplemented from vlink::MessageLoop.

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

include/vlink/base/multi_loop.h

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MultiLoop() [1/2]

◆ MultiLoop() [2/2]

◆ ~MultiLoop()

Member Function Documentation

◆ is_in_same_thread()

◆ on_begin()

◆ on_end()

◆ on_task_changed()

◆ wait_for_idle()