feat(event-loop): merge timers into the ordered lane; route __runOnMainThread through the internal lane

Timers merge (with tombstones):

- Timers no longer owns a Java Handler: each scheduled timer posts one
  anonymous token through the EventLoop's ordered lane, and the token
  drain runs the earliest due item across timers and ordered macrotasks
  - one due-ordered domain, still strictly FIFO with Handler.post on
  the same looper. Token 'when' computation is unchanged, so the
  quiescent setTimeout-vs-Handler.post contract is preserved exactly.
- clearTimeout/clearInterval tombstone the sorted entry instead of
  erasing it: the cleared timer's already-queued token consumes its own
  slot as a no-op, so no token gains surplus capacity to run a
  later-scheduled item (timer or macrotask) ahead of foreign Java
  messages queued between the two token positions. This also fixes the
  pre-existing congestion deviation where a leftover token could fire a
  later timer early.
- FireTimer's internals (sub-ms sorted list, chromium-style interval
  catch-up, nesting clamp, TryCatch discipline) are untouched; the
  check-and-run happens in one OrderedTaskSource::RunIfEarliest call
  under a single Locker acquisition, because background threads mutate
  the timer bookkeeping through setTimeout under multithreaded JS.
- TimerHandler.java is deleted.

__runOnMainThread promotion:

- The 2MB main-looper pipe and RunOnMainThreadFdCallback are replaced
  by bare internal-lane entries on the main runtime's EventLoop. Bare
  entries skip the loop's Locker/checkpoint: the closure locks the
  CALLER's isolate (a worker's, under multithreaded JS), and taking the
  main isolate's Locker first would nest Lockers across isolates and
  can deadlock against worker->main JNI entry paths. Delivery stays
  one-per-poll, matching the old fd callback.
- The callback cache is now mutex-guarded: it was written from
  arbitrary threads under different isolates' Lockers, which provide no
  mutual exclusion; RemoveIsolateEntries also no longer erases while
  range-iterating.
- Uncaught exceptions in the callbacks now surface as pending Java
  exceptions via the loop's guard instead of unwinding C++ through the
  ALooper callback frame.

Tests: tombstone ordering specs (cleared timer's token vs java posts,
for both a later timer and a queued macrotask), against the native
__ns__ timers - the test app's global setTimeout is an old
Handler-based polyfill with colliding ids, not the runtime timers.

Author: edusperoni

test-app/app/src/main/assets/app/tests/testEventLoop.js

@@ -86,10 +86,12 @@ describe("event loop ordered macrotasks", function () {
         Promise.resolve().then(() => order.push("microtask"));
     });
 
