message_loop.h File Reference

Single-threaded event loop with three queue types, timer management and task scheduling. More...

#include <functional>
#include <future>
#include <limits>
#include <memory>
#include <string>
#include <type_traits>
#include <utility>
#include "./schedule.h"
#include "./timer.h"

Include dependency graph for message_loop.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	vlink::MessageLoop
	Single-threaded serial task dispatcher with integrated timer support. More...

Namespaces
namespace	vlink

Detailed Description

Single-threaded event loop with three queue types, timer management and task scheduling.

MessageLoop is the primary task dispatcher in VLink. It owns a task queue and an associated timer registry. Tasks posted via post_task() are executed serially on the loop's thread. Timers registered with Timer::attach() fire their callbacks as regular queue tasks.

Queue types:

Type	Queue implementation	Max tasks	Notes
kNormalType	Mutex-protected std::queue	10000	Default; no priority support
kLockfreeType	MpmcQueue (lock-free MPMC)	10000	Fastest single-producer path
kPriorityType	Priority queue	10000	Supports task priority levels

Dispatch strategies:

Strategy	Behaviour
kOptimizationStrategy	Yields CPU when queue is empty; balances latency vs CPU usage
kPopStrategy	Busy-waits by repeatedly polling the queue (lowest latency)
kBlockStrategy	Blocks on a condition variable when the queue is empty (lowest CPU)

Run modes:

• run() – blocks the calling thread until quit() is called.
• async_run() – launches a new background thread and returns immediately.
• spin() – calls spin_once() in a loop; suitable for use in an existing event loop.
• spin_once() – processes one batch of pending tasks (optionally blocking).

Task execution with scheduling: exec_task() wraps a callback in a Schedule::Config (delay, priority, timeouts) and posts it. It returns a Schedule::Status or Schedule::RetStatus that can be chained with on_then / on_else / on_catch / on_schedule_timeout callbacks.

Note

• Maximum task queue depth is 10000 (kMaxTaskSize); posts beyond this fail silently.
• Maximum active timer count is 100 (kMaxTimerSize).
• invoke_task() dispatches a callable and returns a std::future for the result. Blocking on the future from the same thread as the loop will deadlock.

Example

vlink::MessageLoop loop;
loop.async_run();
 
loop.post_task([] { do_work(); });
 
// Blocking invoke from another thread:
auto fut = loop.invoke_task([]() -> int { return compute(); });
int result = fut.get();  // waits for the loop to process the task
 
loop.quit();
loop.wait_for_quit();