Introduce frame identifier calculation to the rendering pipeline

Summary:
The earlier attempt to measure frame drops during animations was naive and did not take into account stalls on the background work (bind, resolve, layout) that we do during rendering.

This diff stack attempts to fix that.  There are two parts to this change:

**1. Frame Id (this diff)**
We introduce the concept of a "frame identifier", which is an integer that represents the frame in which the last update was requested.  The frame identifier is held by `RenderState` and updated when a new render is requested.  This frame id is then plumbed through to the pipeline to the point where we commit, so that at the point we commit, we know which update we are committing.  Commit listeners receive this.

**2. Animation perf (next diff)**
Each animation registers a commit listener when started.  This commit listener uses the frameId provided to the commit listener callback to then compute how many frames were lost since the last commit happens.

Differential Revision: D54906022

fbshipit-source-id: 7512e0c9ccd8237d1e7e14c95807203a7c79570c

litho-rendercore-sample/src/main/java/com/facebook/rendercore/sample/SampleActivity.kt

@@ -90,7 +90,7 @@ class SampleActivity : ComponentActivity(), RenderState.Delegate<SampleData?> {
     currentRenderTree = next
   }
 
-  override fun commitToUI(tree: RenderTree?, state: SampleData?) {
+  override fun commitToUI(tree: RenderTree?, state: SampleData?, frameId: Int) {
     currentRenderTree = tree
   }
 }

litho-rendercore-testing/src/main/java/com/facebook/rendercore/testing/RenderCoreTestRule.java

@@ -63,7 +63,7 @@ public void commit(
             Object nextState) {}
 
         @Override
-        public void commitToUI(RenderTree tree, Object o) {}
+        public void commitToUI(@Nullable RenderTree tree, @Nullable Object o, int frameVersion) {}
       };
 
   private Context context;

litho-rendercore-testing/src/main/java/com/facebook/rendercore/testing/RendercoreTestDriver.java

@@ -147,7 +147,8 @@ public void commit(
                     Object nextState) {}
 
                 @Override
-                public void commitToUI(RenderTree tree, Object o) {}
+                public void commitToUI(
+                    @Nullable RenderTree tree, @Nullable Object o, int frameVersion) {}
               },
               null,
               null);

litho-rendercore/src/main/java/com/facebook/rendercore/LayoutFuture.kt

