Everywhere: Hoist the Libraries folder to the top-level

Author: https://github.com/trflynn89
Commit: 93712b24bf
Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/2256
Reviewed-by: https://github.com/sideshowbarker

Libraries/LibCore/EventLoop.h

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2018-2023, Andreas Kling <andreas@ladybird.org>
+ * Copyright (c) 2022, kleines Filmröllchen <filmroellchen@serenityos.org>
+ * Copyright (c) 2022, the SerenityOS developers.
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/Forward.h>
+#include <AK/Function.h>
+#include <AK/Noncopyable.h>
+#include <AK/NonnullOwnPtr.h>
+#include <AK/Time.h>
+#include <LibCore/Event.h>
+#include <LibCore/Forward.h>
+
+namespace Core {
+
+class EventLoopImplementation;
+class ThreadEventQueue;
+
+// 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.
+class EventLoop {
+    friend struct EventLoopPusher;
+
+public:
+    enum class WaitMode {
+        WaitForEvents,
+        PollForEvents,
+    };
+
+    EventLoop();
+    ~EventLoop();
+
+    // 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.
+    void post_event(EventReceiver& receiver, NonnullOwnPtr<Event>&&);
+
+    void add_job(NonnullRefPtr<Promise<NonnullRefPtr<EventReceiver>>> job_promise);
+
+    void deferred_invoke(ESCAPING Function<void()>);
+
+    void wake();
+
+    void quit(int);
+    void unquit();
+    bool was_exit_requested() const;
+
+    // The registration functions act upon the current loop of the current thread.
+    static intptr_t register_timer(EventReceiver&, int milliseconds, bool should_reload, TimerShouldFireWhenNotVisible);
+    static void unregister_timer(intptr_t timer_id);
+
+    static void register_notifier(Badge<Notifier>, Notifier&);
+    static void unregister_notifier(Badge<Notifier>, Notifier&);
+
+    static int register_signal(int signo, ESCAPING Function<void(int)> handler);
+    static void unregister_signal(int handler_id);
+
+    // Note: Boost uses Parent/Child/Prepare, but we don't really have anything
+    //       interesting to do in the parent or before forking.
+    enum class ForkEvent {
+        Child,
+    };
+    static void notify_forked(ForkEvent);
+
+    static bool is_running();
+    static EventLoop& current();
+
+    EventLoopImplementation& impl() { return *m_impl; }
+
+private:
+    NonnullOwnPtr<EventLoopImplementation> m_impl;
+};
+
+void deferred_invoke(ESCAPING Function<void()>);
+
+}