diff --git a/Userland/Libraries/LibCore/EventLoop.cpp b/Userland/Libraries/LibCore/EventLoop.cpp index c4cf6f229a..6e3324b482 100644 --- a/Userland/Libraries/LibCore/EventLoop.cpp +++ b/Userland/Libraries/LibCore/EventLoop.cpp @@ -71,6 +71,8 @@ static Threading::MutexProtected> s_inspector_ static thread_local Vector* s_event_loop_stack; static thread_local HashMap>* s_timers; static thread_local HashTable* s_notifiers; +// The wake pipe is both responsible for notifying us when someone calls wake(), as well as POSIX signals. +// While wake() pushes zero into the pipe, signal numbers (by defintion nonzero, see signal_numbers.h) are pushed into the pipe verbatim. thread_local int EventLoop::s_wake_pipe_fds[2]; thread_local bool EventLoop::s_wake_pipe_initialized { false }; @@ -681,6 +683,9 @@ void EventLoop::wait_for_event(WaitMode mode) fd_set rfds; fd_set wfds; retry: + + // Set up the file descriptors for select(). + // Basically, we translate high-level event information into low-level selectable file descriptors. FD_ZERO(&rfds); FD_ZERO(&wfds); @@ -692,6 +697,7 @@ retry: }; int max_fd_added = -1; + // The wake pipe informs us of POSIX signals as well as manual calls to wake() add_fd_to_set(s_wake_pipe_fds[0], rfds); max_fd = max(max_fd, max_fd_added); @@ -710,6 +716,8 @@ retry: queued_events_is_empty = m_queued_events.is_empty(); } + // Figure out how long to wait at maximum. + // This mainly depends on the WaitMode and whether we have pending events, but also the next expiring timer. Time now; struct timeval timeout = { 0, 0 }; bool should_wait_forever = false; @@ -727,7 +735,9 @@ retry: } try_select_again: + // select() and wait for file system events, calls to wake(), POSIX signals, or timer expirations. int marked_fd_count = select(max_fd + 1, &rfds, &wfds, nullptr, should_wait_forever ? nullptr : &timeout); + // Because POSIX, we might spuriously return from select() with EINTR; just select again. if (marked_fd_count < 0) { int saved_errno = errno; if (saved_errno == EINTR) { @@ -738,6 +748,9 @@ try_select_again: dbgln("Core::EventLoop::wait_for_event: {} ({}: {})", marked_fd_count, saved_errno, strerror(saved_errno)); VERIFY_NOT_REACHED(); } + + // We woke up due to a call to wake() or a POSIX signal. + // Handle signals and see whether we need to handle events as well. if (FD_ISSET(s_wake_pipe_fds[0], &rfds)) { int wake_events[8]; ssize_t nread; @@ -771,6 +784,7 @@ try_select_again: now = Time::now_monotonic_coarse(); } + // Handle expired timers. for (auto& it : *s_timers) { auto& timer = *it.value; if (!timer.has_expired(now)) @@ -796,6 +810,7 @@ try_select_again: if (!marked_fd_count) return; + // Handle file system notifiers by making them normal events. for (auto& notifier : *s_notifiers) { if (FD_ISSET(notifier->fd(), &rfds)) { if (notifier->event_mask() & Notifier::Event::Read) diff --git a/Userland/Libraries/LibCore/EventLoop.h b/Userland/Libraries/LibCore/EventLoop.h index ecdc104c63..1830223675 100644 --- a/Userland/Libraries/LibCore/EventLoop.h +++ b/Userland/Libraries/LibCore/EventLoop.h @@ -26,6 +26,26 @@ namespace Core { +// The event loop enables asynchronous (not parallel or multi-threaded) computing by efficiently handling events from various sources. +// Event loops are most important for GUI programs, where the various GUI updates and action callbacks run on the EventLoop, +// as well as services, where asynchronous remote procedure calls of multiple clients are handled. +// Event loops, through select(), allow programs to "go to sleep" for most of their runtime until some event happens. +// EventLoop is too expensive to use in realtime scenarios (read: audio) where even the time required by a single select() system call is too large and unpredictable. +// +// There is at most one running event loop per thread. +// Another event loop can be started while another event loop is already running; that new event loop will take over for the other event loop. +// This is mainly used in LibGUI, where each modal window stacks another event loop until it is closed. +// However, that means you need to be careful with storing the current event loop, as it might already be gone at the time of use. +// Event loops currently handle these kinds of events: +// - Deferred invocations caused by various objects. These are just a generic way of telling the EventLoop to run some function as soon as possible at a later point. +// - Timers, which repeatedly (or once after a delay) run a function on the EventLoop. Note that timers are not super accurate. +// - Filesystem notifications, i.e. whenever a file is read from, written to, etc. +// - POSIX signals, which allow the event loop to act as a signal handler and dispatch those signals in a more user-friendly way. +// - Fork events, because the child process event loop needs to clear its events and handlers. +// - Quit events, i.e. the event loop should exit. +// Any event that the event loop needs to wait on or needs to repeatedly handle is stored in a handle, e.g. s_timers. +// +// EventLoop has one final responsibility: Handling the InspectorServer connection and processing requests to the Object hierarchy. class EventLoop { public: enum class MakeInspectable { @@ -38,47 +58,51 @@ public: Yes }; - explicit EventLoop(MakeInspectable = MakeInspectable::No); - ~EventLoop(); - static void initialize_wake_pipes(); - - int exec(); - enum class WaitMode { WaitForEvents, PollForEvents, }; - // process events, generally called by exec() in a loop. - // this should really only be used for integrating with other event loops + explicit EventLoop(MakeInspectable = MakeInspectable::No); + ~EventLoop(); + + static void initialize_wake_pipes(); + static bool has_been_instantiated(); + + // Pump the event loop until its exit is requested. + int exec(); + + // Process events, generally called by exec() in a loop. + // This should really only be used for integrating with other event loops. + // The wait mode determines whether pump() uses select() to wait for the next event. size_t pump(WaitMode = WaitMode::WaitForEvents); + // Pump the event loop until some condition is met. void spin_until(Function); + // Post an event to this event loop and possibly wake the loop. void post_event(Object& receiver, NonnullOwnPtr&&, ShouldWake = ShouldWake::No); void wake_once(Object& receiver, int custom_event_type); - static EventLoop& current(); + void deferred_invoke(Function invokee) + { + auto context = DeferredInvocationContext::construct(); + post_event(context, make(context, move(invokee))); + } + void wake(); + + void quit(int); + void unquit(); bool was_exit_requested() const { return m_exit_requested; } + // The registration functions act upon the current loop of the current thread. static int register_timer(Object&, int milliseconds, bool should_reload, TimerShouldFireWhenNotVisible); static bool unregister_timer(int timer_id); static void register_notifier(Badge, Notifier&); static void unregister_notifier(Badge, Notifier&); - void quit(int); - void unquit(); - - void take_pending_events_from(EventLoop& other) - { - m_queued_events.extend(move(other.m_queued_events)); - } - - static void wake_current(); - void wake(); - static int register_signal(int signo, Function handler); static void unregister_signal(int handler_id); @@ -89,14 +113,15 @@ public: }; static void notify_forked(ForkEvent); - static bool has_been_instantiated(); - - void deferred_invoke(Function invokee) + void take_pending_events_from(EventLoop& other) { - auto context = DeferredInvocationContext::construct(); - post_event(context, make(context, move(invokee))); + m_queued_events.extend(move(other.m_queued_events)); } + static EventLoop& current(); + + static void wake_current(); + private: void wait_for_event(WaitMode); Optional