The Idea of React Native Worklets and Its JavaScript API

[tjzel]

The Idea of React Native Worklets and Its JavaScript API

Abstract

react-native-worklets is a multithreading library for React Native. It allows to run JavaScript code on multiple JavaScript runtimes and threads. Its primary responsibility is to spawn and manage the UI Runtime – a JavaScript runtime for running worklets on the UI thread.

The purpose of this document is to provide a high-level overview of the desired react-native-worklets' functionalities available in JavaScript as well as a brief explanation of its mental model and limitations. The ideas aren't set in stone and we would be more than happy to iterate on the feedback received from the community.

The discussion about its native API will be facilitated in another document.

Terms

• React Native Runtime

  Referred to as RN Runtime. It is the JavaScript Runtime that executes your app's bundle and where the React part of React Native lives.

• UI Thread

  Also called the Main Thread. It is the only thread that has synchronous access to native events and the native rendering layer.

• JS Thread

  The thread that is primarily tasked with the continuous execution of the RN Runtime.

• Closure

  In a JavaScript function you can use variables defined outside of this function. A collection of these variables and the function are collectively referred to as a closure. You can read more about closures here. Sometimes we refer only to the closure's variables as closure.

• Worklet

  A short JavaScript function (closure), which can be executed on a JavaScript runtime different from the runtime of its origin.

• Worklet Runtime

  A JavaScript runtime spawned by react-native-worklets. It's pre-configured to be able to execute worklets. It isn't coupled to any thread, but there might be a thread dedicated to its execution.

• UI Runtime

  A unique Worklet Runtime that is tailored to efficiently offload work from the RN Runtime and to allow for synchronous access to native events and the native rendering layer.

Why

Worklets were created for smooth animations and handling gestures in react-native-reanimated and react-native-gesture-handler. Over time, we noticed the limitations of its implementation. The multithreading model, tightly coupled with animations and gestures, proved difficult to maintain and exceptionally challenging to expand. Moreover, the community found more applications of worklets than we previously anticipated like processing camera frames, drawing on the Skia canvas and synchronous text formatting. A natural conclusion was to create a separate library with clearly defined boundaries and interfaces.

We received numerous pieces of feedback from the community about the fact that react-native-reanimated is too large to function effectively as a singular entity. This has been a pain point for web apps aiming for the smallest possible bundle size. It was also counterintuitive that, to delegate a resource-heavy task to another thread, you had to use an animation library that added countless features you weren't interested in using but which nevertheless impacted your app.

This is also an opportunity for us, the Reanimated team, to "start over" and make some things right. The multithreading part of react-native-reanimated had occasionally been confusing for our users. It wasn't always clear whether something was executed synchronously, asynchronously, or whether a graphical glitch was due to a bug or an ill-written user animation. We aim to retain a minimalist, seamless API while placing a significantly greater emphasis on its cost and understandability.

How

We plan to implement the API and concepts described in this document gradually. In the initial iterations of react-native-worklets, we'll maintain the APIs known from react-native-reanimated, such as runOnUI, runOnJS, etc. These will eventually get deprecated and dropped over time.

While we aim to create a library that would be symmetric across all Worklet Runtimes, early on we want to focus on the most important feature of react-native-worklets — the UI Runtime. Therefore, general features that aren't specific to the UI Runtime might lag behind for a few iterations.

Threading

JavaScript runtimes aren't tied to a specific thread. We like to think of them as of not thread-safe resources. Therefore, a thread must acquire a given runtime exclusively, which could lead to costly preemptions and even deadlocks in ill-written code. We want to reflect these costs in the API design. To address the transparency issues, we plan to embrace the async/await syntax to hint to the user about what might be going on under the hood.

scheduleOnUI

A function that schedules a worklet on the UI Runtime, to be executed on the UI thread. It doesn't return a value nor directly inform you if the callback has been executed.
It serves as a direct replacement for the current runOnUI.

Example usage

import { scheduleOnUI } from 'react-native-worklets';

// RN Runtime, JS thread

scheduleOnUI((): void => {
  console.log('Hello from UI!');
});