-    it("stays FIFO-ordered with setTimeout(0)", function (done) {
+    // native timers (__ns__*): the app-level `setTimeout` global in this test
+    // app is an old Handler-based polyfill, not the runtime timers
+    it("stays FIFO-ordered with native setTimeout(0)", function (done) {
         const order = [];
         __ns__queueMacrotask(() => order.push("macro1"));
-        setTimeout(() => order.push("timeout"), 0);
+        __ns__setTimeout(() => order.push("timeout"), 0);
         __ns__queueMacrotask(() => {
             order.push("macro2");
             expect(order).toEqual(["macro1", "timeout", "macro2"]);
@@ -116,6 +118,42 @@ describe("event loop ordered macrotasks", function () {
     });
 });
 
+// clearTimeout leaves a tombstone in the merged ordered domain, so the
+// cleared timer's already-queued token consumes its own slot as a no-op
+// instead of running a later-scheduled item ahead of Java messages queued
+// between the two tokens' positions.
+describe("event loop ordered tombstones", function () {
+    it("cleared timeout's token does not run a later timer ahead of java posts", function (done) {
+        const order = [];
+        const handler = new android.os.Handler(android.os.Looper.myLooper());
+        const t1 = __ns__setTimeout(() => order.push("cleared"), 0);
+        __ns__clearTimeout(t1);
+        handler.post(new java.lang.Runnable({
+            run: () => order.push("java")
+        }));
+        __ns__setTimeout(() => {
+            order.push("t2");
+            expect(order).toEqual(["java", "t2"]);
+            done();
+        }, 0);
+    });
+
+    it("cleared timeout's token does not run a queued macrotask ahead of java posts", function (done) {
+        const order = [];
+        const handler = new android.os.Handler(android.os.Looper.myLooper());
+        const t1 = __ns__setTimeout(() => order.push("cleared"), 0);
+        __ns__clearTimeout(t1);
+        handler.post(new java.lang.Runnable({
+            run: () => order.push("java")
+        }));
+        __ns__queueMacrotask(() => {
+            order.push("macro");
+            expect(order).toEqual(["java", "macro"]);
+            done();
+        });
+    });
+});
+
 describe("event loop internal lane", function () {
     // Regression for the eventfd unit-accounting bug: a worker reply's wakeup
     // arriving while an overdue waitAsync timeout is still unsignaled must not

test-app/runtime/src/main/cpp/CallbackHandlers.cpp

@@ -684,48 +684,60 @@ void CallbackHandlers::RunOnMainThreadCallback(const FunctionCallbackInfo<v8::Va
     uint64_t key = ++count_;
     Local<v8::Function> callback = args[0].As<v8::Function>();
 
-    bool inserted;
-    std::tie(std::ignore, inserted) = cache_.try_emplace(key, isolate, callback);
-    assert(inserted && "Main thread callback ID should not be duplicated");
+    {
+        std::lock_guard<std::mutex> lock(cacheMutex_);
+        bool inserted;
+        std::tie(std::ignore, inserted) = cache_.try_emplace(key, isolate, callback);
+        assert(inserted && "Main thread callback ID should not be duplicated");
+    }
 
-    auto value = Callback(key);
-    auto size = sizeof(Callback);
-    auto wrote = write(Runtime::GetWriter(),&value , size);
+    auto mainLoop = Runtime::GetMainEventLoop();
+    if (mainLoop == nullptr) {
+        return;
+    }
+    // bare entry: the closure locks the CALLER's isolate (possibly a
+    // worker's), so the loop must not take the main isolate's Locker first -
+    // nesting the two can deadlock against multithreaded-JS entry paths
+    mainLoop->PostInternalBare([key]() { RunMainThreadEntry(key); });
 }
 
-int CallbackHandlers::RunOnMainThreadFdCallback(int fd, int events, void *data) {
-    struct Callback value;
-    auto size = sizeof(Callback);
-    ssize_t nr = read(fd, &value, sizeof(value));
-
-    auto key = value.id_;
-
-    auto it = cache_.find(key);
-    if (it == cache_.end()) {
-        return 1;
+void CallbackHandlers::RunMainThreadEntry(uint64_t key) {
+    Isolate *isolate;
+    {
+        std::lock_guard<std::mutex> lock(cacheMutex_);
+        auto it = cache_.find(key);
+        if (it == cache_.end()) {
+            return;
+        }
+        isolate = it->second.isolate_;
     }
 
-    Isolate *isolate = it->second.isolate_;
     v8::Locker locker(isolate);
     Isolate::Scope isolate_scope(isolate);
     HandleScope handle_scope(isolate);
-    Local<v8::Function> cb = it->second.callback_.Get(isolate);
+    Local<v8::Function> cb;
+    {
+        std::lock_guard<std::mutex> lock(cacheMutex_);
+        auto it = cache_.find(key);
+        if (it == cache_.end()) {
+            return;
+        }
+        cb = it->second.callback_.Get(isolate);
+        cache_.erase(it);
+    }
     Runtime* runtime = Runtime::GetRuntime(isolate);
     v8::Local<v8::Context> context = runtime->GetContext();
     Context::Scope context_scope(context);
-    // erase the it here as we're already done with its values and the callback might invalidate the iterator
-    cache_.erase(it);
 
     v8::TryCatch tc(isolate);
 
     cb->Call(context, context->Global(), 0, nullptr);  // ignore JS return value
 
     if (tc.HasCaught() &&
         !NativeScriptException::ContainUncaughtCallbackException(isolate, tc)) {
+        // surfaces via the event loop's guard as a pending Java exception
         throw NativeScriptException(tc);
     }
-
-    return 1;
 }
 
 void CallbackHandlers::LogMethodCallback(const v8::FunctionCallbackInfo<v8::Value> &args) {
@@ -1611,13 +1623,19 @@ void CallbackHandlers::CallWorkerScopeOnErrorHandle(Isolate *isolate, TryCatch &
 }
 
 void CallbackHandlers::RemoveIsolateEntries(v8::Isolate *isolate) {
-    for (auto &item: cache_) {
-        if (item.second.isolate_ == isolate) {
-            cache_.erase(item.first);
+    {
+        std::lock_guard<std::mutex> lock(cacheMutex_);
+        for (auto it = cache_.begin(); it != cache_.end();) {
+            if (it->second.isolate_ == isolate) {
+                it = cache_.erase(it);
+            } else {
+                ++it;
+            }
         }
     }
 }
 robin_hood::unordered_map<uint64_t, CallbackHandlers::CacheEntry> CallbackHandlers::cache_;
+std::mutex CallbackHandlers::cacheMutex_;
 
 
 std::atomic_int64_t CallbackHandlers::count_ = {0};

test-app/runtime/src/main/cpp/CallbackHandlers.h

@@ -3,6 +3,7 @@
 
 #include <string>
 #include <map>
+#include <mutex>
 #include <vector>
 #include "JEnv.h"
 #include "ArgsWrapper.h"
@@ -73,7 +74,9 @@ namespace tns {
 
         static void RunOnMainThreadCallback(const v8::FunctionCallbackInfo<v8::Value> &args);
 
-        static int RunOnMainThreadFdCallback(int fd, int events, void* data);
+        // runs one cached __runOnMainThread callback on the main thread,
+        // entering the CALLER's isolate (posted as a bare event-loop entry)
+        static void RunMainThreadEntry(uint64_t key);
 
         static void LogMethodCallback(const v8::FunctionCallbackInfo<v8::Value> &args);
 
@@ -241,6 +244,10 @@ namespace tns {
         };
 
         static robin_hood::unordered_map<uint64_t, CacheEntry> cache_;
+        // guards cache_: __runOnMainThread is callable from any runtime's
+        // thread (multithreaded JS, workers), each under a different
+        // isolate's Locker, so the Lockers provide no mutual exclusion
+        static std::mutex cacheMutex_;
 
 
     };

test-app/runtime/src/main/cpp/EventLoop.cpp

@@ -116,6 +116,10 @@ void EventLoop::BindToCurrentThread() {
     for (auto& pair : ordered_.delayed) {
         env.CallVoidMethod(handler_, EVENT_LOOP_HANDLER_POST, (jlong) std::ceil(pair.first));
     }
+    for (auto when : pendingTokens_) {
+        env.CallVoidMethod(handler_, EVENT_LOOP_HANDLER_POST, when);
+    }
+    pendingTokens_.clear();
 }
 
 void EventLoop::Shutdown() {
@@ -216,39 +220,65 @@ void EventLoop::PostInternal(std::function<void()> fn) {
     if (stopped_) {
         return;
     }
-    PostInternalLocked(Entry{nullptr, std::move(fn), true, 0}, 0);
+    PostInternalLocked(Entry{nullptr, std::move(fn), true, false, 0}, 0);
 }
 
 void EventLoop::PostInternalDelayed(std::function<void()> fn, double delayMs) {
     std::lock_guard<std::mutex> lock(mutex_);
     if (stopped_) {
         return;
     }
-    PostInternalLocked(Entry{nullptr, std::move(fn), true, 0}, delayMs);
+    PostInternalLocked(Entry{nullptr, std::move(fn), true, false, 0}, delayMs);
+}
+
+void EventLoop::PostInternalBare(std::function<void()> fn) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (stopped_) {
+        return;
+    }
+    PostInternalLocked(Entry{nullptr, std::move(fn), true, true, 0}, 0);
 }
 
 void EventLoop::PostOrdered(std::function<void()> fn) {
     std::lock_guard<std::mutex> lock(mutex_);
     if (stopped_) {
         return;
     }
-    PostOrderedLocked(Entry{nullptr, std::move(fn), true, 0}, 0);
+    PostOrderedLocked(Entry{nullptr, std::move(fn), true, false, 0}, 0);
 }
 
 void EventLoop::PostOrderedDelayed(std::function<void()> fn, double delayMs) {
     std::lock_guard<std::mutex> lock(mutex_);
     if (stopped_) {
         return;
     }
-    PostOrderedLocked(Entry{nullptr, std::move(fn), true, 0}, delayMs);
+    PostOrderedLocked(Entry{nullptr, std::move(fn), true, false, 0}, delayMs);
+}
+
+void EventLoop::PostOrderedToken(jlong uptimeMillis) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (stopped_) {
+        return;
+    }
+    if (handler_ != nullptr) {
+        JEnv env;
+        env.CallVoidMethod(handler_, EVENT_LOOP_HANDLER_POST, uptimeMillis);
+    } else {
+        pendingTokens_.push_back(uptimeMillis);
+    }
+}
+
+void EventLoop::SetTimerSource(OrderedTaskSource* source) {
+    // home thread only, like every consumer of timerSource_
+    timerSource_ = source;
 }
 
 void EventLoop::PostV8Task(std::unique_ptr<Task> task, bool nestable, double delaySeconds) {
     std::lock_guard<std::mutex> lock(mutex_);
     if (stopped_) {
         return;
     }
-    PostInternalLocked(Entry{std::move(task), nullptr, nestable, 0},
+    PostInternalLocked(Entry{std::move(task), nullptr, nestable, false, 0},
                        delaySeconds * 1000.0);
 }
 
@@ -288,6 +318,17 @@ std::unique_ptr<EventLoop::Entry> EventLoop::TakeDueLocked(Lane& lane, bool nest
     return nullptr;
 }
 
+double EventLoop::PeekDueLocked(Lane& lane, double now) {
+    // immediate entries are enqueued with monotonically increasing times, so
+    // the front is the earliest
+    double due = lane.immediate.empty() ? -1 : lane.immediate.front().time;
+    if (!lane.delayed.empty() && lane.delayed.begin()->first <= now &&
+        (due < 0 || lane.delayed.begin()->first < due)) {
+        due = lane.delayed.begin()->first;
+    }
+    return due;
+}
+
 void EventLoop::ArmTimerLocked(double now) {
     if (timerFd_ == -1) {
         return;
@@ -313,6 +354,12 @@ void EventLoop::ArmTimerLocked(double now) {
 }
 
 void EventLoop::RunEntry(Entry& entry) {
+    if (entry.bare) {
+        // the fn locks its own (possibly different) isolate; taking this
+        // loop's Locker here would nest Lockers across isolates
+        entry.fn();
+        return;
+    }
     v8::Locker locker(isolate_);
     v8::Isolate::Scope isolate_scope(isolate_);
     v8::HandleScope handleScope(isolate_);
@@ -370,6 +417,27 @@ void EventLoop::RunNestableV8Tasks() {
 }
 
 void EventLoop::RunOrderedTask() {
+    // one anonymous token = one due slot across the whole ordered domain:
+    // pick the earliest due item among the ordered entries and the timer
+    // source, whichever it is. Timers and entries only ever run on this
+    // thread, so the peeked winner can't be taken by anyone else before we
+    // re-lock (a concurrent post can only add later work).
+    auto now = now_ms();
+    double entryDue;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (stopped_) {
+            return;
+        }
+        entryDue = PeekDueLocked(ordered_, now);
+    }
+    if (timerSource_ != nullptr && timerSource_->RunIfEarliest(now, entryDue)) {
+        return;
+    }
+    if (entryDue < 0) {
+        // leftover token: nothing in the domain is due yet
+        return;
+    }
     std::unique_ptr<Entry> entry;
     {
         std::lock_guard<std::mutex> lock(mutex_);
@@ -378,11 +446,9 @@ void EventLoop::RunOrderedTask() {
         }
         entry = TakeDueLocked(ordered_, false, false, false, now_ms());
     }
-    if (entry == nullptr) {
-        // leftover token: the earliest delayed entry isn't due yet
-        return;
+    if (entry != nullptr) {
+        RunEntry(*entry);
     }
-    RunEntry(*entry);
 }
 
 int EventLoop::EventFdCallback(int fd, int events, void* data) {