feat: put frame callbacks on the performance timeline

__postFrameCallback now hands its callback two arguments,
(frameTimeNanos, performanceMillis). The first is unchanged -- the
platform's raw CLOCK_MONOTONIC frame time, which shipped app code divides
by 1e6 -- and the second is that same instant on the isolate's performance
timeline, so it compares directly with performance.now(). Choreographer
stamps frames on the clock the time origin is captured on, so the
conversion (Performance::MonotonicNanosToTimelineMillis, subtracting the
new Runtime::TimeOriginMonotonicMillis) is exact rather than a resampling.

The machinery moves out of CallbackHandlers into FrameCallbacks.{h,cpp},
which now covers the whole minSdk range: AChoreographer only exists from
API 24, so below it __postFrameCallback silently never fired. API 21-23 now
goes through android.view.Choreographer via com.tns.FrameCallbacks, holding
the same entry and producing the same two arguments. Entries are stored
behind unique_ptr so both implementations can hand the platform a stable
pointer, isolate teardown no longer erases while iterating, and the frame
time from the pre-API-29 AChoreographer entry point is widened to 64 bits,
which it is not on the 32-bit ABIs.

Debug runtimes expose __setFrameCallbackImpl so the Java bridge is
selectable on a modern device; both implementations are covered by specs.

Author: edusperoni

docs/performance.md

@@ -47,12 +47,39 @@ file runs unchanged on both runtimes and should be kept in sync with iOS's
 copy.
 
 The native clock is owned by `Runtime` (`Runtime::PerformanceNowMillis()`,
-`Runtime::TimeOriginMillis()`, captured in `Runtime::PrepareV8Runtime`) and
-exposed to native callers through `tns::Performance::NowMillis(isolate)`
-(`test-app/runtime/src/main/cpp/Performance.h`). Any future native producer of
-JS-visible timestamps — `requestAnimationFrame` in particular — must read the
-clock through that hook rather than sampling its own, so every timestamp
-shares `performance.timeOrigin` as its base.
+`Runtime::TimeOriginMillis()`, `Runtime::TimeOriginMonotonicMillis()`,
+captured in `Runtime::PrepareV8Runtime`) and exposed to native callers through
+`tns::Performance::NowMillis(isolate)`
+(`test-app/runtime/src/main/cpp/Performance.h`). Any native producer of
+JS-visible timestamps must read the clock through that hook rather than
+sampling its own, so every timestamp shares `performance.timeOrigin` as its
+base.
+
+## Frame callbacks
+
+`__postFrameCallback(fn[, delayMillis])` / `__removeFrameCallback(fn)`
+(`test-app/runtime/src/main/cpp/FrameCallbacks.h`) schedule `fn` for the next
+display frame. `fn` receives **two** arguments:
+
+```js
+__postFrameCallback((frameTimeNanos, performanceMillis) => { … });
+```
+
+- `frameTimeNanos` — the platform's raw frame time: `CLOCK_MONOTONIC`
+  nanoseconds, the `System.nanoTime()` base. Unchanged from earlier runtimes,
+  which passed it as the only argument.
+- `performanceMillis` — the same instant on this isolate's performance
+  timeline, so it compares directly with `performance.now()`. Converted
+  natively through `Performance::MonotonicNanosToTimelineMillis()`, which
+  subtracts `Runtime::TimeOriginMonotonicMillis()` — Choreographer stamps
+  frames on the very clock the time origin is captured on, so the mapping is
+  exact rather than an approximation resampled in JS.
+
+Two implementations sit behind that one surface: the NDK's `AChoreographer`
+(API 24+, resolved with `dlsym`) and `android.view.Choreographer` through
+`com.tns.FrameCallbacks` for API 21–23, where the NDK API does not exist.
+Scheduling is per calling thread, so a worker schedules against its own looper.
+Both paths produce the same two arguments with the same exactness.
 
 ## Deviations from the specs
 

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

@@ -140,3 +140,90 @@ describe("test PostFrameCallback", function () {
     }, defaultWaitTime);
   });
 });
