perf(event-loop): cancellable timer tokens (claim cells + @CriticalNative gate, identified long-timer removal)

Cancelled timers no longer leave stale wakeups. Two tiers by remaining
delay, both preserving exact clear semantics from any thread
(multithreaded JS can schedule and clear on non-looper threads):

- short timers (<32ms): the token carries a native claim cell - a slot
  in a fixed per-loop atomic table indexed by timer id, with the id
  embedded in the cell word so cancellation can never hit a recycled
  cell. clearTimeout is a single native CAS (zero JNI): winning proves
  the token dead everywhere, so the sorted entry is erased outright;
  losing means dispatch owns the token, so a tombstone is left for it.
  EventLoopHandler claims cells through a @CriticalNative CAS (the
  annotation is public API in current SDKs; where ART doesn't apply it
  the method degrades to a plain JNI call with identical semantics)
  before entering the runtime, so a cancelled token dies in Java in
  nanoseconds - without acquiring the isolate Locker, which previously
  let a stale token park the main thread behind a long background JS
  turn. Only the gate retires cells, and cell tokens are never
  removeMessages()ed, so each cell sees exactly one gate pass; a busy
  slot (interval re-arm racing its previous token, or id collision
  beyond 1024 in-flight) just downgrades the token to plain+tombstone.
- long timers (>=32ms, debounce territory): the token carries a Java
  AtomicBoolean peer, claimed in handleMessage. clearTimeout CASes the
  peer and on winning removeMessages()es the queued token: a cleared
  debounce timer produces no wakeup at all. The peer and its Message
  are GC-owned, which makes the removal-vs-in-flight-dequeue race
  harmless - a lost race costs at most one no-op wakeup, never an
  ordering violation. Below the cutoff a stale wakeup lands within two
  frames of the interaction that scheduled it (the app is provably
  awake), so the zero-allocation cell path applies instead.

Only the newest token of an interval is cancellable; older tokens
orphaned by a re-arm keep functioning anonymously through their own
carriers, so token/slot parity holds under the anonymous-dispatch
shuffle. SetTimer now converts a failed token post into a JS exception
instead of unwinding a NativeScriptException through the V8 callback
frame.

Verified on device: ordering probes 100% across all scenarios
(timer FIFO ties, clear-vs-Handler.post in both orders, orphan gap,
triple-clear, clearInterval-from-callback, starvation), and the full
suite (78 suites / 668 specs) green, including new specs for identified
clear, background-thread clear racing dispatch, and interval stop.

Author: edusperoni

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

@@ -154,6 +154,64 @@ describe("event loop ordered tombstones", function () {
     });
 });
 
+// Long (>=32ms) timers carry an identified token whose clear removes the
+// queued wakeup; short timers carry a native claim cell whose clear is a
+// single CAS. Both must keep exact clear semantics under any thread.
+describe("event loop token cancellation", function () {
+    it("cleared identified (long) timeout never fires and later timers are unaffected", function (done) {
+        let fired = false;
+        const t = __ns__setTimeout(() => { fired = true; }, 100);
+        __ns__clearTimeout(t);
+        __ns__setTimeout(() => {
+            expect(fired).toBe(false);
+            done();
+        }, 150);
+    });
+
+    it("background-thread clear racing dispatch neither jumps java posts nor ghost-fires", function (done) {
+        let remaining = 30;
+        (function iter() {
+            const order = [];
+            const handler = new android.os.Handler(android.os.Looper.myLooper());
+            const t1 = __ns__setTimeout(() => order.push("t1"), 0);
+            new java.lang.Thread(new java.lang.Runnable({
+                run() {
+                    __ns__clearTimeout(t1);
+                }
+            })).start();
+            handler.post(new java.lang.Runnable({
+                run: () => order.push("java")
+            }));
+            __ns__setTimeout(() => {
+                order.push("t2");
+                const observed = order.join(">");
+                // t1 either fired before the clear landed (at its own legal
+                // slot, ahead of "java") or never; t2 must never jump "java"
+                expect(observed === "java>t2" || observed === "t1>java>t2").toBe(true);
+                if (--remaining === 0) {
+                    done();
+                } else {
+                    iter();
+                }
+            }, 5);
+        })();
+    });
+
+    it("clearing an identified interval stops it", function (done) {
+        let ticks = 0;
+        const iv = __ns__setInterval(() => {
+            ticks++;
+            if (ticks === 2) {
+                __ns__clearInterval(iv);
+                __ns__setTimeout(() => {
+                    expect(ticks).toBe(2);
+                    done();
+                }, 120);
+            }
+        }, 40);
+    });
+});
+
 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/EventLoop.cpp