runOnUIAsync

A function that schedules a worklet on the UI Runtime, to be executed on the UI thread. It returns a Promise of the worklet's return value. The Promise is resolved asynchronously, not immediately after the callback execution.

Example usage

import { runOnUIAsync } from 'react-native-worklets';

// RN Runtime, JS thread

const result: Promise<number> = runOnUIAsync((): number => {
  return 42;
});

await result; // 42

runOnUISync

A function that executes a worklet synchronously on the UI Runtime on the current thread. It might preempt the UI Runtime from the UI thread, potentially being expensive. It returns the callback's return value.

Example usage

import { runOnUISync } from 'react-native-worklets';

// RN Runtime, JS thread

const result: number = runOnUISync((): number => {
  return 42;
});

console.log(result); // 42

scheduleOnRN

A function that schedules a worklet on the RN Runtime. The execution thread is decided by React Native, likely to be the JS thread. It doesn't return a value nor inform you directly whether the callback has been executed.

Example usage

import { scheduleOnRN, scheduleOnUI } from 'react-native-worklets';

// RN Runtime, JS thread

const callback = (): void => {
  console.log('Welcome back to RN!');
};

scheduleOnUI(() => {
  scheduleOnRN(callback); // 'Welcome back to RN!'
});

runOnRNAsync

A function that schedules a worklet on the RN Runtime. It returns a Promise of the worklet's return value. The execution thread is decided by React Native, likely to be the JS thread. The Promise is resolved asynchronously, not immediately after the callback execution.

import { scheduleOnUI, runOnRNAsync } from 'react-native-worklets';

// RN Runtime, JS thread

const callback = (): number => {
  return 42;
};

scheduleOnUI(async (): void => {
  const result: Promise<number> = runOnRNAsync(callback);
  await result; // 42
});

runOnRNSync

A function that executes a worklet on the RN Runtime synchronously. It returns the callback's result. Execution may result in thread switching and preempting the RN Runtime, potentially being expensive.

import { scheduleOnUI, runOnRNSync } from 'react-native-worklets';

// RN Runtime, JS thread

const callback = (): number => {
  return 42;
};

scheduleOnUI((): number => {
  const result = runOnRNSync(callback); // 42
});

scheduleOnRuntime

A function that schedules a worklet on a given Worklet Runtime, which will be executed on its dedicated thread. It doesn't return a value nor informs you directly whether the callback has been executed or not. This function cannot target the RN Runtime or the UI Runtime.

import { createWorkletRuntime, scheduleOnRuntime } from 'react-native-worklets';

// RN Runtime, JS thread

const runtime = createWorkletRuntime();

scheduleOnRuntime(runtime, () => {
  console.log('Hello from Worklet Runtime!');
});

runOnRuntimeAsync

A function that schedules a worklet on a given Worklet Runtime to be executed on its dedicated thread. It returns a Promise of the worklet's return value. The Promise is resolved asynchronously, not immediately after the callback execution. This function cannot target the RN Runtime or the UI Runtime.

import { createWorkletRuntime, runOnRuntimeAsync } from 'react-native-worklets';

// RN Runtime, JS thread

const runtime = createWorkletRuntime();

const result: Promise<number> = runOnRuntimeAsync(runtime, (): number => {
  return 42;
});

await result; // 42

runOnRuntimeSync

A function that executes a worklet synchronously on a specified Worklet Runtime on the current thread. This might preempt the Worklet Runtime from its thread, potentially being expensive. It returns the callback's return value. This function cannot target the RN Runtime or the UI Runtime.

import { createWorkletRuntime, runOnRuntimeSync } from 'react-native-worklets';

// RN Runtime, JS thread

const runtime = createWorkletRuntime();

const result: number = runOnRuntimeSync(runtime, (): number => {
  return 42;
});

Passing arguments to worklets

The public methods described previously are designed for parameter-less worklets. This is the most common case for using worklets, a shorthand API. To use worklets with arguments or to memoize the callback, use the worklet API.

worklet

