Skip to content

Threads and timers

WUI does not promise arbitrary concurrent access to controls. Update an interface from its owning event thread. Internal locks around subscriptions do not make add_control(), drawing or control state generally thread-safe.

Platform timer callback
Windows Owning UI/message-loop thread
Linux Shared X11 event thread
macOS Main UI thread
WASM Browser main thread; background tabs can throttle it

The actual timer API is timer(callback), start(interval_ms) and stop(). Constructing a timer does not start it. Keep it alive while needed. For portable UI code, send a small notification to the window and update controls in its event handler, rather than modifying controls directly in a timer/worker callback.

#include <wui/system/timer.hpp>

wui::timer timer([weak = std::weak_ptr<wui::window>(window)] {
    if (auto target = weak.lock()) target->emit_event(100, 0);
});
// Handle internal_event_type::user_emitted in the window subscription.
timer.start(100); // milliseconds
// Before captured state or the receiving window is destroyed:
timer.stop();

emit_event(x,y) delivers an internal_event_type::user_emitted event. Transfer larger data using application-owned storage with appropriate synchronization; the two integer arguments are not object ownership. Join workers and stop timers before destroying the data they capture.

On Linux, timer callbacks, X11 events, device-change notifications and painting share the listener thread. Timer intervals use a steady clock; missed ticks are skipped rather than delivered in a catch-up burst. Callbacks must remain short: move decoding, I/O and other expensive work to a worker.

Linux timer::stop() prevents further invocations and waits for an in-flight callback when called from another thread. A callback can stop, restart or destroy its own timer. Stop timers before destroying objects they capture by raw pointer; the timer cannot extend those objects' lifetime automatically. Do not hold a lock needed by the callback while waiting in stop().

Linux worker code can use get_listener().post(callback) (include <wui/window/listener.h>) to schedule UI work. Capture the receiver through a weak_ptr, and lock it inside the queued callback. post() is asynchronous and does not make other direct access to control state safe. The lower-level listener::clear_timer() is also asynchronous; use wui::timer when synchronized cancellation is needed.

The WASM backend currently has no WUI pthread/Worker integration. On macOS all UI initialization, event processing and drawing must run on the main thread.

On Windows, construct timer on the thread that owns the UI message loop and keep that loop running while callbacks are needed. start() and stop() can be called from workers; native timer changes are queued back to the owner. stop() invalidates pending ticks immediately and waits for an in-flight callback from another thread. Self-stop, restart and self-destruction are supported. Do not hold a lock needed by the callback while waiting in stop(). A timer callback must remain short; perform blocking work on a separate worker.

The Windows backend uses message-only windows and WM_TIMER, including its normal scheduling granularity (typically at least 10 ms). Cancellation filters stale messages even after a restart. Scrollbar animation also runs in short UI ticks, without joining an animation worker from mouse-event handlers. Rebuild the library and applications together after updating the timer implementation.