@@ -49,6 +49,9 @@ namespace tns {
 jclass EventLoop::EVENT_LOOP_HANDLER_CLASS = nullptr;
 jmethodID EventLoop::EVENT_LOOP_HANDLER_CTOR = nullptr;
 jmethodID EventLoop::EVENT_LOOP_HANDLER_POST = nullptr;
+jmethodID EventLoop::EVENT_LOOP_HANDLER_POST_TOKEN = nullptr;
+jmethodID EventLoop::EVENT_LOOP_HANDLER_POST_IDENTIFIED = nullptr;
+jmethodID EventLoop::EVENT_LOOP_HANDLER_CANCEL_IDENTIFIED = nullptr;
 jmethodID EventLoop::EVENT_LOOP_HANDLER_RELEASE = nullptr;
 
 void EventLoop::BindToCurrentThread() {
@@ -96,7 +99,21 @@ void EventLoop::BindToCurrentThread() {
         assert(EVENT_LOOP_HANDLER_CLASS != nullptr);
         EVENT_LOOP_HANDLER_CTOR = env.GetMethodID(EVENT_LOOP_HANDLER_CLASS, "<init>", "(J)V");
         EVENT_LOOP_HANDLER_POST = env.GetMethodID(EVENT_LOOP_HANDLER_CLASS, "post", "(J)V");
+        EVENT_LOOP_HANDLER_POST_TOKEN =
+                env.GetMethodID(EVENT_LOOP_HANDLER_CLASS, "postToken", "(JII)V");
+        EVENT_LOOP_HANDLER_POST_IDENTIFIED = env.GetMethodID(
+                EVENT_LOOP_HANDLER_CLASS, "postIdentified", "(J)Ljava/lang/Object;");
+        EVENT_LOOP_HANDLER_CANCEL_IDENTIFIED = env.GetMethodID(
+                EVENT_LOOP_HANDLER_CLASS, "cancelIdentified", "(Ljava/lang/Object;)Z");
         EVENT_LOOP_HANDLER_RELEASE = env.GetMethodID(EVENT_LOOP_HANDLER_CLASS, "release", "()V");
+        // the @CriticalNative gate must be bound explicitly (name resolution
+        // doesn't apply to the critical calling convention on older ART)
+        static const JNINativeMethod claimMethod = {
+                const_cast<char*>("nativeClaimToken"), const_cast<char*>("(JJ)Z"),
+                reinterpret_cast<void*>(EventLoop::ClaimTokenCritical)};
+        JNIEnv* rawEnv = env;
+        jint registered = rawEnv->RegisterNatives(EVENT_LOOP_HANDLER_CLASS, &claimMethod, 1);
+        assert(registered == 0);
     }
     JniLocalRef handler(env.NewObject(EVENT_LOOP_HANDLER_CLASS, EVENT_LOOP_HANDLER_CTOR,
                                       reinterpret_cast<jlong>(this)));
@@ -255,17 +272,95 @@ void EventLoop::PostOrderedDelayed(std::function<void()> fn, double delayMs) {
     PostOrderedLocked(Entry{nullptr, std::move(fn), true, false, 0}, delayMs);
 }
 
-void EventLoop::PostOrderedToken(jlong uptimeMillis) {
+uint64_t EventLoop::PostTimerToken(jlong uptimeMillis, int timerId) {
     std::lock_guard<std::mutex> lock(mutex_);
     if (stopped_) {
-        return;
+        return 0;
     }
-    if (handler_ != nullptr) {
-        JEnv env;
-        env.CallVoidMethod(handler_, EVENT_LOOP_HANDLER_POST, uptimeMillis);
-    } else {
+    if (handler_ == nullptr) {
         pendingTokens_.push_back(uptimeMillis);
+        return 0;
+    }
+    uint64_t word = 0;
+    auto& cell = claimCells_[((uint32_t) timerId) & (kClaimCells - 1)];
+    uint64_t expected = 0;
+    uint64_t candidate = (((uint64_t) (uint32_t) timerId) << 2) | kCellActive;
+    if (cell.compare_exchange_strong(expected, candidate, std::memory_order_acq_rel)) {
+        word = candidate;
+    }
+    // a busy slot (previous token of the same interval still in flight, or an
+    // id collision) downgrades this token to plain; clear then uses tombstones
+    JEnv env;
+    env.CallVoidMethod(handler_, EVENT_LOOP_HANDLER_POST_TOKEN, uptimeMillis,
+                       (jint) (word >> 32), (jint) (word & 0xffffffffull));
+    return word;
+}
+
+jobject EventLoop::PostIdentifiedTimerToken(jlong uptimeMillis) {
+    JEnv env;
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (stopped_) {
+        return nullptr;
+    }
+    if (handler_ == nullptr) {
+        pendingTokens_.push_back(uptimeMillis);
+        return nullptr;
+    }
+    JniLocalRef peer(env.CallObjectMethod(handler_, EVENT_LOOP_HANDLER_POST_IDENTIFIED,
+                                          uptimeMillis));
+    if (peer.IsNull()) {
+        return nullptr;
     }
+    return env.NewGlobalRef(peer);
+}
+
+bool EventLoop::CancelClaimCell(uint64_t cellWord) {
+    auto& cell = claimCells_[(cellWord >> 2) & (kClaimCells - 1)];
+    uint64_t expected = cellWord;  // id|ACTIVE
+    return cell.compare_exchange_strong(expected, (cellWord & ~3ull) | kCellCancelled,
+                                        std::memory_order_acq_rel);
+}
+
+bool EventLoop::CancelIdentifiedToken(jobject peer) {
+    JEnv env;
+    bool won = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (!stopped_ && handler_ != nullptr) {
+            won = env.CallBooleanMethod(handler_, EVENT_LOOP_HANDLER_CANCEL_IDENTIFIED, peer) ==
+                  JNI_TRUE;
+        }
+    }
+    env.DeleteGlobalRef(peer);
+    return won;
+}
+
+void EventLoop::ReleaseIdentifiedToken(jobject peer) {
+    JEnv env;
+    env.DeleteGlobalRef(peer);
+}
+
+jboolean EventLoop::ClaimTokenCritical(jlong loopPtr, jlong cellWord) {
+    // @CriticalNative: no JNIEnv, thread stays runnable - a single CAS, no
+    // locks, no allocation, no exceptions. The loop pointer is valid for the
+    // same reason nativeRunTask's is: the handler is released before the loop
+    // is destroyed, and released handlers never reach this gate.
+    auto* loop = reinterpret_cast<EventLoop*>(loopPtr);
+    auto word = (uint64_t) cellWord;
+    auto& cell = loop->claimCells_[(word >> 2) & (kClaimCells - 1)];
+    uint64_t expected = word;  // id|ACTIVE
+    if (cell.compare_exchange_strong(expected, 0, std::memory_order_acq_rel)) {
+        // claimed and retired in one step: proceed to the fat path
+        return JNI_TRUE;
+    }
+    if (expected == ((word & ~3ull) | kCellCancelled)) {
+        // the timer was cleared; retire the cell and drop the token here
+        cell.store(0, std::memory_order_release);
+        return JNI_FALSE;
+    }
+    // defensive: a mismatched word can't occur while this token is in flight
+    // (only the gate retires cells), but the fat path is always safe
+    return JNI_TRUE;
 }
 
 void EventLoop::SetTimerSource(OrderedTaskSource* source) {

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

@@ -3,6 +3,8 @@
 
 #include <jni.h>
 #include <android/looper.h>
+#include <atomic>
+#include <cstdint>
 #include <deque>
 #include <functional>
 #include <map>
@@ -97,8 +99,48 @@ class EventLoop {
      * OrderedTaskSource keeps in its own bookkeeping (Timers). One token per
      * item; the drain picks the earliest due item across the source and the
      * ordered entries, so the token needn't name what it will run.
+     *
+     * The token carries a claim cell when one is free for `timerId` (returns
+     * the non-zero cell word to cancel with): EventLoopHandler claims the
+     * cell through a @CriticalNative CAS before entering the runtime, so a
+     * token whose timer was cancelled dies in Java without acquiring the
+     * isolate Locker, and CancelClaimCell neutralizes a queued token with no
+     * JNI at all. Returns 0 when the token is plain (cell slot busy, or the
+     * loop is unbound/stopped) - the caller must then use tombstones.
      */
-    void PostOrderedToken(jlong uptimeMillis);
+    uint64_t PostTimerToken(jlong uptimeMillis, int timerId);
+
+    /**
+     * Posts an ordered token carrying a Java AtomicBoolean claim peer, for
+     * timers long enough that the stale wakeup itself is worth removing.
+     * Returns a global ref to the peer (null when unbound/stopped - caller
+     * falls back to tombstones). CancelIdentifiedToken later CASes the peer
+     * and, on winning, removeMessages()es the queued token: a cleared long
+     * timer produces no wakeup. The peer and its Message are GC-owned, which
+     * is what makes the remove-vs-in-flight-dispatch race harmless.
+     */
+    jobject PostIdentifiedTimerToken(jlong uptimeMillis);
+
+    /**
+     * Neutralizes a cell-carrying token (no JNI, single CAS). True = the
+     * token is guaranteed dead wherever it is, so the caller may delete the
+     * item outright; false = dispatch already claimed it, so the caller must
+     * leave a tombstone for it to consume.
+     */
+    bool CancelClaimCell(uint64_t cellWord);
+
+    /**
+     * Neutralizes an identified token (one JNI crossing; releases the peer
+     * ref). Same true/false contract as CancelClaimCell.
+     */
+    bool CancelIdentifiedToken(jobject peer);
+
+    /**
+     * Releases an identified token's peer ref without cancelling (the timer
+     * fired or is being torn down; the Java Message keeps the peer alive for
+     * its own dispatch).
+     */
+    void ReleaseIdentifiedToken(jobject peer);
 
     /**
      * Registers the ordered lane's external source. Home thread only; pass
@@ -193,10 +235,35 @@ class EventLoop {
     static int EventFdCallback(int fd, int events, void* data);
     static int TimerFdCallback(int fd, int events, void* data);
 
+    /**
+     * Claim cells for cell-carrying timer tokens, indexed by timer id. A cell
+     * word is (id << 2) | state so a token can prove the cell is still its
+     * own; a busy slot (>kClaimCells timers in flight, or an interval's
+     * previous token still pending) just downgrades the new token to plain.
+     * Lifecycle: 0 (free) -> id|ACTIVE (posted, under mutex_) ->
+     * id|CANCELLED (by CancelClaimCell, any thread) -> 0 (retired by the
+     * dispatch gate, which runs exactly once per cell token since cell tokens
+     * are never removeMessages()ed). Only the gate stores 0, so a cell is
+     * never reused while its token is in flight, and cancellation can never
+     * hit a recycled cell.
+     */
+    static constexpr int kClaimCells = 1024;
+    static constexpr uint64_t kCellActive = 1;
+    static constexpr uint64_t kCellCancelled = 2;
+
+    /**
+     * The @CriticalNative body behind EventLoopHandler.nativeClaimToken: one
+     * CAS, no JNIEnv, and the thread stays runnable - it must never block,
+     * allocate or throw. Returns false when the token's timer was cancelled
+     * (token dies in Java); true otherwise (proceed to nativeRunTask).
+     */
+    static jboolean ClaimTokenCritical(jlong loopPtr, jlong cellWord);
+
     v8::Isolate* isolate_;
     std::mutex mutex_;
     Lane internal_;
     Lane ordered_;
+    std::atomic<uint64_t> claimCells_[kClaimCells] = {};
     // ordered-lane source with its own bookkeeping (Timers); home-thread only
     OrderedTaskSource* timerSource_ = nullptr;
     // bare ordered tokens posted before the bind; flushed by Bind
@@ -215,6 +282,9 @@ class EventLoop {
     static jclass EVENT_LOOP_HANDLER_CLASS;
     static jmethodID EVENT_LOOP_HANDLER_CTOR;
     static jmethodID EVENT_LOOP_HANDLER_POST;
+    static jmethodID EVENT_LOOP_HANDLER_POST_TOKEN;
+    static jmethodID EVENT_LOOP_HANDLER_POST_IDENTIFIED;
+    static jmethodID EVENT_LOOP_HANDLER_CANCEL_IDENTIFIED;
     static jmethodID EVENT_LOOP_HANDLER_RELEASE;
 };