EventLoop Class Reference

Per-thread event loop providing event dispatch, timers, and posted callables. More...

#include <eventloop.h>

Public Types
enum	ProcessEventsFlag : uint32_t { ExcludeTimers = 0x01 , ExcludePosted = 0x02 , WaitForMore = 0x04 }
	Flags controlling processEvents() behavior. More...

Public Member Functions
	EventLoop ()
	Constructs an EventLoop and registers it as current for this thread.
	~EventLoop ()
	Destroys the EventLoop.
	EventLoop (const EventLoop &)=delete
EventLoop &	operator= (const EventLoop &)=delete
int	exec ()
	Blocks and processes events until quit() is called.
void	processEvents (uint32_t flags=0, unsigned int timeoutMs=0)
	Processes pending events and returns.
void	quit (int returnCode=0)
	Signals the event loop to exit with the given return code.
void	postCallable (std::function< void()> func)
	Posts a callable to be executed on this EventLoop's thread.
void	postEvent (ObjectBase *receiver, Event *event)
	Posts an Event to this EventLoop for delivery to a receiver.
int	startTimer (ObjectBase *receiver, unsigned int intervalMs, bool singleShot=false)
	Starts a timer that delivers TimerEvent to an ObjectBase.
int	startTimer (unsigned int intervalMs, std::function< void()> func, bool singleShot=false)
	Starts a standalone callable timer.
void	stopTimer (int timerId)
	Stops and removes a timer.
bool	isRunning () const
	Returns whether the event loop is currently running.
int	exitCode () const
	Returns the exit code set by the most recent quit().

Static Public Member Functions
static EventLoop *	current ()
	Returns the EventLoop running on the current thread.

Detailed Description

Per-thread event loop providing event dispatch, timers, and posted callables.

EventLoop is not an ObjectBase — it is infrastructure that ObjectBase instances attach to. Each thread may have at most one active EventLoop, tracked by a thread_local pointer accessible via current().

Two execution models are supported:

• exec() — blocks, processes events until quit() is called.
• processEvents() — processes pending events and returns, suitable for WebAssembly or other environments where the host owns the run loop.

exec() is simply a loop calling processEvents(WaitForMore).

Example

EventLoop loop;
 
// Post work to this thread's event loop
loop.postCallable([]() {
    promekiInfo("Running on event loop thread");
});
 
// Start a repeating 100ms timer
int timerId = loop.startTimer(100, []() {
    promekiInfo("Timer fired");
});
 
// Run the event loop (blocks until quit)
int exitCode = loop.exec();

Note

Timer precision is millisecond-level, based on steady_clock polling.

Member Enumeration Documentation

ProcessEventsFlag

enum EventLoop::ProcessEventsFlag : uint32_t

Flags controlling processEvents() behavior.

Enumerator
ExcludeTimers	Skip timer processing.
ExcludePosted	Skip posted callables and events.
WaitForMore	Block until at least one event is available.

Constructor & Destructor Documentation

EventLoop()

EventLoop::EventLoop

(

)

Constructs an EventLoop and registers it as current for this thread.

Only one EventLoop may be active per thread. If one already exists, the new one replaces it (the previous pointer is not restored on destruction).

~EventLoop()

EventLoop::~EventLoop

(

)

Destroys the EventLoop.

Drains any remaining queued items, freeing owned Event pointers. Clears the thread-local pointer if it still points to this instance.

Member Function Documentation

current()

static EventLoop * EventLoop::current ( )

static

Returns the EventLoop running on the current thread.

Returns

The current thread's EventLoop, or nullptr if none.

exec()

int EventLoop::exec

(

)

Blocks and processes events until quit() is called.

Returns

The exit code passed to quit().

exitCode()

int EventLoop::exitCode ( ) const

inline

Returns the exit code set by the most recent quit().

Returns

The exit code, or 0 if quit() was never called.

isRunning()

bool EventLoop::isRunning ( ) const

inline

Returns whether the event loop is currently running.

Returns

true if exec() is active.

postCallable()

void EventLoop::postCallable

(

std::function< void()>

func

)

Posts a callable to be executed on this EventLoop's thread.

Thread-safe. The callable will be invoked during the next processEvents() call.

Parameters

func	The callable to execute.

postEvent()

void EventLoop::postEvent	(	ObjectBase *	receiver,
		Event *	event
	)

Posts an Event to this EventLoop for delivery to a receiver.

Takes ownership of event. Thread-safe. The event will be delivered during the next processEvents() call via the receiver's event() virtual method.

Parameters

receiver	The ObjectBase to deliver the event to.
event	The event to deliver. Ownership is transferred.

processEvents()

void EventLoop::processEvents	(	uint32_t	flags = 0,
		unsigned int	timeoutMs = 0
	)

Processes pending events and returns.

Parameters

flags	Combination of ProcessEventsFlag values.
timeoutMs	When WaitForMore is set, the maximum time to wait for events in milliseconds. Zero with WaitForMore waits indefinitely. Zero without WaitForMore drains pending events and returns immediately.

quit()

void EventLoop::quit

(

int

returnCode = 0

)

Signals the event loop to exit with the given return code.

Thread-safe. The loop will exit after the current processEvents() iteration completes.

Parameters

returnCode

The exit code returned by exec().

startTimer() [1/2]

int EventLoop::startTimer	(	ObjectBase *	receiver,
		unsigned int	intervalMs,
		bool	singleShot = false
	)

Starts a timer that delivers TimerEvent to an ObjectBase.

The receiver's timerEvent() virtual method will be called each time the timer fires. Must be called from the EventLoop's thread.

Parameters

receiver	The ObjectBase to receive TimerEvents.
intervalMs	The timer interval in milliseconds.
singleShot	If true, the timer fires once and is removed.

Returns

The timer ID, usable with stopTimer().

startTimer() [2/2]

int EventLoop::startTimer	(	unsigned int	intervalMs,
		std::function< void()>	func,
		bool	singleShot = false
	)

Starts a standalone callable timer.

No ObjectBase is needed — the callable runs directly on the EventLoop's thread each time the timer fires.

Parameters

intervalMs	The timer interval in milliseconds.
func	The callable to invoke when the timer fires.
singleShot	If true, the timer fires once and is removed.

Returns

The timer ID, usable with stopTimer().

stopTimer()

void EventLoop::stopTimer

(

int

timerId

)

Stops and removes a timer.

Parameters

timerId

The ID returned by startTimer().

---

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

• include/promeki/core/eventloop.h