Skip to content

Commit 3020bf8

Browse files
feat: docs for runOnRuntimeAsync (#8911)
This is a follow on PR of #8901. This should add docs for runOnRuntimeAsync. ## Summary ## Test plan <img width="1137" height="1191" alt="image" src="https://github.com/user-attachments/assets/f679bd97-5692-4cb5-af07-7da8fb1e745c" />
1 parent ad090fe commit 3020bf8

File tree

1 file changed

+90
-0
lines changed

1 file changed

+90
-0
lines changed
Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
sidebar_position: 42 # Use alphabetical order
3+
---
4+
5+
# runOnRuntimeAsync <AvailableFrom version="0.8.0"/>
6+
7+
`runOnRuntimeAsync` lets you asynchronously run [worklets](/docs/fundamentals/glossary#worklet) on a [Worker Runtime](/docs/fundamentals/runtimeKinds#worker-runtime).
8+
It returns a Promise of the worklet's return value. The Promise is resolved asynchronously, not immediately after the callback execution.
9+
10+
## Reference
11+
12+
```javascript
13+
import { runOnRuntimeAsync, createWorkletRuntime } from 'react-native-worklets';
14+
15+
const workletRuntime = createWorkletRuntime({ name: 'background' });
16+
17+
// RN Runtime, JS thread
18+
19+
const result: Promise<number> = runOnRuntimeAsync(workletRuntime, (): number => {
20+
'worklet';
21+
return 2 + 2;
22+
});
23+
24+
await result; // 4
25+
```
26+
27+
<details>
28+
<summary>Type definitions</summary>
29+
30+
```typescript
31+
function runOnRuntimeAsync<Args extends unknown[], ReturnValue>(
32+
workletRuntime: WorkletRuntime,
33+
worklet: (...args: Args) => ReturnValue,
34+
...args: Args
35+
): Promise<ReturnValue>;
36+
```
37+
38+
</details>
39+
40+
## Arguments
41+
42+
### workletRuntime
43+
44+
The worklet runtime to run the worklet on. Created with [`createWorkletRuntime`](/docs/threading/createWorkletRuntime).
45+
46+
### worklet
47+
48+
A reference to a function you want to execute on the [Worker Runtime](/docs/fundamentals/runtimeKinds#worker-runtime). Arguments to your function have to be passed after the worklet i.e. `runOnRuntimeAsync(workletRuntime, setValue, 10);`.
49+
50+
### args
51+
52+
Arguments to the function you want to execute on the [Worker Runtime](/docs/fundamentals/runtimeKinds#worker-runtime).
53+
54+
## Remarks
55+
56+
- It's a common mistake to execute function inside of `runOnRuntimeAsync` like this: ~~`runOnRuntimeAsync(workletRuntime, myWorklet(10))`~~. Here, the correct usage would be `runOnRuntimeAsync(workletRuntime, myWorklet, 10)`.
57+
58+
- The callback passed as the argument is automatically [workletized](/docs/fundamentals/glossary#to-workletize) and ready to be run on the [Worker Runtime](/docs/fundamentals/runtimeKinds#worker-runtime).
59+
60+
- `runOnRuntimeAsync` can only be called from the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). Calling it from other runtimes will result in an error.
61+
62+
- Errors thrown in the worklet will cause the Promise to reject with that error.
63+
64+
## Example
65+
66+
```javascript
67+
import { runOnRuntimeAsync, createWorkletRuntime } from 'react-native-worklets';
68+
69+
const backgroundRuntime = createWorkletRuntime({ name: 'background' });
70+
71+
async function performHeavyComputation(data: number[]) {
72+
try {
73+
const result = await runOnRuntimeAsync(backgroundRuntime, (numbers: number[]) => {
74+
'worklet';
75+
// Heavy computation on background thread
76+
return numbers.reduce((sum, n) => sum + n, 0);
77+
}, data);
78+
79+
console.log('Computation result:', result);
80+
} catch (error) {
81+
console.error('Computation failed:', error);
82+
}
83+
}
84+
```
85+
86+
## Platform compatibility
87+
88+
| Android | iOS | Web |
89+
| ------- | --- | --- |
90+
||||

0 commit comments

Comments
 (0)