+
+// The two implementations behind __postFrameCallback (NDK AChoreographer,
+// android.view.Choreographer for API < 24) must be indistinguishable from JS.
+// A modern device always selects the NDK one, so the Java bridge is only
+// reachable through __setFrameCallbackImpl, which debug runtimes expose for
+// exactly this.
+describe("frame callback timestamps", function () {
+  const defaultWaitTime = 300;
+  const impls = ["native", "java"];
+
+  afterEach(() => {
+    if (typeof global.__setFrameCallbackImpl === "function") {
+      global.__setFrameCallbackImpl("auto");
+    }
+  });
+
+  function withImpl(impl) {
+    if (typeof global.__setFrameCallbackImpl !== "function") {
+      return impl === "native";
+    }
+    return global.__setFrameCallbackImpl(impl) === impl;
+  }
+
+  impls.forEach((impl) => {
+    describe(impl + " implementation", function () {
+      it("passes the raw frame time and a performance-timeline timestamp", (done) => {
+        if (!withImpl(impl)) {
+          pending("this runtime cannot select the " + impl + " implementation");
+          return;
+        }
+
+        global.__postFrameCallback((frameTimeNanos, performanceMillis) => {
+          const now = performance.now();
+
+          expect(typeof frameTimeNanos).toBe("number");
+          expect(typeof performanceMillis).toBe("number");
+
+          // Uptime-scale nanoseconds, not epoch-scale milliseconds.
+          expect(frameTimeNanos).toBeGreaterThan(1e9);
+          expect(frameTimeNanos / 1e6).toBeLessThan(Date.now());
+
+          // The frame is stamped just before the callback runs, so its
+          // timeline position sits a frame or two behind the reading taken
+          // inside it, never ahead of it.
+          expect(performanceMillis).toBeGreaterThan(0);
+          expect(performanceMillis).not.toBeGreaterThan(now);
+          expect(now - performanceMillis).toBeLessThan(250);
+
+          // Both arguments describe the same instant, so their difference is
+          // the timeline's monotonic origin. System.nanoTime() is on that same
+          // clock, so the pair (nanoTime, now) must yield the same origin --
+          // this is what would break if either argument moved off the base.
+          const originFromFrame = frameTimeNanos / 1e6 - performanceMillis;
+          const originFromClock = java.lang.System.nanoTime() / 1e6 - performance.now();
+          expect(Math.abs(originFromFrame - originFromClock)).toBeLessThan(5);
+          done();
+        });
+      });
+
+      it("advances across consecutive frames", (done) => {
+        if (!withImpl(impl)) {
+          pending("this runtime cannot select the " + impl + " implementation");
+          return;
+        }
+
+        const frames = [];
+        const callback = (frameTimeNanos, performanceMillis) => {
+          frames.push({ nanos: frameTimeNanos, millis: performanceMillis });
+          if (frames.length === 1) {
+            global.__postFrameCallback(callback);
+          }
+        };
+        global.__postFrameCallback(callback);
+
+        setTimeout(() => {
+          expect(frames.length).toBe(2);
+          expect(frames[1].nanos).not.toBeLessThan(frames[0].nanos);
+          expect(frames[1].millis).not.toBeLessThan(frames[0].millis);
+          // The origin the two arguments imply is a constant of the isolate.
+          const origin = (f) => f.nanos / 1e6 - f.millis;
+          expect(Math.abs(origin(frames[1]) - origin(frames[0]))).toBeLessThan(1);
+          done();
+        }, defaultWaitTime);
+      });
+    });
+  });
+});

test-app/runtime/CMakeLists.txt

@@ -152,6 +152,7 @@ add_library(
         src/main/cpp/Constants.cpp
         src/main/cpp/DirectBuffer.cpp
         src/main/cpp/ErrorEvents.cpp
+        src/main/cpp/FrameCallbacks.cpp
         src/main/cpp/Events.cpp
         src/main/cpp/FieldAccessor.cpp
         src/main/cpp/File.cpp

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

@@ -1573,173 +1573,11 @@ void CallbackHandlers::RemoveIsolateEntries(v8::Isolate *isolate) {
             cache_.erase(item.first);
         }
     }