A function that creates a worklet from a provided function. The worklet can be called with arguments.

Example usage

import { worklet } from 'react-native-worklets';

// RN Runtime, JS thread

const callback = worklet((message: string) => {
  console.log(message);
});

callback.scheduleOnUI('Hello from UI!');

The key difference of calling a worklet with parameters compared to using implicit closure is that the worklet's closure is immutable. See the following comparison:

import { worklet } from 'react-native-worklets';

// RN Runtime, JS thread

let param = 42;

const closure = worklet(() => {
  console.log(param);
});

const withParameters = worklet((amount: number) => {
  console.log(amount);
});

closure.scheduleOnUI(); // 42
withParameters.scheduleOnUI(param); // 42

param = 24;

closure.scheduleOnUI(); // 42
withParameters.scheduleOnUI(param); // 24

Using worklet directly allows for efficient memoization:

import { useEffect, useMemo } from 'react';
import { scheduleOnUI, worklet } from 'react-native-worklets';

// RN Runtime, JS thread

function log() {
  console.log('Hello from log function!');
}

function Component() {
  useEffect(() => {
    // Creating a new instance of schedulable function each time.
    // Could be expensive, depending on how complex the function is.
    scheduleOnUI(log);
  });
  // ...
}

function OptimizedComponent() {
  const callback = useMemo(() => worklet(log), [log]);

  useEffect(() => {
    // Always calling the same instance of a schedulable function.
    // Well optimized.
    callback.scheduleOnUI(log);
  });
  // ...
}

Methods

• scheduleOnUI
• runOnUIAsync
• runOnUISync
• scheduleOnRN
• runOnRNAsync
• runOnRNSync
• scheduleOnRuntime
• runOnRuntimeAsync
• runOnRuntimeSync

The methods behave just like their previous respective counterparts.

Memory Sharing

Sharing memory between JavaScript runtimes is a complex topic; therefore, we'll focus only on discussing the key ideas relevant to the API. react-native-worklets introduces three key concepts, Serializables, Shareables and Synchronizables.

Shared Values (Mutables)

After thorough consideration, we decided that Shared Values will remain in Reanimated. They are objects specifically implemented for animations, creating a graph of inputs and outputs, which is irrelevant to multithreading. Instead, react-native-worklets will provide APIs that allow for implementing Shared Values and other objects that preserve a state across a given Worklet Runtime and are easily accessible from other Worklet Runtimes or the RN Runtime.

Serializable

A Serializable is an object that can be copied to Worklet Runtimes. It returns the reference to the Serializable. The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the Serializable. To prevent misconceptions about it we freeze the original value.

Memory model of Serializables.

createSerializable

A function that creates a Serializable from a given value. Conceptually, you don't need to use this function as react-native-worklets handles Serializable creation and management for you.

Example usage

import { createSerializable, scheduleOnUI } from 'react-native-worklets';

// RN Runtime, JS thread

const obj = { a: 42 };
// Note that creating the serializable explicitly here isn't necessary,
// it would be handled by `scheduleOnUI` automatically.
const serializable = createSerializable(obj);

// obj.a = 5; <-- error

scheduleOnUI(() => {
  console.log(serializable.a); // 42
});

For exotic use cases, you can create a Serializable that holds a value different from the original.

import { createSerializable, scheduleOnUI } from 'react-native-worklets';

// RN Runtime, JS thread

const obj = { a: 42 };
const serializable = createSerializable(obj, () => ({ a: 'Exotic use case' }));

console.log(obj.a); // 42

scheduleOnUI(() => {
  console.log(serializable.a); // "Exotic use case"
});

Shareable

A Shareable is an object which can be assigned to a specific Worklet Runtime, where it's shared across worklets. Accessing a Shareable on a runtime different from the assigned runtime means reading or modifying it on a different Worklet Runtime. A Shareable cannot hold a function.

Memory model of Shareables

createShareable

A function that creates a Shareable from a given value. It returns the reference to the Shareable.

A Shareable has the following methods:

