@gjsify/node-gi 0.58.0 → 0.59.1

package/src/loop.cc

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: MIT
 // libuv <-> GLib main loop bridge: startMainLoop (uv-in-GLib GSource) +
 // iterateMainContext + the uv-driven GLib auto-pump (GLib-in-libuv, the
-// non-blocking case).
+// non-blocking case). Where there is no libuv (Android/NativeScript,
+// NODE_GI_HAS_LIBUV off) the auto-pump rides the thread's ALooper instead; both
+// halves implement the same Pump* interface and only one is compiled in.
 
 #include "common.h"
 
@@ -18,8 +20,36 @@
 #include <glib-unix.h>
 #endif
 
+#if !NODE_GI_HAS_LIBUV && defined(__ANDROID__)
+// The libuv-less half of the auto-pump rides the thread's ALooper instead of a
+// uv loop, with a timerfd carrying GLib's next deadline. ALooper_* comes from
+// libandroid, so this build needs -landroid — the NativeScript runtime links it
+// already; the standalone cross-build passes it explicitly.
+#include <algorithm>
+
+#include <android/looper.h>
+#include <sys/timerfd.h>
+#include <unistd.h>
+#endif
+
 namespace nodegi {
 
+static napi_env g_loop_env = nullptr;  // captured at startMainLoop (main thread)
+static gboolean g_loop_started = FALSE;
+
+// TRUE while THIS addon's auto-pump is inside its own GLib work — draining the
+// context or running the prepare/query hint pass. On Node the UvLoopSource
+// consults it to PARK itself (mask the backend fd, report not-ready, skip
+// uv_run): a pump-driven context iteration must never dispatch the uv-in-GLib
+// source, or it would nest uv_run inside the very uv callback that drives the
+// pump (uv_run is not reentrant) — and recursively re-enter the pump itself. On
+// every host it additionally keeps the drain and the hint pass out of each
+// other, which is all it does on the libuv-less Android pump (no co-pump there,
+// so nothing to park). Name kept for the incident trail in common.h.
+static gboolean g_in_uv_pump = FALSE;
+
+#if NODE_GI_HAS_LIBUV
+
 // ---- libuv <-> GLib main loop bridge (milestone: mainloop) ----
 //
 // Port of node-gtk's src/loop.cc (romgrk and contributors, MIT) to N-API. Nests
@@ -43,19 +73,9 @@ struct UvLoopSource {
 #endif
 };
 
-static napi_env g_loop_env = nullptr;       // captured at startMainLoop (main thread)
-static gboolean g_loop_started = FALSE;
 static napi_ref g_process_ref = nullptr;        // process
 static napi_ref g_tick_callback_ref = nullptr;  // process._tickCallback
 
-// TRUE while the uv-driven auto-pump (below) is inside its own GLib work —
-// draining the context or running the prepare/query hint pass. The UvLoopSource
-// consults it to PARK itself (mask the backend fd, report not-ready, skip
-// uv_run): a pump-driven context iteration must never dispatch the uv-in-GLib
-// source, or it would nest uv_run inside the very uv callback that drives the
-// pump (uv_run is not reentrant) — and recursively re-enter the pump itself.
-static gboolean g_in_uv_pump = FALSE;
-
 // Drain Node's nextTick queue + run a microtask checkpoint. process._tickCallback
 // invoked through napi_make_callback runs the tick queue, and the surrounding
 // callback scope's close performs the microtask checkpoint — the N-API analogue
@@ -92,6 +112,8 @@ static void DrainMicrotasks() {
   napi_close_handle_scope(env, scope);
 }
 
+#endif  // NODE_GI_HAS_LIBUV (UvLoopSource + the Node nextTick/microtask drain)
+
 // ---- cross-runtime microtask checkpoint (Bun/Deno) --------------------------
 //
 // Node's napi_make_callback performs the nextTick + microtask checkpoint when
@@ -176,6 +198,7 @@ void NodeGiMaybeDrainMicrotasks(napi_env env) {
   napi_close_handle_scope(env, scope);
 }
 
+#if NODE_GI_HAS_LIBUV
 #ifndef _WIN32
 static gboolean uv_source_prepare(GSource* base, gint* timeout) {
   UvLoopSource* s = reinterpret_cast<UvLoopSource*>(base);
@@ -316,6 +339,7 @@ static GSourceFuncs uv_source_funcs = {
     uv_source_prepare, uv_source_check, uv_source_dispatch, nullptr, nullptr, nullptr,
 };
 #endif  // _WIN32 (UvLoopSource: POSIX fd-driven / Windows readiness-bounded co-pump)
+#endif  // NODE_GI_HAS_LIBUV
 
 // iterateMainContext(mayBlock?) -> boolean
 //
@@ -334,13 +358,139 @@ Napi::Value IterateMainContext(const Napi::CallbackInfo& info) {
   return Napi::Boolean::New(env, dispatched == TRUE);
 }
 
-// ---- uv-driven GLib auto-pump (the non-blocking case) -----------------------
+// ---- the GLib auto-pump (the non-blocking case) -----------------------------
 //
-// The inverse co-pump of UvLoopSource: with NO blocking GLib loop running, a
-// plain `node bundle.mjs` still needs pending GLib sources (Gio async
+// With NO blocking GLib loop running, a plain `node bundle.mjs` (or a
+// NativeScript Android app) still needs pending GLib sources (Gio async
 // completions, GLib timeouts/idles, DBus) to dispatch — under GJS the GLib loop
-// IS the process loop, so they always do. Here Node's libuv loop drives the
-// default GLib main context instead:
+// IS the process loop, so they always do. The HOST's own event loop drives the
+// default GLib main context instead, and the two halves of that are the same on
+// every host:
+//
+//   • DRAIN — dispatch everything the context has ready right now
+//     (PumpDrainContext), run from the host loop with a valid napi scope;
+//   • WAKE — ask the context when its earliest timer is due and which fds it
+//     polls (PumpQueryWakeups), then mirror both into whatever primitive the
+//     host wakes on (PumpArmWakeups, the one host-specific half: libuv
+//     timer/poll watchers on Node, a timerfd + ALooper_addFd on Android).
+//
+// Both of those must never run while a blocking GLib loop owns the context
+// (g_main_depth() > 0) or re-entrantly from our own GLib work (g_in_uv_pump).
+
+static gboolean g_pump_inited = FALSE;
+static gboolean g_pump_context_acquired = FALSE;
+static std::vector<GPollFD>* g_pump_fds = nullptr;  // query scratch (reused)
+static int g_pump_async_pending = 0;  // in-flight scope=async GI callbacks
+
+// Host-specific: mirror the queried deadline + fds into the host's wake-up
+// primitives. Defined once per host below.
+static void PumpArmWakeups();
+
+// Drain every currently-ready GLib source (bounded). Each iteration is a full,
+// self-contained GLib cycle, so readiness (fds, timers, idles) is re-evaluated
+// natively — the host's watchers are pure wake-ups. No-op while a blocking GLib
+// loop is dispatching (g_main_depth() > 0) or when re-entered from a nested
+// host-loop turn inside our own dispatch (g_in_uv_pump).
+static void PumpDrainContext() {
+  if (g_main_depth() > 0 || g_in_uv_pump) return;
+  GMainContext* ctx = g_main_context_default();
+  // The drain runs from a bare host-loop C callback — there is NO ambient V8
+  // HandleScope (unlike a blocking run(), which is entered through a
+  // JS-initiated N-API frame). Anything the dispatched sources do that creates
+  // JS handles outside its own scope (the toggle-ref bridge's
+  // napi_get_reference_value on a GTask teardown unref, most prominently) would
+  // abort with "Cannot create a handle without a HandleScope" — so provide one
+  // for the whole drain.
+  napi_handle_scope scope = nullptr;
+  if (g_loop_env != nullptr) napi_open_handle_scope(g_loop_env, &scope);
+  g_in_uv_pump = TRUE;
+  int guard = 0;
+  while (g_main_context_iteration(ctx, FALSE) && ++guard < 1000) {
+  }
+  g_in_uv_pump = FALSE;
+  if (scope != nullptr) napi_close_handle_scope(g_loop_env, scope);
+}
+
+// The prepare+query+check HINT pass: learn GLib's earliest-timer deadline and
+// which fds it polls, leaving the queried set in g_pump_fds[0..n). Returns the
+// fd count, or -1 when the pass must not run. `*timeout` is GLib's
+// milliseconds-to-next-deadline: 0 = work due now, -1 = no deadline. The
+// g_in_uv_pump flag is held across it so UvLoopSource stays parked (masking
+// uv's backend fd out of the queried set — it must not be watched, and uv's own
+// backend timeout must not feed back into the deadline hint).
+//
+// The CHECK is not cosmetic and must never be dropped again: a GSource may hold
+// a LOCK between its prepare() and its check(), and leaving the context prepared
+// deadlocks the process on the next call into that library. GDK's Wayland event
+// source is exactly that shape — its prepare() takes libwayland's designated-reader
+// slot (`wl_display_prepare_read_queue`) and only its check() releases it
+// (`wl_display_read_events` / `wl_display_cancel_read`). Measured (gjsify #1145,
+// gtk 4.22 / Fedora 44 / Mesa Vulkan): with the hint pass ending at query, the very
+// next `gtk_window_present()` blocked forever inside `wl_display_roundtrip_queue`
+// under `gsk_renderer_new_for_surface_full`, so the app never finished showing its
+// window while its GDBus worker thread kept answering Peer.Ping and Introspect —
+// a live process at ~0.5 % CPU that read as "devtools hangs". Only Wayland shows
+// it (GdkX11's source holds nothing across the pair), only node (bun/deno pump
+// through complete `g_main_context_iteration`s), and only once GTK was initialised
+// at g_main_depth() == 0 — `Gio.Application.register()` before `runAsync()` does
+// exactly that, which is why an app that only ever calls `run()` never saw it.
+// Passing revents = 0 is the right reading: this pass did NOT poll, so no fd is
+// reported ready and every source that took something in prepare() gives it back.
+//
+// No dispatch pairs with the check: g_main_context_prepare() clears
+// pending_dispatches on entry (glib gmain.c), and PumpDrainContext() runs on the
+// same host-loop turn, so anything this marks ready is dispatched there rather
+// than being stranded.
+static int PumpQueryWakeups(gint* timeout) {
+  if (!g_pump_inited || g_main_depth() > 0 || g_in_uv_pump) return -1;
+  GMainContext* ctx = g_main_context_default();
+  gint prio = 0;
+  *timeout = -1;
+  g_in_uv_pump = TRUE;
+  g_main_context_prepare(ctx, &prio);
+  int nfds = g_main_context_query(ctx, prio, timeout, g_pump_fds->data(),
+                                  static_cast<gint>(g_pump_fds->size()));
+  while (nfds > static_cast<int>(g_pump_fds->size())) {
+    g_pump_fds->resize(nfds);
+    nfds = g_main_context_query(ctx, prio, timeout, g_pump_fds->data(),
+                                static_cast<gint>(g_pump_fds->size()));
+  }
+  // g_main_context_query fills fd + events and leaves revents untouched, so the
+  // previous pass's values would otherwise be replayed as fresh readiness.
+  for (int i = 0; i < nfds; i++) (*g_pump_fds)[i].revents = 0;
+  g_main_context_check(ctx, prio, g_pump_fds->data(), nfds);
+  g_in_uv_pump = FALSE;
+  return nfds;
+}
+
+// Own the default context on this (the JS) thread. Required so a cross-thread
+// g_source_attach (a completing GTask worker) signals the context's wakeup
+// eventfd — which the host's fd watcher turns into a host-loop wake. Same-thread
+// recursive acquisition by a later blocking g_main_loop_run() still works.
+static void PumpAcquireContext() {
+  g_pump_fds = new std::vector<GPollFD>(16);
+  g_pump_context_acquired = g_main_context_acquire(g_main_context_default());
+  if (!g_pump_context_acquired) {
+    g_printerr("(node-gi) warning: default GMainContext is owned by another thread; "
+               "cross-thread wakeups may be delayed\n");
+  }
+}
+
+static void PumpReleaseContext() {
+  delete g_pump_fds;
+  g_pump_fds = nullptr;
+  if (g_pump_context_acquired) {
+    g_main_context_release(g_main_context_default());
+    g_pump_context_acquired = FALSE;
+  }
+}
+
+#if NODE_GI_HAS_LIBUV
+
+// ---- the libuv-driven half (Node) -------------------------------------------
+//
+// The inverse co-pump of UvLoopSource: Node's libuv loop drives the default GLib
+// main context.
 //
 //   • a uv_prepare + uv_check handle pair drains every READY GLib source once
 //     per libuv loop turn (a bounded `g_main_context_iteration(ctx, FALSE)`
@@ -384,15 +534,11 @@ struct PumpPoll {
   gboolean started;  // whether the watcher is currently armed (see PumpPollCb)
 };
 
-static gboolean g_pump_inited = FALSE;
-static gboolean g_pump_context_acquired = FALSE;
 static uv_prepare_t g_pump_prepare;
 static uv_check_t g_pump_check;
 static uv_timer_t g_pump_timer;
 static gboolean g_pump_timer_reffed = FALSE;
 static std::unordered_map<int, PumpPoll*>* g_pump_polls = nullptr;
-static std::vector<GPollFD>* g_pump_fds = nullptr;  // query scratch (reused)
-static int g_pump_async_pending = 0;  // in-flight scope=async GI callbacks
 static gboolean g_pump_prepare_reffed = FALSE;
 static gboolean g_pump_poll_warned = FALSE;
 
@@ -508,78 +654,12 @@ static gboolean SyncPumpPolls(int nfds) {
 #endif  // _WIN32
 }
 
-// Drain every currently-ready GLib source (bounded). Each iteration is a full,
-// self-contained GLib cycle, so readiness (fds, timers, idles) is re-evaluated
-// natively — the uv watchers are pure wake-ups. No-op while a blocking GLib
-// loop is dispatching (g_main_depth() > 0) or when re-entered from a nested
-// uv_run inside our own dispatch (g_in_uv_pump).
-static void PumpDrainContext() {
-  if (g_main_depth() > 0 || g_in_uv_pump) return;
-  GMainContext* ctx = g_main_context_default();
-  // The drain runs from a bare uv_prepare/uv_check C callback — there is NO
-  // ambient V8 HandleScope (unlike a blocking run(), which is entered through a
-  // JS-initiated N-API frame). Anything the dispatched sources do that creates
-  // JS handles outside its own scope (the toggle-ref bridge's
-  // napi_get_reference_value on a GTask teardown unref, most prominently) would
-  // abort with "Cannot create a handle without a HandleScope" — so provide one
-  // for the whole drain.
-  napi_handle_scope scope = nullptr;
-  if (g_loop_env != nullptr) napi_open_handle_scope(g_loop_env, &scope);
-  g_in_uv_pump = TRUE;
-  int guard = 0;
-  while (g_main_context_iteration(ctx, FALSE) && ++guard < 1000) {
-  }
-  g_in_uv_pump = FALSE;
-  if (scope != nullptr) napi_close_handle_scope(g_loop_env, scope);
-}
-
-// The prepare+query+check HINT pass: learn GLib's earliest-timer deadline + poll
-// fds and mirror them into the uv timer / uv_poll watchers, so libuv's poll sleep
-// ends exactly when GLib next has work. Runs only at g_main_depth() == 0; the
-// g_in_uv_pump flag is held across it so UvLoopSource stays parked (masking uv's
-// backend fd out of the queried set — it must not be uv_poll'd, and uv's own
-// backend timeout must not feed back into the timer hint).
-//
-// The CHECK is not cosmetic and must never be dropped again: a GSource may hold a
-// LOCK between its prepare() and its check(), and leaving the context prepared
-// deadlocks the process on the next call into that library. GDK's Wayland event
-// source is exactly that shape — its prepare() takes libwayland's designated-reader
-// slot (`wl_display_prepare_read_queue`) and only its check() releases it
-// (`wl_display_read_events` / `wl_display_cancel_read`). Measured (gjsify #1145,
-// gtk 4.22 / Fedora 44 / Mesa Vulkan): with the hint pass ending at query, the very
-// next `gtk_window_present()` blocked forever inside `wl_display_roundtrip_queue`
-// under `gsk_renderer_new_for_surface_full`, so the app never finished showing its
-// window while its GDBus worker thread kept answering Peer.Ping and Introspect —
-// a live process at ~0.5 % CPU that read as "devtools hangs". Only Wayland shows
-// it (GdkX11's source holds nothing across the pair), only node (bun/deno pump
-// through complete `g_main_context_iteration`s), and only once GTK was initialised
-// at g_main_depth() == 0 — `Gio.Application.register()` before `runAsync()` does
-// exactly that, which is why an app that only ever calls `run()` never saw it.
-// Passing revents = 0 is the right reading: this pass did NOT poll, so no fd is
-// reported ready and every source that took something in prepare() gives it back.
+// Mirror GLib's queried deadline + fds into the uv timer / uv_poll watchers, so
+// libuv's poll sleep ends exactly when GLib next has work.
 static void PumpArmWakeups() {
-  if (!g_pump_inited || g_main_depth() > 0 || g_in_uv_pump) return;
-  GMainContext* ctx = g_main_context_default();
-  gint prio = 0;
   gint timeout = -1;
-  g_in_uv_pump = TRUE;
-  g_main_context_prepare(ctx, &prio);
-  int nfds = g_main_context_query(ctx, prio, &timeout, g_pump_fds->data(),
-                                  static_cast<gint>(g_pump_fds->size()));
-  while (nfds > static_cast<int>(g_pump_fds->size())) {
-    g_pump_fds->resize(nfds);
-    nfds = g_main_context_query(ctx, prio, &timeout, g_pump_fds->data(),
-                                static_cast<gint>(g_pump_fds->size()));
-  }
-  // g_main_context_query fills fd + events and leaves revents untouched, so the
-  // previous pass's values would otherwise be replayed as fresh readiness.
-  for (int i = 0; i < nfds; i++) (*g_pump_fds)[i].revents = 0;
-  // No dispatch pairs with this check: g_main_context_prepare() clears
-  // pending_dispatches on entry (glib gmain.c), and PumpDrainContext() — a full
-  // iteration — runs on the same libuv turn, so anything this marks ready is
-  // dispatched there rather than being stranded.
-  g_main_context_check(ctx, prio, g_pump_fds->data(), nfds);
-  g_in_uv_pump = FALSE;
+  const int nfds = PumpQueryWakeups(&timeout);
+  if (nfds < 0) return;
 
   if (!SyncPumpPolls(nfds)) {
     // Degraded wake path: poll at a short cadence instead of on readiness. This is
@@ -641,6 +721,244 @@ static void PumpCheckCb(uv_check_t* /*h*/) {
   PumpArmWakeups();
 }
 
+static void PumpInit(uv_loop_t* loop) {
+  if (g_pump_inited) return;
+  g_pump_polls = new std::unordered_map<int, PumpPoll*>();
+  PumpAcquireContext();
+
+  uv_prepare_init(loop, &g_pump_prepare);
+  uv_prepare_start(&g_pump_prepare, PumpPrepareCb);
+  uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
+
+  uv_check_init(loop, &g_pump_check);
+  uv_check_start(&g_pump_check, PumpCheckCb);
+  uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_check));
+
+  uv_timer_init(loop, &g_pump_timer);
+  uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
+
+  g_pump_inited = TRUE;
+}
+
+// Close the pump's uv handles so the loop can wind down cleanly.
+static void PumpShutdownPlatform() {
+  uv_prepare_stop(&g_pump_prepare);
+  uv_check_stop(&g_pump_check);
+  uv_timer_stop(&g_pump_timer);
+  uv_close(reinterpret_cast<uv_handle_t*>(&g_pump_prepare), nullptr);
+  uv_close(reinterpret_cast<uv_handle_t*>(&g_pump_check), nullptr);
+  uv_close(reinterpret_cast<uv_handle_t*>(&g_pump_timer), nullptr);
+  if (g_pump_polls != nullptr) {
+    for (auto& it : *g_pump_polls) {
+      uv_poll_stop(&it.second->handle);
+      uv_close(reinterpret_cast<uv_handle_t*>(&it.second->handle), PumpPollCloseCb);
+    }
+    delete g_pump_polls;
+    g_pump_polls = nullptr;
+  }
+}
+
+#elif defined(__ANDROID__)
+
+// ---- the ALooper-driven half (Android / NativeScript) -----------------------
+//
+// NativeScript's V8 runtime is a Node-API host with NO libuv of its own, so the
+// whole uv half above is compiled out (NODE_GI_HAS_LIBUV 0 — common.h explains
+// why a mere REFERENCE to a uv symbol is fatal there, not just a call). The
+// host's event loop is Android's own ALooper on the thread that runs JS, and the
+// pump mirrors GLib onto it with the two halves named at the top of this
+// section:
+//
+//   • WAKE — every fd GLib queries is registered with ALooper_addFd, and GLib's
+//     next deadline is armed on a timerfd registered the same way. The looper
+//     then wakes for GLib I/O, for a cross-thread wakeup (the context's own
+//     eventfd, signalled by a completing GTask worker) and for GLib timers
+//     alike, instead of for a uv_poll/uv_timer.
+//   • DRAIN — a looper callback runs from the host's poll, OUTSIDE any JS frame
+//     or handle scope, so it must not touch napi or JS at all. It only posts a
+//     threadsafe function; the TSFN's call_js runs on the JS thread inside a
+//     proper handle + callback scope and does the drain plus the re-arm.
+//
+// No keep-alive half: Android's looper belongs to the app and outlives every
+// pump, so there is nothing to ref or unref. g_pump_async_pending is still
+// maintained (calls.cc does it unconditionally) and still answers
+// mainContextHasPending(); it just holds nothing open here.
+//
+// NOT supported on this host: a BLOCKING GLib.MainLoop.run() / Gio.Application
+// .run() on the UI thread. It would park Android's own looper — no input, no
+// frames, an ANR — and there is no co-pump to borrow (UvLoopSource embeds uv's
+// backend fd in a GSource; a looper exposes no such fd). Nothing refuses it at
+// build or link time, since the boxed GLib.MainLoop surface is host-independent;
+// it simply freezes the thread it is called on. An app drives GLib through this
+// pump instead.
+
+static ALooper* g_looper = nullptr;
+static napi_threadsafe_function g_pump_tsfn = nullptr;
+static int g_pump_timerfd = -1;
+// The GLib poll fds currently registered with the looper (not the timerfd, which
+// is added once and stays). Small by nature — a linear sweep beats a hash map.
+static std::vector<int>* g_looper_fds = nullptr;
+// A drain post is already in flight: one looper poll can report several fds
+// ready for a single GLib cycle, and one drain answers all of them. Written only
+// on the JS thread (every poster runs there), so no atomic.
+static gboolean g_pump_posted = FALSE;
+
+// Ask for a drain on the JS thread. Callable from a looper callback: the only
+// napi function it touches is the non-blocking TSFN post, which is the one
+// documented to be legal from any thread at any time.
+static void PumpPostTsfn() {
+  if (g_pump_tsfn == nullptr || g_pump_posted) return;
+  if (napi_call_threadsafe_function(g_pump_tsfn, nullptr, napi_tsfn_nonblocking) == napi_ok) {
+    g_pump_posted = TRUE;
+  }
+}
+
+// A GLib poll fd became ready. Wake-only, and the wake is an EDGE for the same
+// reason as on libuv (#1912): ALooper is level-triggered and this callback reads
+// nothing, so an fd that STAYS ready — the context's wakeup eventfd, which
+// block_source() re-signals on every dispatch, or a dead socket at POLLHUP —
+// would spin the host loop at 100 % CPU. Returning 0 removes the registration;
+// PumpArmWakeups re-adds whatever GLib still queries.
+static int PumpLooperFdCb(int /*fd*/, int /*events*/, void* /*data*/) {
+  PumpPostTsfn();
+  return 0;
+}
+
+// The timerfd expired. This one KEEPS its registration (returns 1): read() is
+// what clears the expiry, so it cannot stay spuriously ready, and an
+// armed-again timer needs only a new itimerspec, not a new watcher.
+static int PumpTimerFdCb(int fd, int /*events*/, void* /*data*/) {
+  uint64_t expirations = 0;
+  while (read(fd, &expirations, sizeof(expirations)) == sizeof(expirations)) {
+  }
+  PumpPostTsfn();
+  return 1;
+}
+
+// Register every fd GLib queries, and drop the ones it no longer does.
+// ALooper_addFd REPLACES an existing registration for the same fd, which is how
+// a self-removed watcher (PumpLooperFdCb returning 0) comes back.
+static void SyncLooperFds(int nfds) {
+  std::vector<int> wanted;
+  wanted.reserve(static_cast<size_t>(nfds));
+  for (int i = 0; i < nfds; i++) {
+    const GPollFD& pfd = (*g_pump_fds)[i];
+    int events = 0;
+    if (pfd.events & (G_IO_IN | G_IO_HUP | G_IO_ERR)) events |= ALOOPER_EVENT_INPUT;
+    if (pfd.events & G_IO_OUT) events |= ALOOPER_EVENT_OUTPUT;
+    if (events == 0) continue;
+    if (ALooper_addFd(g_looper, pfd.fd, ALOOPER_POLL_CALLBACK, events, PumpLooperFdCb,
+                      nullptr) == 1) {
+      wanted.push_back(pfd.fd);
+    }
+  }
+  for (int fd : *g_looper_fds) {
+    if (std::find(wanted.begin(), wanted.end(), fd) == wanted.end()) {
+      ALooper_removeFd(g_looper, fd);
+    }
+  }
+  *g_looper_fds = std::move(wanted);
+}
+
+// Mirror GLib's deadline onto the timerfd. An all-zero it_value DISARMS a
+// timerfd rather than firing immediately, so a 0 ms deadline ("work is due now")
+// has to be answered by posting the drain directly; that drain re-arms.
+static void ArmTimerfd(gint timeout) {
+  if (g_pump_timerfd < 0) return;
+  if (timeout == 0) {
+    PumpPostTsfn();
+    timeout = -1;
+  }
+  struct itimerspec its = {};
+  if (timeout > 0) {
+    its.it_value.tv_sec = timeout / 1000;
+    its.it_value.tv_nsec = static_cast<long>(timeout % 1000) * 1000000L;
+  }
+  timerfd_settime(g_pump_timerfd, 0, &its, nullptr);
+}
+
+static void PumpArmWakeups() {
+  gint timeout = -1;
+  const int nfds = PumpQueryWakeups(&timeout);
+  if (nfds < 0) return;
+  SyncLooperFds(nfds);
+  ArmTimerfd(timeout);
+}
+
+// The drain, on the JS thread, inside the scopes the TSFN infra provides.
+static void PumpTsfnCb(napi_env /*env*/, napi_value /*js_cb*/, void* /*context*/,
+                       void* /*data*/) {
+  g_pump_posted = FALSE;
+  if (!g_pump_inited) return;
+  PumpDrainContext();
+  PumpArmWakeups();
+}
+
+static void PumpInit(napi_env env, ALooper* looper) {
+  if (g_pump_inited) return;
+  g_looper = looper;
+  g_looper_fds = new std::vector<int>();
+  PumpAcquireContext();
+
+  // js_func null — PumpTsfnCb IS the callback, and the TSFN infra invokes it
+  // inside a handle + callback scope, so a dispatched GLib source re-entering JS
+  // runs as a proper N-API callback. max_queue_size 1 coalesces bursts;
+  // initial_thread_count 1 keeps it alive for the env's lifetime, so a looper
+  // callback may post without acquiring first. Same shape as toggle.cc's drain.
+  napi_value name = nullptr;
+  napi_create_string_utf8(env, "node-gi:glib-pump", NAPI_AUTO_LENGTH, &name);
+  if (napi_create_threadsafe_function(env, nullptr, nullptr, name, /*max_queue_size*/ 1,
+                                      /*initial_thread_count*/ 1, nullptr, nullptr, nullptr,
+                                      PumpTsfnCb, &g_pump_tsfn) != napi_ok) {
+    g_pump_tsfn = nullptr;
+  } else {
+    // The pump must not hold the host loop open by itself (the uv_unref
+    // equivalent). Best-effort: NativeScript no-ops TSFN ref/unref, and its
+    // looper does not end anyway.
+    napi_unref_threadsafe_function(env, g_pump_tsfn);
+  }
+
+  // NONBLOCK because PumpTimerFdCb read()s until EAGAIN; CLOEXEC so no
+  // Gio.Subprocess child inherits it.
+  g_pump_timerfd = timerfd_create(CLOCK_MONOTONIC, TFD_NONBLOCK | TFD_CLOEXEC);
+  if (g_pump_timerfd >= 0) {
+    ALooper_addFd(g_looper, g_pump_timerfd, ALOOPER_POLL_CALLBACK, ALOOPER_EVENT_INPUT,
+                  PumpTimerFdCb, nullptr);
+  }
+
+  g_pump_inited = TRUE;
+  // Arm the first wake-ups now. The uv half gets this for free from its
+  // always-active prepare handle, which runs on the very next loop turn; here
+  // nothing would ever ask until something already woke the looper.
+  PumpArmWakeups();
+}
+
+// Unregister everything the pump put on the looper. Reached only through an env
+// cleanup hook, which NativeScript never runs for the main env — so on the live
+// host this is dead code, kept because the pump must not leak a watcher into a
+// looper that outlives it on any host that DOES tear an env down.
+static void PumpShutdownPlatform() {
+  if (g_pump_tsfn != nullptr) {
+    napi_release_threadsafe_function(g_pump_tsfn, napi_tsfn_release);
+    g_pump_tsfn = nullptr;
+  }
+  if (g_looper_fds != nullptr) {
+    for (int fd : *g_looper_fds) ALooper_removeFd(g_looper, fd);
+    delete g_looper_fds;
+    g_looper_fds = nullptr;
+  }
+  if (g_pump_timerfd >= 0) {
+    ALooper_removeFd(g_looper, g_pump_timerfd);
+    close(g_pump_timerfd);
+    g_pump_timerfd = -1;
+  }
+  g_looper = nullptr;
+}
+
+#else
+#error "no GLib auto-pump for this host: it has neither libuv nor an ALooper"
+#endif  // NODE_GI_HAS_LIBUV / __ANDROID__ (the host-specific pump half)
+
 // pumpKick() -> void — drain ready GLib sources + re-arm the wake hints NOW.
 // The L1 layer calls this from a `process.on('beforeExit')` hook: with only
 // UNREF'd handles active, uv_run(UV_RUN_DEFAULT) returns without ever running
@@ -656,6 +974,14 @@ Napi::Value PumpKick(const Napi::CallbackInfo& info) {
   if (g_pump_inited && static_cast<napi_env>(info.Env()) == g_loop_env) {
     PumpDrainContext();
     PumpArmWakeups();
+#if !NODE_GI_HAS_LIBUV && defined(__ANDROID__)
+    // Both calls above no-op while a blocking GLib loop owns the context or we
+    // are re-entered from our own dispatch, and on this host nothing else will
+    // come back for the work: the uv half has an always-active prepare handle
+    // that retries every loop turn, the looper only wakes for something it
+    // watches. The post defers the kick to a later JS-thread turn instead.
+    PumpPostTsfn();
+#endif
   }
   return info.Env().Undefined();
 }
@@ -668,35 +994,6 @@ NodeGiPumpJsDispatchScope::NodeGiPumpJsDispatchScope() : saved_(g_in_uv_pump) {
 }
 NodeGiPumpJsDispatchScope::~NodeGiPumpJsDispatchScope() { g_in_uv_pump = saved_; }
 
-static void PumpInit(uv_loop_t* loop) {
-  if (g_pump_inited) return;
-  g_pump_polls = new std::unordered_map<int, PumpPoll*>();
-  g_pump_fds = new std::vector<GPollFD>(16);
-
-  // Own the default context on this (the JS) thread. Required so a cross-thread
-  // g_source_attach (a completing GTask worker) signals the context's wakeup
-  // eventfd — which our uv_poll watcher turns into a libuv wake. Same-thread
-  // recursive acquisition by a later blocking g_main_loop_run() still works.
-  g_pump_context_acquired = g_main_context_acquire(g_main_context_default());
-  if (!g_pump_context_acquired) {
-    g_printerr("(node-gi) warning: default GMainContext is owned by another thread; "
-               "cross-thread wakeups may be delayed\n");
-  }
-
-  uv_prepare_init(loop, &g_pump_prepare);
-  uv_prepare_start(&g_pump_prepare, PumpPrepareCb);
-  uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
-
-  uv_check_init(loop, &g_pump_check);
-  uv_check_start(&g_pump_check, PumpCheckCb);
-  uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_check));
-
-  uv_timer_init(loop, &g_pump_timer);
-  uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
-
-  g_pump_inited = TRUE;
-}
-
 // mainContextHasPending() -> boolean
 //
 // Is there JS-armed GLib work a *pumping* runtime must stay alive for? True
