Document committed semantics of hasBeenMounted and threading (#59108)

Summary:
Pull Request resolved: #59108

Review follow-ups for the preallocated view cleanup in the pull model:

- Document that `ShadowNodeFamily::setMounted()` and `hasBeenMounted()` refer to a node of the family being part of a committed shadow tree, which can happen before the platform mounts its view. This matches how `ShadowNode::setMounted` and `updateMountedFlag` use "mounted", so the names stay.
- Document the threading requirements of the `FabricMountingManager` preallocation and mount methods.
- Rename the test helper `mountCreate` to `executeCreateMutation`.

Changelog: [Internal]

Differential Revision: D125436483

Author: bartlomiejbloniarz

packages/react-native/ReactAndroid/src/main/jni/react/fabric/FabricMountingManager.h

@@ -32,15 +32,22 @@ class FabricMountingManager final {
 
   void onSurfaceStop(SurfaceId surfaceId);
 
+  /*
+   * Can be called from any thread.
+   */
   void maybePreallocateShadowNode(const ShadowNode &shadowNode);
 
+  /*
+   * Can be called from any thread.
+   */
   void destroyUnmountedShadowNode(const ShadowNodeFamily &family);
 
   /*
    * Drains preallocatedViewsQueue_: preallocates each queued view on the Java
    * side and registers its tag in allocatedViewRegistry_ so that executeMount
    * skips the redundant Create mount item for this tag. In the pull model, it
-   * skips the views whose family was destroyed. Can be called by any thread.
+   * skips the views whose family was destroyed. Must be called on the UI
+   * thread.
    */
   void drainPreallocateViewsQueue();
 

packages/react-native/ReactAndroid/src/main/jni/react/fabric/test_helper/FabricMountingManagerTestHelper.cpp

@@ -117,7 +117,9 @@ void FabricMountingManagerTestHelper::drainPreallocationQueue() {
   mountingManager_->drainPreallocateViewsQueue();
 }
 
-void FabricMountingManagerTestHelper::mountCreate(jint surfaceId, jint tag) {
+void FabricMountingManagerTestHelper::executeCreateMutation(
+    jint surfaceId,
+    jint tag) {
   auto telemetry = TransactionTelemetry{};
   telemetry.willCommit();
   telemetry.willDiff();
@@ -300,7 +302,8 @@ void FabricMountingManagerTestHelper::registerNatives() {
           "drainPreallocationQueue",
           FabricMountingManagerTestHelper::drainPreallocationQueue),
       makeNativeMethod(
-          "mountCreate", FabricMountingManagerTestHelper::mountCreate),
+          "executeCreateMutation",
+          FabricMountingManagerTestHelper::executeCreateMutation),
       makeNativeMethod(
           "dropFamily", FabricMountingManagerTestHelper::dropFamily),
       makeNativeMethod(

packages/react-native/ReactAndroid/src/main/jni/react/fabric/test_helper/FabricMountingManagerTestHelper.h

@@ -31,7 +31,7 @@ class FabricMountingManagerTestHelper : public jni::HybridClass<FabricMountingMa
   void preallocateView(jint surfaceId, jint tag);
   void queuePreallocation(jint surfaceId, jint tag);
   void drainPreallocationQueue();
-  void mountCreate(jint surfaceId, jint tag);
+  void executeCreateMutation(jint surfaceId, jint tag);
   void dropFamily(jint tag);
   void destroyUnmountedView(jint surfaceId, jint tag);
   void destroyCommittedView(jint surfaceId, jint tag);

packages/react-native/ReactAndroid/src/test/java/com/facebook/react/fabric/FabricMountingManagerInstrumentationTest.kt

@@ -432,7 +432,7 @@ class FabricMountingManagerInstrumentationTest {
     val helper = createTestHelper()
     helper.startSurface(surfaceId)
     helper.preallocateView(surfaceId, 42)
-    helper.mountCreate(surfaceId, 42)
+    helper.executeCreateMutation(surfaceId, 42)
 
     helper.destroyCommittedView(surfaceId, 42)
 

packages/react-native/ReactAndroid/src/test/java/com/facebook/react/fabric/FabricMountingManagerTestHelper.kt

@@ -35,7 +35,7 @@ class FabricMountingManagerTestHelper private constructor(fabricUIManager: Fabri
 
   external fun drainPreallocationQueue()
 
-  external fun mountCreate(surfaceId: Int, tag: Int)
+  external fun executeCreateMutation(surfaceId: Int, tag: Int)
 
   external fun dropFamily(tag: Int)
 

packages/react-native/ReactCommon/react/renderer/core/ShadowNodeFamily.h

@@ -107,12 +107,13 @@ class ShadowNodeFamily final : public jsi::NativeState {
   void setMostRecentState(const std::shared_ptr<const State> &state);
 
   /**
-   * Mark this ShadowNodeFamily as mounted.
+   * Mark this ShadowNodeFamily as part of a committed shadow tree.
    */
   void setMounted();
 
   /**
-   * Whether this ShadowNodeFamily was ever mounted.
+   * Whether this ShadowNodeFamily was ever part of a committed shadow tree.
+   * Its view may not have been mounted on the platform yet.
    */
   bool hasBeenMounted() const;
 
@@ -206,7 +207,7 @@ class ShadowNodeFamily final : public jsi::NativeState {
   bool hasParent_{false};
 
   /*
-   * Determines if the ShadowNodeFamily was ever mounted on the screen.
+   * Determines if the ShadowNodeFamily was ever part of a committed shadow tree.
    */
   bool hasBeenMounted_{false};
 };