Cover runtimeexecutor with Stable API guards (#58324)

Summary:

Classifies `runtimeexecutor:runtimeexecutor` as a public target under the C++ stable API three-tier visibility model. Adds `#include <react/cxxstableapi/UmbrellaGuard.h>` to the module's 3 exported headers and introduces the module umbrella `React/RuntimeExecutor.h`, wiring the guard dependency into BUCK, CMake and CocoaPods and the umbrella into BUCK, CocoaPods, the iOS prebuild header config and the Android prefab export.

Consumers that opt into `RN_STRICT_API` now get an error if they include the module's headers directly, and should include `<React/RuntimeExecutor.h>` instead; without that flag the guards are inert, so no existing build changes behaviour.

Changelog: [Internal]

Differential Revision: D118792973

Author: j-piasecki

packages/react-native/ReactAndroid/build.gradle.kts

@@ -191,6 +191,7 @@ val preparePrefab by
                       ),
                       // runtimeexecutor
                       Pair("../ReactCommon/runtimeexecutor/", ""),
+                      Pair("../ReactCommon/runtimeexecutor/platform/cxx/", ""),
                       // react_renderer_textlayoutmanager
                       Pair(
                           "../ReactCommon/react/renderer/textlayoutmanager/",

packages/react-native/ReactCommon/runtimeexecutor/CMakeLists.txt

@@ -14,6 +14,6 @@ add_library(runtimeexecutor OBJECT ${runtimeexecutor_SRC})
 
 target_include_directories(runtimeexecutor PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/platform/cxx)
 
-target_link_libraries(runtimeexecutor jsi)
+target_link_libraries(runtimeexecutor jsi react_cxxstableapi)
 target_compile_reactnative_options(runtimeexecutor PRIVATE)
 target_compile_options(runtimeexecutor PRIVATE -Wpedantic)

packages/react-native/ReactCommon/runtimeexecutor/React-runtimeexecutor.podspec

@@ -31,10 +31,14 @@ Pod::Spec.new do |s|
   s.platforms              = min_supported_versions
   s.source                 = source
   s.source_files           = podspec_sources(["ReactCommon/*.{m,mm,cpp,h}", "platform/ios/**/*.{m,mm,cpp,h}"], ["ReactCommon/*.h", "platform/ios/**/*.h"])
+  s.exclude_files          = ["React"]
   s.header_dir             = "ReactCommon"
 
   if ENV['USE_FRAMEWORKS']
-    header_search_paths = header_search_paths + ["\"$(PODS_TARGET_SRCROOT)/platform/ios\""]
+    header_search_paths = header_search_paths + [
+      "\"$(PODS_TARGET_SRCROOT)/platform/ios\"",
+      "\"$(PODS_TARGET_SRCROOT)/..\"", # ReactCommon, for <react/cxxstableapi/...>
+    ]
   end
 
   resolve_use_frameworks(s, header_mappings_dir: ".")
@@ -48,10 +52,17 @@ Pod::Spec.new do |s|
   add_rncore_dependency(s)
 
   s.dependency "React-jsi", version
+  s.dependency "React-cxxstableapi"
   add_dependency(s, "React-featureflags")
   add_dependency(s, "React-debug")
   add_dependency(s, "React-utils", :additional_framework_paths => ["react/utils/platform/ios"])
 
 
+  s.subspec "runtimeexecutorUmbrella" do |ss|
+    ss.source_files        = "React/*.h"
+    ss.header_dir          = ""
+    ss.header_mappings_dir = "."
+  end
+
   mark_as_react_native_build(s)
 end

packages/react-native/ReactCommon/runtimeexecutor/React/RuntimeExecutor.h

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+// =============================================================================
+// Umbrella header for the `runtimeexecutor` module - public entry point.
+//
+//   #include <React/RuntimeExecutor.h>
+//
+// Re-exports the module's public interface headers. React Native's own code
+// should keep using the fine-grained `<ReactCommon/...>` includes; only outside
+// consumers use this umbrella.
+// =============================================================================
+
+// Marks that the following headers are pulled in through the umbrella, so their
+// shared guard (<react/cxxstableapi/UmbrellaGuard.h>) accepts them. The marker
+// is saved and restored rather than defined and undefined: the scope ends at
+// this block, so later *direct* includes in the same TU are still caught, and
+// it nests inside an enclosing umbrella rather than disarming it.
+#pragma push_macro("RN_UMBRELLA_CONTEXT")
+#undef RN_UMBRELLA_CONTEXT
+#define RN_UMBRELLA_CONTEXT 1
+
+#include <ReactCommon/RuntimeExecutor.h>
+#include <ReactCommon/RuntimeExecutorSyncUIThreadUtils.h>
+
+#undef RN_UMBRELLA_CONTEXT
+#pragma pop_macro("RN_UMBRELLA_CONTEXT")

packages/react-native/ReactCommon/runtimeexecutor/ReactCommon/RuntimeExecutor.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <jsi/jsi.h>
 
 namespace facebook::react {

packages/react-native/ReactCommon/runtimeexecutor/platform/cxx/ReactCommon/RuntimeExecutorSyncUIThreadUtils.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <ReactCommon/RuntimeExecutor.h>
 
 #include <jsi/jsi.h>

packages/react-native/ReactCommon/runtimeexecutor/platform/ios/ReactCommon/RuntimeExecutorSyncUIThreadUtils.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <ReactCommon/RuntimeExecutor.h>
 
 #include <jsi/jsi.h>

packages/react-native/scripts/ios-prebuild/headers-config.js

@@ -653,6 +653,24 @@ const PodspecExceptions /*: {[key: string]: PodSpecConfiguration} */ = {
       },
     ],
   },
+  'ReactCommon/runtimeexecutor/React-runtimeexecutor.podspec': {
+    name: 'React-runtimeexecutor',
+    headerPatterns: [],
+    headerDir: '',
+    subSpecs: [
+      {
+        name: 'runtimeexecutor',
+        headerPatterns: ['ReactCommon/*.h', 'platform/ios/**/*.h'],
+        excludePatterns: ['React'],
+        headerDir: 'ReactCommon',
+      },
+      {
+        name: 'runtimeexecutorUmbrella',
+        headerPatterns: ['React/*.h'],
+        headerDir: 'React',
+      },
+    ],
+  },
 };
 
 module.exports = {PodspecExceptions};