@@ -762,49 +1059,51 @@ Napi::Value MakePumpPendingCount(const Napi::CallbackInfo& info) {
 bool NodeGiPumpAsyncBegin(napi_env env) {
   if (g_loop_env != nullptr && env != g_loop_env) return false;
   ++g_pump_async_pending;
+#if NODE_GI_HAS_LIBUV
   if (g_pump_inited && g_pump_async_pending == 1 && !g_pump_prepare_reffed) {
     uv_ref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
     g_pump_prepare_reffed = TRUE;
   }
+#else
+  // Nothing to hold open here (§ the ALooper half), but the work just armed may
+  // be a SAME-THREAD source — a GLib idle or timeout added from JS — which does
+  // not signal the context's wakeup eventfd, so no fd the looper watches
+  // changed and the looper would sleep straight past it. Ask for a drain, which
+  // re-arms the timerfd to the new deadline. (The uv half needs no equivalent:
+  // its prepare handle re-queries on the very next loop turn.)
+  //
+  // This covers same-thread sources armed FROM JS only. One armed inside a C
+  // library on this thread — GDK's repeating timeout is the known case, and only
+  // track C of ADR 0104 reaches it — still waits for the next drain, because
+  // nothing re-queries the context per looper turn the way uv's prepare does.
+  if (g_pump_inited) PumpPostTsfn();
+#endif
   return true;
 }
 
 void NodeGiPumpAsyncEnd() {
   if (g_pump_async_pending == 0) return;
   --g_pump_async_pending;
+#if NODE_GI_HAS_LIBUV
   if (g_pump_inited && g_pump_async_pending == 0 && g_pump_prepare_reffed) {
     uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
     g_pump_prepare_reffed = FALSE;
   }
+#endif
 }
 
-// Env-teardown: close the pump's uv handles so the loop can wind down cleanly.
-// Only the env that armed the pump (the main env) tears it down.
+// Env-teardown: release the pump's host handles so the host loop can wind down
+// cleanly, then give the context back. Only the env that armed the pump (the
+// main env) tears it down.
 void NodeGiPumpShutdown(napi_env env) {
   if (!g_pump_inited || env != g_loop_env) return;
   g_pump_inited = FALSE;
-  uv_prepare_stop(&g_pump_prepare);
-  uv_check_stop(&g_pump_check);
-  uv_timer_stop(&g_pump_timer);
-  uv_close(reinterpret_cast<uv_handle_t*>(&g_pump_prepare), nullptr);
-  uv_close(reinterpret_cast<uv_handle_t*>(&g_pump_check), nullptr);
-  uv_close(reinterpret_cast<uv_handle_t*>(&g_pump_timer), nullptr);
-  if (g_pump_polls != nullptr) {
-    for (auto& it : *g_pump_polls) {
-      uv_poll_stop(&it.second->handle);
-      uv_close(reinterpret_cast<uv_handle_t*>(&it.second->handle), PumpPollCloseCb);
-    }
-    delete g_pump_polls;
-    g_pump_polls = nullptr;
-  }
-  delete g_pump_fds;
-  g_pump_fds = nullptr;
-  if (g_pump_context_acquired) {
-    g_main_context_release(g_main_context_default());
-    g_pump_context_acquired = FALSE;
-  }
+  PumpShutdownPlatform();
+  PumpReleaseContext();
 }
 
+#if NODE_GI_HAS_LIBUV
+
 // startMainLoop() -> void
 // Attach the libuv-backed GSource to the default GLib main context (idempotent).
 // Harmless until a GLib main loop actually runs — it adds no uv handle, so it
@@ -892,4 +1191,42 @@ Napi::Value StartMainLoop(const Napi::CallbackInfo& info) {
   return env.Undefined();
 }
 
+#elif defined(__ANDROID__)
+
+// startMainLoop() -> void
+// Arm the ALooper-driven GLib pump on the calling thread (idempotent). There is
+// no uv-in-GLib bridge to attach alongside it: NativeScript's V8 host has no
+// libuv loop to co-pump, so the pump is the whole bridge here — which also means
+// a blocking GLib.MainLoop.run() has no co-pump to keep the host alive (see the
+// ALooper half above).
+Napi::Value StartMainLoop(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (g_loop_started) return env.Undefined();
+
+  // The looper of the thread that called in — whichever JS thread that is. The
+  // UI thread always has one, and so does a NativeScript Worker (its Java side
+  // runs Looper.prepare() + Looper.loop() around the runtime, see the host's
+  // WorkerWrapper). A Worker is in fact the better owner for GTK: GTK's Android
+  // glue blocks the UI thread on a default-GMainContext idle (GlibContext
+  // .blockForMain), which only returns if some OTHER thread iterates that
+  // context. A null answer means the host called from a bare pthread that never
+  // prepared a looper, and there is then nothing for GLib to be pumped by.
+  ALooper* looper = ALooper_forThread();
+  if (looper == nullptr) {
+    Napi::Error::New(env,
+                     "no ALooper on this thread: the GLib pump needs a looper-backed "
+                     "thread (call startMainLoop from the JS thread)")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  g_loop_env = env;
+  PumpInit(env, looper);
+
+  g_loop_started = TRUE;
+  return env.Undefined();
+}
+
+#endif  // NODE_GI_HAS_LIBUV / __ANDROID__ (startMainLoop)
+
 }  // namespace nodegi