feat(Worklets): runOnRuntimeSync

apps/common-app/src/apps/reanimated/examples/RuntimeTests/RuntimeTestsExample.tsx

@@ -58,6 +58,7 @@ export default function RuntimeTestsExample() {
             require('./tests/runtimes/runOnUISync.test');
             require('./tests/runtimes/scheduleOnRuntime.test');
             require('./tests/runtimes/scheduleOnUI.test');
+            require('./tests/runtimes/runOnRuntimeSync.test');
           },
         },
         {

apps/common-app/src/apps/reanimated/examples/RuntimeTests/tests/runtimes/runOnRuntimeSync.test.tsx

@@ -0,0 +1,57 @@
+import {
+  createSynchronizable,
+  createWorkletRuntime,
+  scheduleOnRN,
+  runOnRuntimeSync,
+  scheduleOnRuntime,
+} from 'react-native-worklets';
+import { describe, expect, test, notify, waitForNotification } from '../../ReJest/RuntimeTestsApi';
+import { ComparisonMode } from '../../ReJest/types';
+
+const NOTIFICATION_NAME = 'NOTIFICATION_NAME';
+
+describe('runOnRuntimeSync', () => {
+  test('use runOnRuntimeSync to run a function on the Worker Runtime from RN Runtime', () => {
+    // Arrange
+    const workletRuntime = createWorkletRuntime({ name: 'test' });
+
+    // Act
+    const result = runOnRuntimeSync(workletRuntime, () => {
+      'worklet';
+      return 100;
+    });
+
+    // Assert
+    expect(result).toBe(100, ComparisonMode.NUMBER);
+  });
+
+  test('keep the correct order of execution runOnRuntimeSync and scheduleOnRuntime', async () => {
+    // Arrange
+    const workletRuntime = createWorkletRuntime({ name: 'test' });
+    const synchronizable = createSynchronizable(0);
+
+    const onJSCallback = () => {
+      notify(NOTIFICATION_NAME);
+    };
+
+    // Act
+    // TODO: Replace with `runOnRuntimeAsync`.
+    scheduleOnRuntime(workletRuntime, () => {
+      'worklet';
+      // heavy computation
+      new Array(50_000_000).map((_v, i) => i ** 2);
+      synchronizable.setBlocking(100);
+      scheduleOnRN(onJSCallback);
+    });
+
+    const result = runOnRuntimeSync(workletRuntime, () => {
+      'worklet';
+      return 100;
+    });
+
+    // Assert
+    expect(result).toBe(100, ComparisonMode.NUMBER);
+    await waitForNotification(NOTIFICATION_NAME);
+    expect(synchronizable.getBlocking()).toBe(100, ComparisonMode.NUMBER);
+  });
+});

packages/docs-worklets/docs/threading/createWorkletRuntime.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 8
 ---
 
 # createWorkletRuntime

packages/docs-worklets/docs/threading/executeOnUIRuntimeSync.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 ---
 
 <DeprecatedBanner

packages/docs-worklets/docs/threading/getRuntimeKind.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 12
 ---
 
 # getRuntimeKind

packages/docs-worklets/docs/threading/isWorkletFunction.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 13
 ---
 
 # isWorkletFunction

packages/docs-worklets/docs/threading/runOnRuntime.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 9
 ---
 
 <DeprecatedBanner

packages/docs-worklets/docs/threading/runOnRuntimeSync.mdx

@@ -0,0 +1,79 @@
+---
+sidebar_position: 11
+---
+
+# runOnRuntimeSync
+
+`runOnRuntimeSync` lets you run a [workletized](/docs/fundamentals/glossary#to-workletize) function synchronously on a [Worker Runtime](/docs/fundamentals/glossary#worker-worklet-runtime---worker-runtime).
+It might preempt the Runtime where it's called from the thread (it's blocking).
+## Reference
+
+```javascript
+import { runOnRuntimeSync, createWorkletRuntime } from 'react-native-worklets';
+
+const workletRuntime = createWorkletRuntime({ name: 'background' });
+
+const result = runOnRuntimeSync(workletRuntime, () => {
+  'worklet';
+  return 2+2;
+}); // This will block the RN Runtime until the worklet is finished
+
+console.log(result); // 4
+```
+
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+function runOnRuntimeSync<Args extends unknown[], ReturnValue>(
+  workletRuntime: WorkletRuntime,
+  worklet: (...args: Args) => ReturnValue,
+  ...args: Args
+): ReturnValue
+```
+
+</details>
+
+## Arguments
+
+### workletRuntime
+
+The worklet runtime to run the worklet on.
+
+### worklet
+
+A reference to a function you want to execute on the [Worklet Runtime](/docs/fundamentals/glossary#worklet-runtime).
+
+### args
+
+Arguments to the function you want to execute on the [Worklet Runtime](/docs/fundamentals/glossary#worklet-runtime).
+
+## Remarks
+
+- `runOnRuntimeSync` can only be called on the [RN Runtime](/docs/fundamentals/glossary#react-native-runtime) unless the [Bundle Mode](/docs/experimental/bundleMode) is enabled.
+
+```javascript
+import { createWorkletRuntime, runOnRuntimeSync } from 'react-native-worklets';
+
+const workletRuntime = createWorkletRuntime({ name: 'background' });
+
+runOnUI(() => {
+  runOnRuntimeSync(workletRuntime, (greeting: string) => { 
+    console.log(`${greeting} from the background Worklet Runtime`); 
+  }, 'Hello'); // This will throw an error outside of Bundle Mode 🚨
+});
+```
+
+```javascript
+import { createWorkletRuntime, scheduleOnRuntime } from 'react-native-worklets';
+
+const workletRuntime = createWorkletRuntime({ name: 'background' });
+const anotherWorkletRuntime = createWorkletRuntime({ name: 'anotherBackground' });
+
+runOnRuntimeSync(anotherWorkletRuntime, () => {
+  runOnRuntimeSync(workletRuntime, (greeting: string) => {
+    console.log(`${greeting} from the background Worklet Runtime`);
+  }, 'Hello'); // This will throw an error outside of Bundle Mode 🚨
+});
+```

packages/docs-worklets/docs/threading/runOnUIAsync.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # runOnUIAsync

packages/docs-worklets/docs/threading/runOnUISync.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 10
+sidebar_position: 5
 ---
 
 # runOnUISync

packages/docs-worklets/docs/threading/scheduleOnRN.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 7
 ---
 
 # scheduleOnRN

packages/docs-worklets/docs/threading/scheduleOnRuntime.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 12
+sidebar_position: 10
 ---
 
 # scheduleOnRuntime
@@ -74,6 +74,6 @@ const anotherWorkletRuntime = createWorkletRuntime({ name: 'anotherBackground' }
 scheduleOnRuntime(anotherWorkletRuntime, () => {
   scheduleOnRuntime(workletRuntime, (greeting: string) => {
     console.log(`${greeting} from the background Worklet Runtime`);
-  }, 'Hello'); // This will throw an error 🚨
+  }, 'Hello'); // This will throw an error outside of Bundle Mode 🚨
 });
 ```

packages/docs-worklets/docs/threading/scheduleOnUI.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 11
+sidebar_position: 6
 ---
 
 # scheduleOnUI

packages/react-native-worklets/Common/cpp/worklets/NativeModules/JSIWorkletsModuleProxy.cpp

@@ -61,6 +61,15 @@ inline jsi::Value executeOnUIRuntimeSync(
   return jsi::Value::undefined();
 }
 
+inline jsi::Value runOnRuntimeSync(
+    jsi::Runtime &rt,
+    const jsi::Value &workletRuntimeValue,
+    const jsi::Value &serializableWorkletValue) {
+  auto workletRuntime =
+      workletRuntimeValue.getObject(rt).getHostObject<WorkletRuntime>(rt);
+  return workletRuntime->executeSync(rt, serializableWorkletValue);
+}
+
 inline jsi::Value createWorkletRuntime(
     jsi::Runtime &originRuntime,
     const std::shared_ptr<RuntimeManager> &runtimeManager,
@@ -202,6 +211,7 @@ std::vector<jsi::PropNameID> JSIWorkletsModuleProxy::getPropertyNames(
   propertyNames.emplace_back(jsi::PropNameID::forAscii(rt, "scheduleOnUI"));
   propertyNames.emplace_back(
       jsi::PropNameID::forAscii(rt, "executeOnUIRuntimeSync"));
+  propertyNames.emplace_back(jsi::PropNameID::forAscii(rt, "runOnRuntimeSync"));
   propertyNames.emplace_back(
       jsi::PropNameID::forAscii(rt, "createWorkletRuntime"));
   propertyNames.emplace_back(
@@ -496,6 +506,17 @@ jsi::Value JSIWorkletsModuleProxy::get(
         });
   }
 
+  if (name == "runOnRuntimeSync") {
+    return jsi::Function::createFromHostFunction(
+        rt,
+        propName,
+        2,
+        [](jsi::Runtime &rt,
+           const jsi ::Value &thisValue,
+           const jsi::Value *args,
+           size_t count) { return runOnRuntimeSync(rt, args[0], args[1]); });
+  }
+
   if (name == "createWorkletRuntime") {
     return jsi::Function::createFromHostFunction(
         rt,

packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/WorkletRuntime.cpp

@@ -164,11 +164,12 @@ jsi::Value WorkletRuntime::executeSync(
   auto serializableWorklet = extractSerializableOrThrow<SerializableWorklet>(
       rt,
       worklet,
-      "[Worklets] Only worklets can be executed synchronously on UI runtime.");
+      "[Worklets] Only worklets can be executed synchronously on Worklet (" +
+          name_ + ") Runtime.");
   auto lock = std::unique_lock<std::recursive_mutex>(*runtimeMutex_);
-  jsi::Runtime &uiRuntime = getJSIRuntime();
+  jsi::Runtime &workletRuntime = getJSIRuntime();
   auto result = runGuarded(serializableWorklet);
-  auto serializableResult = extractSerializableOrThrow(uiRuntime, result);
+  auto serializableResult = extractSerializableOrThrow(workletRuntime, result);
   lock.unlock();
   return serializableResult->toJSValue(rt);
 }

packages/react-native-worklets/__typetests__/runOnRuntimeSync.tsx

@@ -0,0 +1,46 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { createWorkletRuntime, runOnRuntimeSync, runOnUISync } from '..';
+
+function runOnRuntimeSyncTypeTests() {
+  const workletRuntime = createWorkletRuntime({ name: 'test' });
+  // Correct usage - correct usage
+  runOnRuntimeSync(
+    workletRuntime,
+    (num: number): number => {
+      return num + 1;
+    },
+    0
+  );
+
+  // @ts-expect-error - expected no args, but arg is provided
+  runOnRuntimeSync(workletRuntime, (): void => {}, 0);
+
+  // Wrong args type
+  runOnRuntimeSync(
+    workletRuntime,
+    (num: number): number => {
+      return num + 1;
+    },
+    // @ts-expect-error - wrong args type
+    'tets'
+  );
+
+  // Wrong return type
+  runOnRuntimeSync(
+    workletRuntime,
+    (num: number): string => {
+      // @ts-expect-error - wrong return type
+      return num + 1;
+    },
+    0
+  );
+
+  // @ts-expect-error - wrong return type
+  const result: string = runOnRuntimeSync(
+    workletRuntime,
+    (num: number): number => {
+      return num + 1;
+    },
+    0
+  );
+}

packages/react-native-worklets/src/WorkletsModule/JSWorklets.ts

@@ -135,6 +135,12 @@ class JSWorklets implements IWorkletsModule {
     );
   }
 
+  runOnRuntimeSync(): never {
+    throw new WorkletsError(
+      '`runOnRuntimeSync` is not available in JSWorklets.'
+    );
+  }
+
   createWorkletRuntime(): never {
     throw new WorkletsError(
       'createWorkletRuntime is not available in JSWorklets.'

packages/react-native-worklets/src/WorkletsModule/NativeWorklets.ts

@@ -192,6 +192,13 @@ See https://docs.swmansion.com/react-native-worklets/docs/guides/troubleshooting
     );
   }
 
+  runOnRuntimeSync<TValue, TReturn>(
+    workletRuntime: WorkletRuntime,
+    worklet: SerializableRef<TValue>
+  ): TReturn {
+    return this.#workletsModuleProxy.runOnRuntimeSync(workletRuntime, worklet);
+  }
+
   createSynchronizable<TValue>(value: TValue): SynchronizableRef<TValue> {
     return this.#workletsModuleProxy.createSynchronizable(value);
   }

packages/react-native-worklets/src/WorkletsModule/workletsModuleProxy.ts

@@ -88,6 +88,11 @@ export interface WorkletsModuleProxy {
     worklet: SerializableRef<TValue>
   ): void;
 
+  runOnRuntimeSync<TValue, TReturn>(
+    workletRuntime: WorkletRuntime,
+    worklet: SerializableRef<TValue>
+  ): TReturn;
+
   reportFatalErrorOnJS(
     message: string,
     stack: string,

packages/react-native-worklets/src/index.ts

@@ -21,6 +21,7 @@ export { getRuntimeKind, RuntimeKind } from './runtimeKind';
 export {
   createWorkletRuntime,
   runOnRuntime,
+  runOnRuntimeSync,
   scheduleOnRuntime,
 } from './runtimes';
 export { createSerializable, isSerializableRef } from './serializable';