From 0678b0812ae763240718f391533c3775327b0c07 Mon Sep 17 00:00:00 2001
From: Tomek Zawadzki <tomekzawadzki98@gmail.com>
Date: Mon, 27 Jan 2025 10:58:05 +0100
Subject: [PATCH 1/3] docs: add `runOnRuntime` page and extend
`createWorkletRuntime` page
---
.../docs/threading/createWorkletRuntime.mdx | 4 +-
.../docs/threading/runOnRuntime.mdx | 70 +++++++++++++++++++
2 files changed, 73 insertions(+), 1 deletion(-)
create mode 100644 packages/docs-reanimated/docs/threading/runOnRuntime.mdx
diff --git a/packages/docs-reanimated/docs/threading/createWorkletRuntime.mdx b/packages/docs-reanimated/docs/threading/createWorkletRuntime.mdx
index 1feadb9dec0..72322c23cab 100644
--- a/packages/docs-reanimated/docs/threading/createWorkletRuntime.mdx
+++ b/packages/docs-reanimated/docs/threading/createWorkletRuntime.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 3
+sidebar_position: 4
---
# createWorkletRuntime
@@ -69,6 +69,8 @@ An optional worklet that will be run synchronously on the same thread immediatel
- You can use Chrome DevTools to debug the runtime (Hermes only). The runtime will appear in the devices list as `name` passed to `createWorkletRuntime`.
+- [Shared values](/docs/fundamentals/glossary#shared-value) are only partially supported in worklet runtimes. If you want to write to a shared value from the RN runtime and read it on the worklet runtime, you need to perform the assignment using [`runOnRuntime`](/docs/threading/runOnRuntime). Otherwise, the value will be updated only in the RN and UI runtimes.
+
## Platform compatibility
<PlatformCompatibility android ios />
diff --git a/packages/docs-reanimated/docs/threading/runOnRuntime.mdx b/packages/docs-reanimated/docs/threading/runOnRuntime.mdx
new file mode 100644
index 00000000000..87b764454b0
--- /dev/null
+++ b/packages/docs-reanimated/docs/threading/runOnRuntime.mdx
@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# runOnRuntime
+
+`runOnRuntime` lets you asynchronously run [workletized](/docs/fundamentals/glossary#to-workletize) functions on a separate worklet runtime on a separate thread.
+
+## Reference
+
+```javascript
+import { createWorkletRuntime, runOnRuntime } from 'react-native-reanimated';
+
+const workletRuntime = createWorkletRuntime('background');
+
+function App() {
+ // E.g. in event handler or in an effect
+ // highlight-next-line
+ runOnRuntime(workletRuntime, (greeting) => {
+ console.log(`${greeting} from a separate thread`);
+ // highlight-next-line
+ })('Howdy');
+
+ // ...
+}
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+function runOnRuntime<A extends any[], R>(
+ workletRuntime: WorkletRuntime,
+ fn: (...args: A) => R
+): (...args: Parameters<typeof fn>) => void;
+```
+
+</details>
+
+### Arguments
+
+#### workletRuntime
+
+A reference to worklet runtime created with [`createWorkletRuntime`](/docs/advanced/createWorkletRuntime).
+
+#### fn
+
+A reference to a function you want to execute on the [UI thread](/docs/fundamentals/glossary#ui-thread) from the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread). Arguments to your function have to be passed to the function returned from `runOnUI` i.e. `runOnUI(myWorklet)(10);`.
+
+### Returns
+
+`runOnRuntime` returns a function that accepts arguments for the function passed as the first argument.
+
+:::info
+Don't forget to call the function returned from `runOnRuntime`.
+:::
+
+## Remarks
+
+- It's a common mistake to execute function inside of `runOnRuntime` like this: ~~`runOnRuntime(myWorklet(10))()`~~. Here, the correct usage would be `runOnRuntime(myWorklet)(10)`.
+
+- The callback passed as the argument will not be [workletized](/docs/fundamentals/glossary#to-workletize) automatically. You need to add `'worklet';` directive manually to allow the function to be run on the [UI thread](/docs/fundamentals/glossary#ui-thread).
+
+- You may call `runOnRuntime` on any runtime, including the RN runtime, UI runtime and other worklet runtimes.
+
+- The function passed to `runOnRuntime` will be added to an execution queue on a separate thread and executed asynchronously on the specified worklet runtime. The functions will be executed in the order they were added to the queue.
+
+## Platform compatibility
+
+<PlatformCompatibility android ios />
From 3e7ad513faca4c17a27f5e6f7b807ff0646287b7 Mon Sep 17 00:00:00 2001
From: Tomek Zawadzki <tomekzawadzki98@gmail.com>
Date: Mon, 27 Jan 2025 13:33:58 +0100
Subject: [PATCH 2/3] docs: propagate changes to 3.x versioned docs
---
.../threading/createWorkletRuntime.mdx | 4 +-
.../version-3.x/threading/runOnRuntime.mdx | 70 +++++++++++++++++++
2 files changed, 73 insertions(+), 1 deletion(-)
create mode 100644 packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx
diff --git a/packages/docs-reanimated/versioned_docs/version-3.x/threading/createWorkletRuntime.mdx b/packages/docs-reanimated/versioned_docs/version-3.x/threading/createWorkletRuntime.mdx
index 1feadb9dec0..72322c23cab 100644
--- a/packages/docs-reanimated/versioned_docs/version-3.x/threading/createWorkletRuntime.mdx
+++ b/packages/docs-reanimated/versioned_docs/version-3.x/threading/createWorkletRuntime.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 3
+sidebar_position: 4
---
# createWorkletRuntime
@@ -69,6 +69,8 @@ An optional worklet that will be run synchronously on the same thread immediatel
- You can use Chrome DevTools to debug the runtime (Hermes only). The runtime will appear in the devices list as `name` passed to `createWorkletRuntime`.
+- [Shared values](/docs/fundamentals/glossary#shared-value) are only partially supported in worklet runtimes. If you want to write to a shared value from the RN runtime and read it on the worklet runtime, you need to perform the assignment using [`runOnRuntime`](/docs/threading/runOnRuntime). Otherwise, the value will be updated only in the RN and UI runtimes.
+
## Platform compatibility
<PlatformCompatibility android ios />
diff --git a/packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx b/packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx
new file mode 100644
index 00000000000..87b764454b0
--- /dev/null
+++ b/packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx
@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# runOnRuntime
+
+`runOnRuntime` lets you asynchronously run [workletized](/docs/fundamentals/glossary#to-workletize) functions on a separate worklet runtime on a separate thread.
+
+## Reference
+
+```javascript
+import { createWorkletRuntime, runOnRuntime } from 'react-native-reanimated';
+
+const workletRuntime = createWorkletRuntime('background');
+
+function App() {
+ // E.g. in event handler or in an effect
+ // highlight-next-line
+ runOnRuntime(workletRuntime, (greeting) => {
+ console.log(`${greeting} from a separate thread`);
+ // highlight-next-line
+ })('Howdy');
+
+ // ...
+}
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+function runOnRuntime<A extends any[], R>(
+ workletRuntime: WorkletRuntime,
+ fn: (...args: A) => R
+): (...args: Parameters<typeof fn>) => void;
+```
+
+</details>
+
+### Arguments
+
+#### workletRuntime
+
+A reference to worklet runtime created with [`createWorkletRuntime`](/docs/advanced/createWorkletRuntime).
+
+#### fn
+
+A reference to a function you want to execute on the [UI thread](/docs/fundamentals/glossary#ui-thread) from the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread). Arguments to your function have to be passed to the function returned from `runOnUI` i.e. `runOnUI(myWorklet)(10);`.
+
+### Returns
+
+`runOnRuntime` returns a function that accepts arguments for the function passed as the first argument.
+
+:::info
+Don't forget to call the function returned from `runOnRuntime`.
+:::
+
+## Remarks
+
+- It's a common mistake to execute function inside of `runOnRuntime` like this: ~~`runOnRuntime(myWorklet(10))()`~~. Here, the correct usage would be `runOnRuntime(myWorklet)(10)`.
+
+- The callback passed as the argument will not be [workletized](/docs/fundamentals/glossary#to-workletize) automatically. You need to add `'worklet';` directive manually to allow the function to be run on the [UI thread](/docs/fundamentals/glossary#ui-thread).
+
+- You may call `runOnRuntime` on any runtime, including the RN runtime, UI runtime and other worklet runtimes.
+
+- The function passed to `runOnRuntime` will be added to an execution queue on a separate thread and executed asynchronously on the specified worklet runtime. The functions will be executed in the order they were added to the queue.
+
+## Platform compatibility
+
+<PlatformCompatibility android ios />
From ea4669e4598fc9adb5f2b2324cbae057d5705f76 Mon Sep 17 00:00:00 2001
From: Tomek Zawadzki <tomekzawadzki98@gmail.com>
Date: Mon, 27 Jan 2025 13:42:41 +0100
Subject: [PATCH 3/3] Fix broken links
---
packages/docs-reanimated/docs/threading/runOnRuntime.mdx | 2 +-
.../versioned_docs/version-3.x/threading/runOnRuntime.mdx | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/packages/docs-reanimated/docs/threading/runOnRuntime.mdx b/packages/docs-reanimated/docs/threading/runOnRuntime.mdx
index 87b764454b0..de1742591cf 100644
--- a/packages/docs-reanimated/docs/threading/runOnRuntime.mdx
+++ b/packages/docs-reanimated/docs/threading/runOnRuntime.mdx
@@ -41,7 +41,7 @@ function runOnRuntime<A extends any[], R>(
#### workletRuntime
-A reference to worklet runtime created with [`createWorkletRuntime`](/docs/advanced/createWorkletRuntime).
+A reference to worklet runtime created with [`createWorkletRuntime`](/docs/threading/createWorkletRuntime).
#### fn
diff --git a/packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx b/packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx
index 87b764454b0..de1742591cf 100644
--- a/packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx
+++ b/packages/docs-reanimated/versioned_docs/version-3.x/threading/runOnRuntime.mdx
@@ -41,7 +41,7 @@ function runOnRuntime<A extends any[], R>(
#### workletRuntime
-A reference to worklet runtime created with [`createWorkletRuntime`](/docs/advanced/createWorkletRuntime).
+A reference to worklet runtime created with [`createWorkletRuntime`](/docs/threading/createWorkletRuntime).
#### fn