• getAsync - returns a Promise of the value held by the Shareable, similar to runOn...Async functions.
• getSync - returns the value held by the Shareable, similar to runOn...Sync functions.
• setAsync - asynchronously sets the value of the Shareable on the Shareable's Worklet Runtime; similar scheduleOn... functions. You can pass a worklet as an argument to modify the Shareable in place efficiently.
• setSync - synchronously sets the value of Shareable on the Shareable's Worklet Runtime; similar to runOn...Sync functions. You can pass a worklet as an argument to modify the Shareable in place efficiently.

A Shareable can be initiated with a value or an initializer worklet, which runs on the assigned Worklet Runtime.

Example usage

import { createShareable, UIRuntime } from 'react-native-worklets';

// RN Runtime, JS thread

const shareable = createShareable(UIRuntime, 42);
console.log(shareable.getSync()); // 42

shareable.setAsync(24);

const value = await shareable.getAsync();
console.log(value); // 24

Possible flow of the Shareable example usage snippet.

Modifying in place

import { createShareable, UIRuntime } from 'react-native-worklets';

// RN Runtime, JS thread

const shareable = createShareable(UIRuntime, [1,2,3,4]);
console.log(shareable.getSync()); // [1,2,3,4]

shareable.setAsync((prev) => {
    prev.push(5);
    // Returning the same reference guarantees modifying in place.
    return prev;
});

const value = await shareable.getAsync();
console.log(value); // [1,2,3,4,5];

To understand the key differences between Serializables and Shareables, consider the following example:

import {
  createShareable,
  createSerializable,
  scheduleOnUI,
} from 'react-native-worklets';

// RN Runtime, JS thread

const shareable = createShareable(UIRuntime, 'shareable');
const name = 'serializable';
const serializable = createSerializable(name);

scheduleOnUI(() => {
  console.log(shareable.getSync()); // "shareable"
  console.log(serializable); // "serializable"

  shareable.setSync('modified shareable');
  serializable = 'modified serializable';
  console.log(shareable.getSync()); // "modified shareable"
  console.log(serializable); // "modified serializable"
});

scheduleOnUI(() => {
  // Changes to `shareable` are persistent across worklets
  console.log(shareable.getSync()); // "modified shareable"
  // Changes to `serializable` do not persist and are local to each worklet
  console.log(serializable); // "serializable"
});

// Using `getAsync` to ensure that the changes have been applied.
const modifiedShareable = shareable.getAsync();
await modifiedShareable;

console.log(name); // "serializable"
console.log(modifiedShareable); // "modified shareable"

Synchronizable

A Synchronizable is a shared memory not tied to any JavaScript Runtime. It can be accessed from any JavaScript Runtime and C++. The type of the value cannot be changed. It can be obtained exclusively or non-exclusively, therefore trying to access it from multiple threads at once could lead to blocking.

Synchronizable is an advanced concept. It's useful when you need to access shared memory from C++ often, as it doesn't need to do intermediate calls to JavaScript. If you mainly need access in JavaScript, use a Shareable instead for better performance.

Memory model of Synchronizables.

A Synchronizable has the following methods:

• getBlocking - exclusively obtains the Synchronizable and returns its value, potentially blocking if either setDirty or setBlocking are being executed on another thread.
• getDirty - non-exclusively obtains the Synchronizable and returns its value. It never blocks, even if either setDirty or setBlocking are being executed on another thread, therefore could result in a dirty read.
• setBlocking - exclusively obtains the Synchronizable and sets it to the provided value, potentially blocking if either getBlocking, setBlocking or setDirty are being executed on another thread.
• setDirty - non-exclusively obtains the Synchronizable and sets it to the provided value, potentially blocking if either getBlocking or setBlocking are being executed on another thread. It doesn't block when setDirty is executed on another thread, therefore could result in a lost update.

createSynchronizable

A function that creates a Synchronizable from a given value. It returns the reference to the Synchronizable.

Example usage

import { createSynchronizable, scheduleOnUI } from 'react-native-worklets';

// RN Runtime, JS thread

const synchronizable = createSynchronizable({a: 42});

