LibCore: Explain EventLoop and reorder some members in the header

This hopefully makes EventLoop easier to understand.

Userland/Libraries/LibCore/EventLoop.cpp

@@ -71,6 +71,8 @@ static Threading::MutexProtected<RefPtr<InspectorServerConnection>> s_inspector_
 static thread_local Vector<EventLoop&>* s_event_loop_stack;
 static thread_local HashMap<int, NonnullOwnPtr<EventLoopTimer>>* s_timers;
 static thread_local HashTable<Notifier*>* 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)

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
     };
 
+    enum class WaitMode {
+        WaitForEvents,
+        PollForEvents,
+    };
+
     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();
 
-    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
+    // 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<bool()>);
 
+    // Post an event to this event loop and possibly wake the loop.
     void post_event(Object& receiver, NonnullOwnPtr<Event>&&, ShouldWake = ShouldWake::No);
     void wake_once(Object& receiver, int custom_event_type);
 
-    static EventLoop& current();
+    void deferred_invoke(Function<void()> invokee)
+    {
+        auto context = DeferredInvocationContext::construct();
+        post_event(context, make<Core::DeferredInvocationEvent>(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>, Notifier&);
     static void unregister_notifier(Badge<Notifier>, 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<void(int)> 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<void()> invokee)
+    void take_pending_events_from(EventLoop& other)
     {
-        auto context = DeferredInvocationContext::construct();
-        post_event(context, make<Core::DeferredInvocationEvent>(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<Time> get_next_timer_expiration();