-
-    for (auto &item: frameCallbackCache_) {
-        if (item.second.isolate_ == isolate) {
-            frameCallbackCache_.erase(item.first);
-        }
-    }
-
-}
-CallbackHandlers::func_AChoreographer_getInstance AChoreographer_getInstance_;
-
-CallbackHandlers::func_AChoreographer_postFrameCallback AChoreographer_postFrameCallback_;
-CallbackHandlers::func_AChoreographer_postFrameCallbackDelayed AChoreographer_postFrameCallbackDelayed_;
-
-CallbackHandlers::func_AChoreographer_postFrameCallback64 AChoreographer_postFrameCallback64_;
-CallbackHandlers::func_AChoreographer_postFrameCallbackDelayed64 AChoreographer_postFrameCallbackDelayed64_;
-
-void CallbackHandlers::PostCallback(const FunctionCallbackInfo<v8::Value> &args, CallbackHandlers::FrameCallbackCacheEntry* entry, v8::Local<v8::Context> context){
-    ALooper_prepare(0);
-    auto instance = AChoreographer_getInstance_();
-    auto delay = args[1];
-    if(android_get_device_api_level() >= 29){
-        if(!delay.IsEmpty() && delay->IsNumber()){
-            AChoreographer_postFrameCallbackDelayed64_(instance, entry->frameCallback64_, entry, delay->Uint32Value(context).FromMaybe(0));
-        }else {
-            AChoreographer_postFrameCallback64_(instance, entry->frameCallback64_, entry);
-        }
-    }else {
-        if(!delay.IsEmpty() && delay->IsNumber()){
-            AChoreographer_postFrameCallbackDelayed_(instance, entry->frameCallback_, entry, (long)delay->IntegerValue(context).FromMaybe(0));
-        }else {
-            AChoreographer_postFrameCallback_(instance, entry->frameCallback_, entry);
-        }
-    }
-}
-
-
-void CallbackHandlers::PostFrameCallback(const FunctionCallbackInfo<v8::Value> &args) {
-    if (android_get_device_api_level() >= 24) {
-        InitChoreographer();
-        Isolate *isolate = args.GetIsolate();
-
-        v8::Locker locker(isolate);
-        Isolate::Scope isolate_scope(isolate);
-        HandleScope handle_scope(isolate);
-        auto context = isolate->GetCurrentContext();
-        Context::Scope context_scope(context);
-
-        if (args.Length() < 1 || !args[0]->IsFunction()) {
-            isolate->ThrowException(v8::Exception::TypeError(v8::String::NewFromUtf8Literal(isolate, "Frame callback argument is not a function")));
-            return;
-        }
-
-        auto func = args[0].As<Function>();
-
-        auto idKey = ArgConverter::ConvertToV8String(isolate, "_postFrameCallbackId");
-
-        Local<Value> pId;
-        bool success = V8GetPrivateValue(isolate, func, idKey, pId);
-
-        if (success && pId->IsNumber()){
-            auto id = pId->IntegerValue(context).FromMaybe(0);
-            auto cb = frameCallbackCache_.find(id);
-            if (cb != frameCallbackCache_.end()) {
-                // check if it's already scheduled first, we don't want to schedule it twice
-                bool shouldReschedule = !cb->second.isScheduled();
-                // always mark as scheduled, as that will also mark it as not removed anymore
-                cb->second.markScheduled();
-                if (shouldReschedule) {
-                    PostCallback(args, &cb->second, context);
-                }
-                return;
-            }
-        }
-
-        Local<v8::Function> callback = func;
-        uint64_t key = ++frameCallbackCount_;
-
-        V8SetPrivateValue(isolate, func, idKey, v8::Number::New(isolate, (double) key));
-
-        robin_hood::unordered_map<uint64_t, FrameCallbackCacheEntry>::iterator val;
-        bool inserted;
-        std::tie(val, inserted) = frameCallbackCache_.try_emplace(key, isolate, callback, key);
-        assert(inserted && "Frame callback ID should not be duplicated");
-
-        val->second.markScheduled();
-        PostCallback(args, &val->second, context);
-    }
-}
-
-void CallbackHandlers::RemoveFrameCallback(const FunctionCallbackInfo<v8::Value> &args) {
-
-    if (android_get_device_api_level() >= 24) {
-        InitChoreographer();
-        Isolate *isolate = args.GetIsolate();
-        v8::Locker locker(isolate);
-        Isolate::Scope isolate_scope(isolate);
-        HandleScope handle_scope(isolate);
-        auto context = isolate->GetCurrentContext();
-        Context::Scope context_scope(context);
-
-        if (args.Length() < 1 || !args[0]->IsFunction()) {
-            isolate->ThrowException(v8::Exception::TypeError(v8::String::NewFromUtf8Literal(isolate, "Frame callback argument is not a function")));
-            return;
-        }
-        auto func = args[0].As<Function>();
-
-        auto idKey = ArgConverter::ConvertToV8String(isolate, "_postFrameCallbackId");
-
-        Local<Value> pId;
-        bool success = V8GetPrivateValue(isolate, func, idKey, pId);
-
-        if (success && pId->IsNumber()){
-            auto id = pId->IntegerValue(context).FromMaybe(0);
-            auto cb = frameCallbackCache_.find(id);
-            if (cb != frameCallbackCache_.end()) {
-                cb->second.markRemoved();
-            }
-        }
-
-    }
-
 }
