LibCore: Explain EventLoop and reorder some members in the header

This hopefully makes EventLoop easier to understand.

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<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();