message_loop_integration.hpp

Go to the documentation of this file.

#pragma once
 
// Per-OS message-loop integration shims.
//
// This header exposes a thin, cross-platform API surface that callers can
// use to introspect and cooperate with the host's native main message loop
// (Cocoa NSRunLoop / Win MsgWaitForMultipleObjects / Linux GLib MainLoop
// or X11/Wayland event sources).
//
// Background:
//   `MainThreadDispatcher` is a process-wide bridge that lets any Pulp
//   subsystem post work to whatever native main-thread queue a platform
//   owner has registered. The macOS plugin-mode helper
//   (`plugin_main_thread.hpp`) adds a refcounted Cocoa backend so format
//   adapters can register at instantiation time. This header sits one
//   level up: it exposes the *kind* of native loop that's currently
//   integrated, so cross-platform code can branch on capabilities (e.g.
//   "do I have a Cocoa run loop I can attach a CFRunLoopObserver to?")
//   without including platform headers.
//
// What this header DOES:
//   - Reports the active backend kind (`MainLoopKind`).
//   - Forwards `call_async` / `call_sync` / `is_main_thread` to the
//     underlying `MainThreadDispatcher` so callers can write one piece
//     of cross-platform code.
//   - Documents the per-OS contract (callback thread, re-entrancy, etc.)
//     for the four loops Pulp targets.
//
// What this header additionally does for headless native hosts:
//   - Offers one bounded main-loop service slice on Apple platforms. This
//     lets offline tools advance plug-ins whose initialization depends on
//     XPC, timers, or main-queue callbacks without taking ownership of the
//     application's event loop.
//
// Platform coverage:
//   - macOS / iOS  — Cocoa NSRunLoop backend via the plugin-mode helper
//     in `plugin_main_thread.hpp`.
//   - Windows      — MsgWaitForMultipleObjects backend pending; the
//     dispatcher will report `MainLoopKind::None` until the standalone
//     Win32 host or VST3 editor registers one.
//   - Linux        — GLib / X11 / Wayland backends pending; same
//     `MainLoopKind::None` story until a backend lands.
 
#include <pulp/events/main_thread_dispatcher.hpp>
 
#include <chrono>
#include <cstdint>
#include <string_view>
 
namespace pulp::events {

enum class MainLoopKind : std::uint8_t {
    None        = 0,    
    Cocoa       = 1,    
    Win32       = 2,    
    GLib        = 3,    
    X11         = 4,    
    Wayland     = 5,    
    Custom      = 255,  
};

enum class MainLoopPumpResult : std::uint8_t {
    HandledSource = 0, 
    TimedOut      = 1, 
    Stopped       = 2, 
    Finished      = 3, 
    Unsupported   = 4, 
    WrongThread   = 5, 
};

class MessageLoopIntegration {
public:
    static MainLoopKind active_kind();

    static std::string_view active_name();

    static bool available();

    static bool is_main_thread();

    static bool post(Task task);

    static bool call_sync(Task task);

    static MainLoopPumpResult
    pump_main_loop_for(std::chrono::milliseconds max_duration);

    static void register_kind(MainThreadDispatcher::Token token, MainLoopKind kind);

    static void unregister_kind(MainThreadDispatcher::Token token);
};
 
// ─── Per-OS contract notes (documentation surface) ──────────────────────
//
// macOS / iOS — Cocoa (MainLoopKind::Cocoa)
//   - Callback thread: the AppKit / UIKit main thread.
//   - Re-entrancy: `call_sync()` from the main thread runs inline; from
//     a worker thread it dispatches via `dispatch_get_main_queue()` and
//     blocks until the block runs.
//   - Cooperation with hosts: the plugin-mode backend in
//     `plugin_main_thread.hpp` is refcounted; safe to call register /
//     unregister once per loaded plugin instance.
//
// Windows — Win32 (MainLoopKind::Win32) — backend pending
//   - Expected callback thread: the thread that owns the message pump
//     (the thread that called `GetMessage` / `MsgWaitForMultipleObjects`).
//   - Re-entrancy: `call_sync()` from the pump thread should run inline;
//     from a worker thread it should `PostMessage` to a hidden window
//     and block on an event.
//
// Linux — GLib / X11 / Wayland — backends pending
//   - GLib hosts: register via `g_main_context_invoke` for `call_async`
//     and a `GMutex` + `GCond` for `call_sync`.
//   - X11 hosts: post to a self-pipe that the main thread reads under
//     `select()`; the X11 event loop ferries the wakeup.
//   - Wayland hosts: use `wl_display_dispatch_pending()` plus a self-pipe
//     wakeup; otherwise indistinguishable from X11 from the caller's POV.
 
} // namespace pulp::events