@@ -26,6 +26,7 @@ class LayoutFuture<State, RenderContext>(
     val tree: Node<RenderContext>,
     state: State?,
     val version: Int,
+    val frameId: Int,
     previousResult: RenderResult<State, RenderContext>?,
     extensions: Array<RenderCoreExtension<*, *>>?,
     val sizeConstraints: SizeConstraints

litho-rendercore/src/main/java/com/facebook/rendercore/RenderState.kt

@@ -24,10 +24,12 @@ import com.facebook.infer.annotation.ThreadConfined
 import com.facebook.rendercore.StateUpdateReceiver.StateUpdate
 import com.facebook.rendercore.extensions.RenderCoreExtension
 import com.facebook.rendercore.utils.ThreadUtils
+import com.facebook.rendercore.utils.VSyncUtils
 import java.util.Objects
 import java.util.concurrent.Executor
 import java.util.concurrent.atomic.AtomicInteger
 import javax.annotation.concurrent.ThreadSafe
+import kotlin.math.roundToInt
 
 /** todo: javadocs * */
 class RenderState<State, RenderContext, StateUpdateType : StateUpdate<*>>
@@ -75,7 +77,7 @@ constructor(
         nextState: State?
     )
 
-    fun commitToUI(tree: RenderTree?, state: State?)
+    fun commitToUI(tree: RenderTree?, state: State?, frameVersion: Int)
   }
 
   fun interface HostListener {
@@ -94,14 +96,20 @@ constructor(
   private var latestResolveFunc: ResolveFunc<State, RenderContext, StateUpdateType>? = null
   private var resolveFuture: ResolveFuture<State, RenderContext, StateUpdateType>? = null
   private var layoutFuture: LayoutFuture<State, RenderContext>? = null
+  private var resolveVersionCounter = 0
+  private var committedResolveVersion = UNSET
   private var committedResolvedTree: Node<RenderContext>? = null
   private var committedState: State? = null
+  private var committedResolvedFrameId = UNSET
   private val pendingStateUpdates: MutableList<StateUpdateType> = ArrayList()
   private var committedRenderResult: RenderResult<State, RenderContext>? = null
-  private var resolveVersionCounter = 0
+
+  private val normalVSyncTime = VSyncUtils.getNormalVsyncTime(context)
+  private val frameReferenceTimeNanos = System.nanoTime()
+
   private var layoutVersionCounter = 0
-  private var committedResolveVersion = UNSET
   private var committedLayoutVersion = UNSET
+  private var committedLayoutFrameId = UNSET
   private var sizeConstraints: SizeConstraints = SizeConstraints()
   private var hasSizeConstraints = false
   private val resolveToken = Any()
@@ -140,6 +148,11 @@ constructor(
     uiHandler.postAtTime({ requestResolve(null, async) }, resolveToken, 0)
   }
 
+  private fun getElapsedFrameCount(): Int {
+    val elapsedTimeNanos = System.nanoTime() - frameReferenceTimeNanos
+    return (elapsedTimeNanos * 1.0 / normalVSyncTime).roundToInt()
+  }
+
   private fun requestResolve(
       resolveFunc: ResolveFunc<State, RenderContext, StateUpdateType>?,
       doAsync: Boolean,
@@ -151,6 +164,7 @@ constructor(
       if (resolveFunc == null && pendingStateUpdates.isEmpty()) {
         return
       }
+
       if (resolveFunc != null) {
         latestResolveFunc = resolveFunc
       }
@@ -161,7 +175,8 @@ constructor(
               committedResolvedTree,
               committedState,
               if (pendingStateUpdates.isEmpty()) emptyList() else ArrayList(pendingStateUpdates),
-              resolveVersionCounter++)
+              resolveVersionCounter++,
+              getElapsedFrameCount())
       resolveFuture = future
     }
     if (doAsync) {
@@ -193,6 +208,7 @@ constructor(
     if (future.version > committedResolveVersion) {
       committedResolveVersion = future.version
       committedResolvedTree = result.resolvedNode
+      committedResolvedFrameId = future.frameId
       committedState = result.resolvedState
       pendingStateUpdates.removeAll(future.stateUpdatesToApply)
       didCommit = true
@@ -223,6 +239,7 @@ constructor(
                 commitedTree,
                 committedState,
                 layoutVersionCounter++,
+                committedResolvedFrameId,
                 committedRenderResult,
                 extensions,
                 sizeConstraints)
@@ -238,6 +255,7 @@ constructor(
           committedRenderResult != renderResult) {
         committedLayoutVersion = layoutFuture.version
         committedNewLayout = true
+        committedLayoutFrameId = layoutFuture.frameId
         committedRenderResult = renderResult
       }
       if (this.layoutFuture == layoutFuture) {
@@ -340,7 +358,8 @@ constructor(
   @ThreadConfined(ThreadConfined.UI)
   private fun maybePromoteCommittedTreeToUI() {
     synchronized(this) {
-      delegate.commitToUI(committedRenderResult?.renderTree, committedRenderResult?.state)
+      delegate.commitToUI(
+          committedRenderResult?.renderTree, committedRenderResult?.state, committedLayoutFrameId)
       if (uiRenderTree == committedRenderResult?.renderTree) {
         return
       }

litho-rendercore/src/main/java/com/facebook/rendercore/ResolveFuture.kt

@@ -26,7 +26,8 @@ class ResolveFuture<State, RenderContext, StateUpdateType : StateUpdate<*>>(
     committedTree: Node<RenderContext>?,
     committedState: State?,
     val stateUpdatesToApply: List<StateUpdateType>,
-    val version: Int
+    val version: Int,
+    val frameId: Int,
 ) :
     ThreadInheritingPriorityFuture<ResolveResult<Node<RenderContext>, State>>(
         Callable {

litho-rendercore/src/main/java/com/facebook/rendercore/utils/VSyncUtils.kt

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.facebook.rendercore.utils
+
+import android.content.Context
+import android.view.WindowManager
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicInteger
+import kotlin.math.roundToInt
+
+object VSyncUtils {
+  private const val DEFAULT_REFRESH_RATE = 60.0
+  private const val REFRESH_RATE_MIN = 30.0
+  private const val REFRESH_RATE_MAX = 240.0
+  private val ONE_SECOND_IN_NS = TimeUnit.SECONDS.toNanos(1)
+
+  private val vsyncTimeNs: AtomicInteger = AtomicInteger(-1)
+
+  @JvmStatic
+  fun getNormalVsyncTime(context: Context): Int {
+    var value = vsyncTimeNs.get()
+    if (value != -1) {
+      return value
+    }
+
+    // Initialize the value.
+    val display = (context.getSystemService(Context.WINDOW_SERVICE) as WindowManager).defaultDisplay
+    var refreshRate = display.refreshRate.toDouble()
+
+    // If refresh rate is lower than 0, it means the OS is not reporting a correct value. We
+    // will
+    // assume it is 60.
+    refreshRate =
+        if (refreshRate < 0) {
+          DEFAULT_REFRESH_RATE
+        } else {
+          // Cap refresh rates between 30 and 240. Anything else is unreasonable.
+          refreshRate.coerceIn(REFRESH_RATE_MIN, REFRESH_RATE_MAX)
+        }
+
+    value = (ONE_SECOND_IN_NS / refreshRate).roundToInt()
+    vsyncTimeNs.compareAndSet(-1, value)
+
+    return value
+  }
+}

litho-rendercore/src/test/java/com/facebook/rendercore/RenderStateTest.kt

@@ -46,7 +46,7 @@ class RenderStateTest {
             nextState: Any?
         ) = Unit
 
-        override fun commitToUI(tree: RenderTree?, state: Any?) = Unit
+        override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) = Unit
       }
 
   @LooperMode(LooperMode.Mode.PAUSED)
@@ -74,7 +74,7 @@ class RenderStateTest {
                   nextState: Any?
               ) = Unit
 
-              override fun commitToUI(tree: RenderTree?, state: Any?) = Unit
+              override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) = Unit
             },
             null,
             null,
@@ -110,7 +110,7 @@ class RenderStateTest {
                 wasCalled.set(true)
               }
 
-              override fun commitToUI(tree: RenderTree?, state: Any?) = Unit
+              override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) = Unit
             },
             null,
             null)
@@ -145,7 +145,7 @@ class RenderStateTest {
                 }
               }
 
-              override fun commitToUI(tree: RenderTree?, state: Any?) = Unit
+              override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) = Unit
             },
             null,
             null)
@@ -293,7 +293,7 @@ class RenderStateTest {
                 numberOfCommits.incrementAndGet()
               }
 
-              override fun commitToUI(tree: RenderTree?, state: Any?) {
+              override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) {
                 numberOfUICommits.incrementAndGet()
               }
             },
@@ -331,7 +331,7 @@ class RenderStateTest {
                 numberOfCommits.incrementAndGet()
               }
 
-              override fun commitToUI(tree: RenderTree?, state: Any?) {
+              override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) {
                 numberOfUICommits.incrementAndGet()
               }
             },

litho-rendercore/src/test/java/com/facebook/rendercore/RootHostViewTests.kt

@@ -53,7 +53,7 @@ class RootHostViewTests {
                   nextState: Any?
               ) = Unit
 
-              override fun commitToUI(tree: RenderTree?, state: Any?) = Unit
+              override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) = Unit
             },
             null,
             null)
@@ -84,7 +84,7 @@ class RootHostViewTests {
                   nextState: Any?
               ) = Unit
 
-              override fun commitToUI(tree: RenderTree?, state: Any?) = Unit
+              override fun commitToUI(tree: RenderTree?, state: Any?, frameId: Int) = Unit
             },
             null,
             null)