scheduleOnUI(() => {
    // Note that it's still possible for `getBlocking` to be
    // executed before `setDirty` and get "{a: 42}" instead.
    const value = synchronizable.getBlocking();
    console.log(value); // {a: 24}
});

// Will most likely be executed before `getBlocking`.
synchronizable.setDirty({a: 24});

Possible flow of the Synchronizable example usage snippet. Scheduling part was omitted.

Runtimes

Our community has asked us for more granular process of creating and managing the Worklet Runtimes. Therefore, we're overhauling the API for more specialized use cases. We'll follow the same pattern when expanding the native API of the Worklet Runtimes. Old API of createWorkletRuntime will be dropped and replaced with a new one.

createWorkletRuntime

A function that creates a Worklet Runtime, accordingly to a provided configuration.

The configuration object has the following properties:

• runtimeName - the name of the Runtime. Defaults to a UUID.
• initializer - initializer worklet which will be executed immediately on the Worklet Runtime creation. There's no initializer by default.
• queue - execution queue of the Worklet Runtime. By default react-native-worklets will create a new execution queue for the Runtime and spawn a dedicated thread to run the queue. You can either provide your own queue or opt-out and have no queue.
• threadName - the name of the dedicated thread. Only valid when queue is not set.
• locking - a boolean flag that decides whether the Worklet Runtime should be guarded by a mutex. Defaults to true. Only set it to false when you know what you're doing, as JavaScript runtimes aren't thread safe.
• builtins - an object defining what builtins react-native-worklets should provide to the Worklet Runtime out-of-the-box. By default only console and performance are provided.

Example usage

import { createWorkletRuntime, scheduleOnRuntime } from 'react-native-worklets';

const runtime = createWorkletRuntime({
  runtimeName: 'MyHappyRuntime',
  initializer: () => {
    globalThis.isInitialized = true;
  },
  threadName: 'MyHappyThread',
  builtins: {
    console: true,
    performance: false,
  },
});

scheduleOnRuntime(runtime, () => {
  console.log(globalThis.isInitialized); // true
}); 

Events

While handling native events synchronously - like screen taps - is one of the key features of react-native-worklets, we plan to preserve all event handling APIs (useEvent etc.) in react-native-reanimated. The existing JavaScript implementation of event handling is very (React) component-specific, and initially react-native-worklets should not inherit any component-specific code. However, we are open to discussing this feature in the future iterations of react-native-worklets.

Reanimated Babel plugin

Renamed to Worklets Babel plugin, available to import from react-native-worklets. For convenience it's reexported from react-native-reanimated but with a meaningful deprecation message.

Future

With react-native-worklets as a separate library, not tied to animations, we can finally work on adding more features to it.

• Defining the native APIs.
• Defining the event loop of the UI Runtime.
• Elaborate documentation on the multithreading model.
• Symmetric behavior between Worklet Runtimes, i.e. bringing optimizations specific to UI Runtime to other Worklet Runtimes.
• Running 3rd party libraries on Worklet Runtimes.
• Decreasing the impact of the Worklets Babel Plugin on the bundle size.

Afterword

This document will be a cornerstone of the future react-native-worklets documentation. If you're interested in how some concepts work under the hood, feel free to ask questions. If an explanation of some intricacy is valuable for the user, we'd gladly add it to the documentation.

[andrew-tandem]

Would being able to do things like storage access (sqlite, react-native-mmkv) and making HTTP calls be something that would be considered for support in the future?

[tjzel]

That's the idea. Making HTTP requests isn't available in bare Hermes instance, so this would probably be an optional builtin provided by react-native-worklets.

[ex3ndr]

One of the most complicated things in RN development is freeing main event loop, which often includes all kind of operations except the UI. For example, download and parse a sizable JSON, merging it into the some kind of store (and diffing to make react perform), writing to disk, etc - the only way right now is to move to native.

The Web Worker model would be perfect - keeps a lot of flexibility, it is still a single file as worklets.

The perfect threading would be:

