dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / src / webview / event_loop.lucb
#==============================================================================================
#
# event_loop - the Core event loop over an embedder's run loop
#
# DESCRIPTION:
# The adapter between the engine's Core event loop seam (web's
# external/lib_core/event_loop.lucb) and an application's own run loop, as Ladybird's
# UI/AppKit/Application/EventLoopImplementationMacOS.mm (and UI/Qt's
# EventLoopImplementationQt) puts LibCore's events on the platform's loop: there a
# Core::Timer becomes a CFRunLoopTimer and a deferred invocation signals a run loop
# source, so the platform loop sleeps until the engine has work and then runs it.
#
# The platform loop here (luce-ui's Application over luce-window) has no timer or source
# of its own to hand out, so the adapter keeps LibCore's ThreadData (the timers and the
# queue of deferred invocations) and tells the embedder two things:
#
# - a wake hook (webview_set_wake_hook), called whenever new work makes the earliest
# due moment earlier: a deferred invocation (due now), a timer registered (due at its
# first fire time) or Core::EventLoop::wake. The embedder makes its loop stop
# waiting (luce-window's window.wake()), as post_application_event does on macOS;
# - when the engine is next due (webview_event_loop_next_due), which the embedder
# folds into how long its loop may block, as the CFRunLoopTimers are.
#
# Each turn of its loop the embedder calls webview_event_loop_process, which runs what
# is due without waiting (the work of the run loop source and the timers' handlers),
# never longer than a slice, so input and painting keep going while a page is busy.
# Core::EventLoop::spin_until (pump in wait_for_events mode) still blocks until a timer
# is due, as LibCore's nested loops do.
#
# Socket notifiers (Core::Notifier, the in-process client's sockets): the loop keeps them in
# a CoreEventLoopNotifiers (web's external/lib_core/event_loop_notifiers.lucb), as
# web_test's WorkerEventLoop does. Each turn first looks at their descriptors without
# waiting and fires the ready ones after the deferred invocations and before the timers,
# LibCore's order (ThreadEventQueue::process after wait_for_events). Someone must notice
# when a descriptor turns ready while the embedder's loop sleeps, one of two ways:
#
# - by default, while any notifier is registered the loop is next due within a poll
# interval, so the embedder's loop comes back to look;
# - an embedder whose loop can watch descriptors itself (luce-ui's Application.watch)
# takes them over instead (webview_event_loop_hand_over_sockets), as the macOS loop
# makes each notifier a CFSocket source in register_notifier: the loop queues each
# descriptor whose notifiers changed (webview_event_loop_take_socket_change, with the
# wake hook called when the queue was empty), the embedder watches it for what
# webview_event_loop_socket_interest answers, and the poll interval no longer applies.
#
# Core::EventLoop::spin_until (pump in wait_for_events mode) waits on the descriptors
# until the next timer is due, as the worker does.
#
# Copyright (c) 2018-2026, the Ladybird developers.
# Copyright (c) 2023-2025, Tim Flynn <trflynn89@ladybird.org>
# Copyright (c) 2026 the luce-browser authors.
# SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================
# mark: The loop ================================================================================
## The longest webview_event_loop_process runs before it hands the thread back, in nanoseconds
## (a frame at 120 Hz).
pub let webview_event_loop_slice_nanoseconds: u64 = 8000000
## How soon the loop is due again while sockets are watched, in nanoseconds.
pub let webview_event_loop_poll_nanoseconds: u64 = 4000000
## A registered timer (LibCore's EventLoopTimer): fires `timer` at `fire_time` (time.now()
## nanoseconds), then every `interval_ms` while it stays registered.
struct WebViewLoopTimer:
var timer: web.CoreTimer*
var id: isize
var interval_ms: i32
var should_reload: bool
var fire_time: u64
## The embedder's wake-up: makes its run loop stop waiting. It may be called from the loop's
## own thread while it runs; it must not reenter the engine.
pub type WebViewWakeHook = func() -> unit
## The process's event loop (web.CoreEventLoopImplementation). It lives in the C heap inside a
## conservative root region (roots.lucb): its timer list and deferred queue are managed
## memory that only it refers to.
pub struct WebViewEventLoop: web.CoreEventLoopImplementation:
var timers: ak.Vector[WebViewLoopTimer]
var next_timer_id: isize
var deferred: ak.Vector[ak.Function0[unit]]
var notifiers: web.CoreEventLoopNotifiers
## Whether the embedder's loop watches the notifiers' descriptors itself, and the descriptors
## whose notifiers changed since it last took them (webview_event_loop_take_socket_change).
var sockets_handed_over: bool
var socket_changes: ak.Vector[i32]
var exit_requested: bool
var exit_code: i32
var wake_hook: WebViewWakeHook?
## EventLoopImplementation::pump (EventLoopImplementationUnix's). In wait_for_events mode with
## nothing queued it waits until a watched descriptor is ready or the next timer is due
## (spin_until's nested loop; with nothing that can ever happen, waiting would never end, so
## it traps); then it runs a turn. Answers how many events it processed.
func pump(mode: web.CoreEventLoopPumpMode) -> usize:
let waiting = mode == web.CoreEventLoopPumpMode.wait_for_events and ak.vector_is_empty(&self.deferred)
if waiting and self.is_watching():
var deadline = net.Deadline()
if let next = self.next_fire_time():
deadline = net.Deadline.at(next)
_ = web.core_event_loop_notifiers_wait(&self.notifiers, deadline)
return self.run_turn()
if waiting:
let next = self.next_fire_time() else trap("webview: the event loop waits for an event that can never come")
let now = time.now()
if next > now:
thread.sleep((next - now + 999999) // 1000000)
return self.process_once()
## Whether any notifier is registered.
func is_watching() -> bool:
return web.core_event_loop_notifiers_count(&self.notifiers) > 0
## One turn without waiting: the watched descriptors looked at, then run_turn.
func process_once() -> usize:
if self.is_watching():
_ = web.core_event_loop_notifiers_wait(&self.notifiers, net.Deadline.at(0))
return self.run_turn()
## The deferred invocations queued before the turn, the notifiers the last look found ready,
## then the due timers by id, each looked up again before it fires (firing one may stop
## another).
func run_turn() -> usize:
var processed: usize = 0
let pending = self.deferred
self.deferred = ak.Vector[ak.Function0[unit]]()
for index in 0..<ak.vector_size(&pending):
var function = *ak.vector_at_const(&pending, index)
ak.function0_call(&function)
processed += 1
processed += web.core_event_loop_notifiers_dispatch(&self.notifiers)
let now = time.now()
var due: ak.Vector[isize]
for index in 0..<ak.vector_size(&self.timers):
let entry = ak.vector_at_const(&self.timers, index)
if entry.fire_time <= now:
ak.vector_append_t(&due, entry.id)
for index in 0..<ak.vector_size(&due):
let id = *ak.vector_at_const(&due, index)
let slot = self.find_timer(id) else continue
let entry = ak.vector_at(&self.timers, slot)
let timer = entry.timer
if entry.should_reload:
entry.fire_time = now + (u64)entry.interval_ms * 1000000
else:
_ = ak.vector_take(&self.timers, slot)
web.core_timer_timer_event(timer)
processed += 1
return processed
func quit(code: i32):
self.exit_requested = true
self.exit_code = code
func was_exit_requested() -> bool:
return self.exit_requested
## Core::EventLoop::wake: the embedder's loop stops waiting.
func wake():
self.call_wake_hook()
## Core::deferred_invoke: queued, and the embedder's loop woken (the run loop source's
## signal in EventLoopImplementationMacOS::post_event).
func deferred_invoke(function: ak.Function0[unit]):
let was_idle = ak.vector_is_empty(&self.deferred)
ak.vector_append_t(&self.deferred, function)
if was_idle:
self.call_wake_hook()
## EventLoopManagerMacOS::register_timer: the timer's first fire time joins the loop's
## deadlines; the embedder's loop is woken when it is now the earliest.
func register_timer(timer: web.CoreTimer*, milliseconds: i32, should_reload: bool) -> isize:
self.next_timer_id += 1
let interval = milliseconds if milliseconds > 0 else 0
let fire_time = time.now() + (u64)interval * 1000000
let earliest = self.next_fire_time()
ak.vector_append_t(&self.timers, WebViewLoopTimer(timer = timer, id = self.next_timer_id, interval_ms = interval, should_reload = should_reload, fire_time = fire_time))
if earliest == none or fire_time < (earliest else 0):
self.call_wake_hook()
return self.next_timer_id
func unregister_timer(timer_id: isize):
if let slot = self.find_timer(timer_id):
_ = ak.vector_take(&self.timers, slot)
## EventLoopManager::register_notifier: watched from the next turn on. The embedder's loop is
## woken so it comes back within the poll interval, or, when it watches the descriptors
## itself, so it takes the change.
func register_notifier(notifier: web.CoreNotifier*):
let was_watching = self.is_watching()
web.core_event_loop_notifiers_register(&self.notifiers, notifier)
if self.sockets_handed_over:
self.note_socket_change(notifier.m_fd)
elif not was_watching:
self.call_wake_hook()
## EventLoopManager::unregister_notifier.
func unregister_notifier(notifier: web.CoreNotifier*):
web.core_event_loop_notifiers_unregister(&self.notifiers, notifier)
if self.sockets_handed_over:
self.note_socket_change(notifier.m_fd)
## Queues `fd` for the embedder's loop, which watches it (once, however often it changes
## before the embedder takes it); the first change since it last took them wakes it.
func note_socket_change(fd: i32):
let was_idle = ak.vector_is_empty(&self.socket_changes)
for index in 0..<ak.vector_size(&self.socket_changes):
if *ak.vector_at_const(&self.socket_changes, index) == fd:
return
ak.vector_append_t(&self.socket_changes, fd)
if was_idle:
self.call_wake_hook()
## The index of the registered timer `id`, if it is registered.
func find_timer(id: isize) -> usize?:
for index in 0..<ak.vector_size(&self.timers):
if ak.vector_at_const(&self.timers, index).id == id:
return index
return none
## When the next timer is due, if any is registered.
func next_fire_time() -> u64?:
var next: u64? = none
for index in 0..<ak.vector_size(&self.timers):
let fire_time = ak.vector_at_const(&self.timers, index).fire_time
if let earliest = next:
if fire_time < earliest:
next = fire_time
else:
next = fire_time
return next
## Whether anything is queued or due at `now`.
func has_due_work(now: u64) -> bool:
if not ak.vector_is_empty(&self.deferred):
return true
for index in 0..<ak.vector_size(&self.timers):
if ak.vector_at_const(&self.timers, index).fire_time <= now:
return true
return false
func call_wake_hook():
if let hook = self.wake_hook:
hook()
# mark: The process's loop ======================================================================
## The installed loop (one per process, as Core::EventLoopManager is).
var webview_event_loop_the: WebViewEventLoop*?
## Makes the process's loop in the C heap and installs it behind the Core seam with the
## Platform::EventLoopPlugin over it (WebContent's main: Core::EventLoop and
## `Web::Platform::EventLoopPlugin::install(*new Web::Platform::EventLoopPlugin)`).
pub func webview_event_loop_install() -> WebViewEventLoop*:
assert(webview_event_loop_the == none, "webview: the event loop is installed once")
with memory.heap:
let event_loop = new WebViewEventLoop(next_timer_id = 0, notifiers = web.CoreEventLoopNotifiers(), sockets_handed_over = false, exit_requested = false, exit_code = 0, wake_hook = none) else trap("out of memory")
web.core_event_loop_install(event_loop)
let plugin = new web.PlatformEventLoopPlugin else trap("out of memory")
web.platform_event_loop_plugin_install(plugin)
webview_event_loop_the = event_loop
return event_loop
## Makes the loop a root region of `heap` once the VM exists: what it holds stays alive.
pub func webview_event_loop_root(event_loop: WebViewEventLoop*, heap: gc.Heap*):
_ = webview_root_region_create(heap, (const void*)event_loop, memory.size_of(WebViewEventLoop))
## The process's loop.
pub func webview_event_loop() -> WebViewEventLoop*:
return webview_event_loop_the else trap("webview: not initialized (webview.initialize)")
## Sets the embedder's wake hook (none: no wake-ups; the embedder polls).
pub func webview_set_wake_hook(hook: WebViewWakeHook?):
webview_event_loop().wake_hook = hook
## Runs what is due now (the watched descriptors are always looked at), turn after turn, until
## nothing is or a slice has passed; never waits. Answers how many events ran.
pub func webview_event_loop_process(event_loop: WebViewEventLoop*) -> usize:
let start = time.now()
var processed: usize = 0
if event_loop.is_watching() and not event_loop.has_due_work(start):
processed += event_loop.process_once()
while event_loop.has_due_work(time.now()):
processed += event_loop.process_once()
if time.now() - start >= webview_event_loop_slice_nanoseconds:
break
return processed
## When the loop next has work (a time.now() moment): now while invocations are queued, else the
## earliest timer, no later than a poll interval while sockets are watched (unless the embedder
## watches them itself); none when nothing is registered.
pub func webview_event_loop_next_due(event_loop: WebViewEventLoop*) -> u64?:
let now = time.now()
if not ak.vector_is_empty(&event_loop.deferred):
return now
let next = event_loop.next_fire_time()
if event_loop.is_watching() and not event_loop.sockets_handed_over:
let poll = now + webview_event_loop_poll_nanoseconds
if let timer = next:
return timer if timer < poll else poll
return poll
return next
# mark: Sockets the embedder watches ===========================================================
## Makes the embedder's loop watch the notifiers' descriptors (`handed_over`), or the loop poll
## them again: every registered descriptor is queued for the embedder to take, and the poll
## interval stops (or starts again) applying to webview_event_loop_next_due.
pub func webview_event_loop_hand_over_sockets(event_loop: WebViewEventLoop*, handed_over: bool):
event_loop.sockets_handed_over = handed_over
ak.vector_clear(&event_loop.socket_changes)
if not handed_over:
return
for index in 0..<ak.vector_size(&event_loop.notifiers.m_entries):
event_loop.note_socket_change(ak.vector_at_const(&event_loop.notifiers.m_entries, index).notifier.m_fd)
## The next descriptor whose notifiers changed since the embedder last took it, if any; it
## watches it for what webview_event_loop_socket_interest now answers.
pub func webview_event_loop_take_socket_change(event_loop: WebViewEventLoop*) -> i32?:
if ak.vector_is_empty(&event_loop.socket_changes):
return none
return ak.vector_take_first(&event_loop.socket_changes)
## What the notifiers registered for `fd` wait for together: read, write, both, or none_ when none
## is registered (stop watching it). A notifier of neither read nor write (hang-up or error only)
## waits as a reader, as the loop's own wait has it (core_event_loop_notifiers_interest).
pub func webview_event_loop_socket_interest(event_loop: const WebViewEventLoop*, fd: i32) -> web.CoreNotificationType:
var registered = false
var kind = web.CoreNotificationType.none_
for index in 0..<ak.vector_size(&event_loop.notifiers.m_entries):
let notifier = ak.vector_at_const(&event_loop.notifiers.m_entries, index).notifier
if notifier.m_fd == fd:
registered = true
kind = web.core_notification_type_union(kind, notifier.m_type)
let wanted = web.core_notification_type_intersection(kind, web.core_notification_type_union(web.CoreNotificationType.read, web.CoreNotificationType.write))
if registered and wanted == web.CoreNotificationType.none_:
return web.CoreNotificationType.read
return wanted