-
-void CallbackHandlers::InitChoreographer() {
-    if(AChoreographer_getInstance_ == nullptr){
-        void* lib = dlopen("libandroid.so", RTLD_NOW | RTLD_LOCAL);
-        if (lib != nullptr) {
-
-            // Retrieve function pointers from shared object.
-            AChoreographer_getInstance_ =
-                    reinterpret_cast<func_AChoreographer_getInstance>(
-                            dlsym(lib, "AChoreographer_getInstance"));
-            AChoreographer_postFrameCallback_ =
-                    reinterpret_cast<func_AChoreographer_postFrameCallback>(
-                            dlsym(lib, "AChoreographer_postFrameCallback"));
-
-            AChoreographer_postFrameCallbackDelayed_ =
-                    reinterpret_cast<func_AChoreographer_postFrameCallbackDelayed>(
-                            dlsym(lib, "AChoreographer_postFrameCallbackDelayed"));
-
-            assert(AChoreographer_getInstance_);
-            assert(AChoreographer_postFrameCallback_);
-            assert(AChoreographer_postFrameCallbackDelayed_);
-
-            if(android_get_device_api_level() >= 29){
-                AChoreographer_postFrameCallback64_ =
-                        reinterpret_cast<func_AChoreographer_postFrameCallback64>(
-                                dlsym(lib, "AChoreographer_postFrameCallback64"));
-
-                AChoreographer_postFrameCallbackDelayed64_ =
-                        reinterpret_cast<func_AChoreographer_postFrameCallbackDelayed64>(
-                                dlsym(lib, "AChoreographer_postFrameCallbackDelayed64"));
-
-                assert(AChoreographer_postFrameCallback64_);
-                assert(AChoreographer_postFrameCallbackDelayed64_);
-            }
-        }
-    }
-}
-
-
 robin_hood::unordered_map<uint64_t, CallbackHandlers::CacheEntry> CallbackHandlers::cache_;
 
-robin_hood::unordered_map<uint64_t, CallbackHandlers::FrameCallbackCacheEntry> CallbackHandlers::frameCallbackCache_;
 
 std::atomic_int64_t CallbackHandlers::count_ = {0};
-std::atomic_uint64_t CallbackHandlers::frameCallbackCount_ = {0};
 
 
 short CallbackHandlers::MAX_JAVA_STRING_ARRAY_LENGTH = 100;