• UI Thread for complex animations and layouting (reaction time is 8ms)
• JS Main Thread - for react and basic state (should be snappy, but 100ms is acceptable (maximum reaction time for button press)
• Worker Thread - can be blocked for a while, wont affect the visible performance anywhere and can crunch data as it wish, syncing data, storing data, etc.

[tjzel]

The inherent difference between Web Workers and Worklet API is that Web Workers are based on whole files while worklets are functions (closures). For the time being we want to stay with worklets, since it's the API we already have and there's still a lot of features to implement. Still, all the operations you described will be achievable within the API. You can create as many Worker Threads as you want, the only bottleneck for you would be how you synchronize with the data.

[MaxRobertsDear]

@tjzel thanks for the document you put together. This is exciting to see!

And thanks to @ex3ndr for the clarifying question.

At risk of coming across as ignorant, I have a perhaps naive follow up to the provided example

Worker Thread - can be blocked for a while, wont affect the visible performance anywhere

What actually is a worker thread?

Coming from a RN background and toggling the performance monitor on the iOS simulator / Android emulator, we're only ever shown the frame rate for the JS and UI threads.

What I'm gleaning from this discussion is that we'd be able to spawn a JS runtime that is on a thread that is not the UI or JS thread but a distinct dedicated worklet thread. This understanding is also informed by the following definition of the worklet runtime

A JavaScript runtime spawned by react-native-worklets. that are pre-configured to be able to execute worklets. It isn't coupled to any thread, but there might be a thread dedicated to its execution.

So is the spawned runtime handled by a new thread that is neither the JS or UI thread but a new dedicated worker thread? Can this be explicitly set? Thanks in advance. Trying to update my mental model (your above diagrams have been a great help @tjzel !)

[tjzel]

@MaxRobertsDear Yes, you will be able to spawn multiple runtimes and multiple threads and set them explicitly. I think you grasped everything perfectly.

[hkochniss]

on the Web we have the concept of transferable objects for worker <-> main thread data transfer of e.g. large arrays in O(1) (see the section in the link regarding zero-copy operation for ArrayBuffers), as basically ownership (and just a pointer) is transferred.

As my usecase (something akin to crossfilter.js but in RN on the native layer) requires transfer of potentially very large data arrays (of numbers) to the worklet, is this already solved with the concepts introduced here? It seems so, but like to know for sure (otherwise something like transferable objects would be my request)

[tjzel]

I'm not sure but I think transferable objects like ArrayBuffers are already implemented according to spec in the Hermes engine, so you could use them in your case. If you'd like for e.g. "standard" arrays to be transferable like this, I think it would have to be implemented in the engine itself and it's not much we can do as a library.

[hkochniss]

Ok maybe I'm just confused and have to try it out, there are several algo variants here, and the bottleneck in the end is the per-frame "UI input -> worklet -> big compute -> UI Chart" update latency (ideally 60+ FPS). So any tips on minimzing the Gesture Handler update -> worklet -> UI thread latency with this (proposed) library would be helpful. The rest is experimentation on my side

[fatihkayan20]

I have to sync bunch of data from Apple health kit to my database. For this use case fps drops sometimes. Is this good usage for that?

[tjzel]

I haven't had any experience with Apple health kit, but if these are simple fetches, then absolutely!

[f0rdream]

What's the difference between runOnUIAsync and scheduleOnUI? Looks like the only difference is that there's no returning value for scheduleOnUI. runOnUIAsync can be perfectly act as the alternative of previous runOnUI

[tjzel]

Yes, scheduleOnUI doesn't return the promise - this is a useful optimization, as there's no need to pass the promise resolver function between runtimes which saves on unnecessary copies of memory.

[BoBoooooo]

It seems like Reanimated is working on react-native-worklets

[lucaswitch]

This could elevate the React Native ecosystem to a whole new level.
In my case, I'm rendering real-time charts using D3 with Skia. The workload is mostly CPU-bound, as the actual rendering is done by Skia(i expect it to be IO bound mostly), which is quite efficient.

It would benefit everyone if Hermes supported a built-in worker thread model—similar to the one that works out of the box in Node.js.