1
Fork 0
mirror of https://github.com/RGBCube/serenity synced 2025-07-27 02:37:36 +00:00

LibCore: Explain EventLoop and reorder some members in the header

This hopefully makes EventLoop easier to understand.
This commit is contained in:
kleines Filmröllchen 2022-12-30 15:17:52 +01:00 committed by Jelle Raaijmakers
parent ae6a84c261
commit 2475f6a641
2 changed files with 65 additions and 25 deletions

View file

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