mirror of
https://github.com/facebook/react-native.git
synced 2025-11-01 09:14:26 +00:00
Prettify markdown files in __docs__ (#50587)
Summary: Pull Request resolved: https://github.com/facebook/react-native/pull/50587 Changelog: [internal] This does an initial formatting of all Markdown files that are going to be formatted by prettier from now on. Reviewed By: lenaic Differential Revision: D72706240 fbshipit-source-id: b365a94e5d74945a121966fddcb43776ebc534e0
This commit is contained in:
Rubén Norte
committed by
Facebook GitHub Bot
Facebook GitHub Bot
parent
c97af95a7f
commit
97d6442a7d
+55
-20
@@ -5,55 +5,90 @@ _This is a document about documentation (hence the file name)._
|
||||
## Motivation
|
||||
|
||||
The goals of this documentation are:
|
||||
1. To make it easier for people to understand and contribute to the React Native architecture.
|
||||
2. To ensure the architecture is easy to maintain, with clearly scoped subsystems that are easy to reason about and change.
|
||||
|
||||
1. To make it easier for people to understand and contribute to the React Native
|
||||
architecture.
|
||||
2. To ensure the architecture is easy to maintain, with clearly scoped
|
||||
subsystems that are easy to reason about and change.
|
||||
|
||||
## Strategy
|
||||
|
||||
Our documentation supports the following use cases:
|
||||
1. [Exploration based] I want to understand how React Native works and learn about its different parts. I want to explore.
|
||||
2. [Goal based] I want to solve a problem and change something specific, so I want to understand what I should change and how the system I need to change works. I need to understand how other systems depend on this.
|
||||
|
||||
To support the first case, we provide a single entrypoint for the whole documentation, which will be the first step in a tree of docs with links to parents and children:
|
||||
1. (Exploration based) I want to understand how React Native works and learn
|
||||
about its different parts. I want to explore.
|
||||
2. (Goal based) I want to solve a problem and change something specific, so I
|
||||
want to understand what I should change and how the system I need to change
|
||||
works. I need to understand how other systems depend on this.
|
||||
|
||||
To support the first case, we provide a single entrypoint for the whole
|
||||
documentation, which will be the first step in a tree of docs with links to
|
||||
parents and children:
|
||||
|
||||
- `<root>/__docs__/README.md` (with links to subsystems 1, 2, etc.)
|
||||
- `Subsystem 1/__docs__/README.md` (with links to root and subsystems 1.1, 1.2, etc.)
|
||||
- `Subsystem 1.1/__docs__/README.md` (with links to subsystem 1 and subsystems 1.1.1, 1.1.2, etc.)
|
||||
- `Subsystem 1/__docs__/README.md` (with links to root and subsystems 1.1,
|
||||
1.2, etc.)
|
||||
- `Subsystem 1.1/__docs__/README.md` (with links to subsystem 1 and
|
||||
subsystems 1.1.1, 1.1.2, etc.)
|
||||
- `Subsystem 1.2/__docs__/README.md`
|
||||
- `Subsystem 2/__docs__/README.md`
|
||||
|
||||
This structure will make it possible for the user to navigate across the documentation organically, just following links within the documents themselves.
|
||||
This structure will make it possible for the user to navigate across the
|
||||
documentation organically, just following links within the documents themselves.
|
||||
|
||||
To support the second use case, focusing on a specific subsystem, we will describe what are the relationships between that subsystem and others, to make sure that changes to its API are understood, and that usages of other subsystems are considered.
|
||||
To support the second use case, focusing on a specific subsystem, we will
|
||||
describe what are the relationships between that subsystem and others, to make
|
||||
sure that changes to its API are understood, and that usages of other subsystems
|
||||
are considered.
|
||||
|
||||
The use of the `__docs__` directory (inspired by Python) has 2 goals:
|
||||
1. Make the documentation easy to find in the directory, by generally appearing at the top of the directory (similar to `__tests__`).
|
||||
|
||||
1. Make the documentation easy to find in the directory, by generally appearing
|
||||
at the top of the directory (similar to `__tests__`).
|
||||
2. Grouping the documentation itself and its assets (images, diagrams, etc.).
|
||||
|
||||
## Guidelines
|
||||
|
||||
### Content
|
||||
|
||||
Use [this template](./README-template.md) to write the documentation for a subsystem, adding the appropriate subsections depending on what that documentation requires. Only diverge from this structure if it is strictly necessary (removing unnecessary or empty sections is fine).
|
||||
Use [this template](./README-template.md) to write the documentation for a
|
||||
subsystem, adding the appropriate subsections depending on what that
|
||||
documentation requires. Only diverge from this structure if it is strictly
|
||||
necessary (removing unnecessary or empty sections is fine).
|
||||
|
||||
Include supporting images and diagrams in the documentation. Those assets should be placed in the same `__docs__` directory as the `README.md` file. Use relative paths to link to the assets in those directories.
|
||||
Include supporting images and diagrams in the documentation. Those assets should
|
||||
be placed in the same `__docs__` directory as the `README.md` file. Use relative
|
||||
paths to link to the assets in those directories.
|
||||
|
||||
If you include Excalidraw diagrams, make sure to export an SVG image from the website using the "Embedded scene" option, so the original diagram is included in the file and can be re-uploaded to Excalidraw for future modifications. Use the extension `.excalidraw.svg` to signal this.
|
||||
If you include Excalidraw diagrams, make sure to export an SVG image from the
|
||||
website using the "Embedded scene" option, so the original diagram is included
|
||||
in the file and can be re-uploaded to Excalidraw for future modifications. Use
|
||||
the extension `.excalidraw.svg` to signal this.
|
||||
|
||||
### Granularity
|
||||
|
||||
The level of granularity in the definition of the subsystems should be enough to correctly describe how React Native works, but not so detailed that any changes in the code require changes in the documentation.
|
||||
The level of granularity in the definition of the subsystems should be enough to
|
||||
correctly describe how React Native works, but not so detailed that any changes
|
||||
in the code require changes in the documentation.
|
||||
|
||||
Examples:
|
||||
|
||||
- Requires updating the docs:
|
||||
- Adding a new major feature or API.
|
||||
- Adding a new relevant dependency. Adding a dependency to helper functions does not count as relevant.
|
||||
- Adding a new relevant dependency. Adding a dependency to helper functions
|
||||
does not count as relevant.
|
||||
- Does NOT require updating the docs:
|
||||
- Internal implementation details that do not change how the system works or interacts with others.
|
||||
- Internal implementation details that do not change how the system works or
|
||||
interacts with others.
|
||||
- Making a minor API or feature change.
|
||||
- Internal refactors, even if they create new modules or introduce dependencies to external helpers.
|
||||
- Internal refactors, even if they create new modules or introduce
|
||||
dependencies to external helpers.
|
||||
|
||||
### Location
|
||||
|
||||
When a specific subsystem exists in multiple directories (e.g.: platform-specific ones, C++, JavaScript, etc.):
|
||||
1. Choose one of them to place the canonical documentation (in order of preference, JavaScript -> C++ -> platform).
|
||||
2. Create specific files in the rest linking to the canonical one.
|
||||
When a specific subsystem exists in multiple directories (e.g.:
|
||||
platform-specific ones, C++, JavaScript, etc.):
|
||||
|
||||
1. Choose one of them to place the canonical documentation (in order of
|
||||
preference, JavaScript -> C++ -> platform).
|
||||
2. Create specific files in the rest linking to the canonical one.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# _Subsystem name_
|
||||
|
||||
* [Main doc](../__docs__/README.md)
|
||||
- [Main doc](../__docs__/README.md)
|
||||
|
||||
_Description of the subsystem with the necessary context._
|
||||
|
||||
@@ -10,22 +10,27 @@ _Explanation of how the subsystem is used._
|
||||
|
||||
## Design
|
||||
|
||||
_Explain how the subsystem is designed, relevant implementation details, etc. Ideally include an Excalidraw diagram._
|
||||
_Explain how the subsystem is designed, relevant implementation details, etc.
|
||||
Ideally include an Excalidraw diagram._
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
### Part of
|
||||
|
||||
- _A single bullet for the parent subsystem. Link to the documentation of that subsystem if it exists._
|
||||
- _A single bullet for the parent subsystem. Link to the documentation of that
|
||||
subsystem if it exists._
|
||||
|
||||
### Part of this
|
||||
|
||||
- _One bullet point for each subsystem that is part of this one. Link to the documentation of those subsystems if it exists._
|
||||
- _One bullet point for each subsystem that is part of this one. Link to the
|
||||
documentation of those subsystems if it exists._
|
||||
|
||||
### Used by this
|
||||
|
||||
- _One bullet point for each subsystem used by this one, explaining why it uses it and how. Link to the documentation of those subsystems if it exists._
|
||||
- _One bullet point for each subsystem used by this one, explaining why it uses
|
||||
it and how. Link to the documentation of those subsystems if it exists._
|
||||
|
||||
### Uses this
|
||||
|
||||
- _One bullet point for each subsystem using this one, explaining why it uses it and how. Link to the documentation of those subsystems if it exists._
|
||||
- _One bullet point for each subsystem using this one, explaining why it uses it
|
||||
and how. Link to the documentation of those subsystems if it exists._
|
||||
|
||||
+25
-8
@@ -1,20 +1,34 @@
|
||||
# React Native Technical Documentation
|
||||
|
||||
The React Native technical documentation describes how React Native works internally, the subsystems it is composed of, how they work and how they interact with each other.
|
||||
The React Native technical documentation describes how React Native works
|
||||
internally, the subsystems it is composed of, how they work and how they
|
||||
interact with each other.
|
||||
|
||||
The intended audience is people who want to learn about the internals of React Native and contribute to it. **End users of React Native are meant to use the [public website](https://reactnative.dev) instead** (its code can be found [here](https://github.com/facebook/react-native-website)).
|
||||
The intended audience is people who want to learn about the internals of React
|
||||
Native and contribute to it. **End users of React Native are meant to use the
|
||||
[public website](https://reactnative.dev) instead** (its code can be found
|
||||
[here](https://github.com/facebook/react-native-website)).
|
||||
|
||||
For details on how we approach technical documentation in this repository, see [GUIDELINES.md](./GUIDELINES.md).
|
||||
For details on how we approach technical documentation in this repository, see
|
||||
[GUIDELINES.md](./GUIDELINES.md).
|
||||
|
||||
## Usage
|
||||
|
||||
This repository is not meant to be consumed directly by end users. Instead, it creates several packages that are published to the NPM registry for direct consumption by end users and frameworks.
|
||||
This repository is not meant to be consumed directly by end users. Instead, it
|
||||
creates several packages that are published to the NPM registry for direct
|
||||
consumption by end users and frameworks.
|
||||
|
||||
This repository uses a monorepo approach, and public packages can be found in the [`packages`](../packages/) directory (the ones that do not contain `"private": true` in their `package.json` file).
|
||||
This repository uses a monorepo approach, and public packages can be found in
|
||||
the [`packages`](../packages/) directory (the ones that do not contain
|
||||
`"private": true` in their `package.json` file).
|
||||
|
||||
The most important package is the [`react-native`](https://www.npmjs.com/package/react-native) package, located in [`packages/react-native`](../packages/react-native), which contains the public JavaScript API.
|
||||
The most important package is the
|
||||
[`react-native`](https://www.npmjs.com/package/react-native) package, located in
|
||||
[`packages/react-native`](../packages/react-native), which contains the public
|
||||
JavaScript API.
|
||||
|
||||
This repository provides the Android and iOS versions of React Native. Versions for other platforms are maintained in their own repositories.
|
||||
This repository provides the Android and iOS versions of React Native. Versions
|
||||
for other platforms are maintained in their own repositories.
|
||||
|
||||
## Design
|
||||
|
||||
@@ -80,11 +94,14 @@ TODO: Explain the different components of React Native at a high level.
|
||||
|
||||
### Used by this
|
||||
|
||||
This repository has many different types of dependencies: build systems, external packages to be used during development, external packages used at runtime, etc.
|
||||
This repository has many different types of dependencies: build systems,
|
||||
external packages to be used during development, external packages used at
|
||||
runtime, etc.
|
||||
|
||||
### Uses this
|
||||
|
||||
The main use cases for this repository are:
|
||||
|
||||
1. Developing React Native itself.
|
||||
2. Testing and releasing React Native.
|
||||
3. Synchronizing forks like `react-native-windows` and `react-native-macos`.
|
||||
|
||||
+6
-3
@@ -1,8 +1,9 @@
|
||||
# Android event dispatching
|
||||
|
||||
* [Main doc](../../../../../../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains Kotlin classes specific to Android event dispatching in the new architecture.
|
||||
This directory contains Kotlin classes specific to Android event dispatching in
|
||||
the new architecture.
|
||||
|
||||
## Design
|
||||
|
||||
@@ -16,4 +17,6 @@ This directory contains Kotlin classes specific to Android event dispatching in
|
||||
|
||||
### Used by this
|
||||
|
||||
This component is tightly coupled with the legacy event dispatch mechanism. Some of the interfaces and components live in the com.facebook.react.uimanager.events package so that they may reference internal API's.
|
||||
This component is tightly coupled with the legacy event dispatch mechanism. Some
|
||||
of the interfaces and components live in the com.facebook.react.uimanager.events
|
||||
package so that they may reference internal API's.
|
||||
|
||||
+3
-2
@@ -1,8 +1,9 @@
|
||||
# Feature Flags
|
||||
|
||||
* [Main doc](../../../../../../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the Java/Kotlin bindings for the internal React Native feature flags system.
|
||||
This directory contains the Java/Kotlin bindings for the internal React Native
|
||||
feature flags system.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
# Feature Flags
|
||||
|
||||
* [Main doc](../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the shared C++ implementation of the internal React Native feature flags system.
|
||||
This directory contains the shared C++ implementation of the internal React
|
||||
Native feature flags system.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
+3
-2
@@ -1,8 +1,9 @@
|
||||
# Feature Flags
|
||||
|
||||
* [Main doc](../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the native C++ TurboModule for the internal React Native feature flags system.
|
||||
This directory contains the native C++ TurboModule for the internal React Native
|
||||
feature flags system.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
+4
-2
@@ -1,8 +1,10 @@
|
||||
# IntersectionObserver
|
||||
|
||||
* [Main doc](../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the native module used by the [IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) in React Native.
|
||||
This directory contains the native module used by the
|
||||
[IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)
|
||||
in React Native.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
# Microtasks
|
||||
|
||||
* [Main doc](../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the native module used to implement `queueMicrotask` in React Native, which schedules microtasks in the [Event Loop](../../../renderer/runtimescheduler/__docs__/README.md).
|
||||
This directory contains the native module used to implement `queueMicrotask` in
|
||||
React Native, which schedules microtasks in the
|
||||
[Event Loop](../../../renderer/runtimescheduler/__docs__/README.md).
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
+4
-2
@@ -1,8 +1,10 @@
|
||||
# MutationObserver
|
||||
|
||||
* [Main doc](../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the native module used by the [MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) in React Native.
|
||||
This directory contains the native module used by the
|
||||
[MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
|
||||
in React Native.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
+4
-2
@@ -1,8 +1,10 @@
|
||||
# IntersectionObserver
|
||||
|
||||
* [Main doc](../../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the C++ implementation of the [IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) in React Native.
|
||||
This directory contains the C++ implementation of the
|
||||
[IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)
|
||||
in React Native.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
+4
-2
@@ -1,8 +1,10 @@
|
||||
# MutationObserver
|
||||
|
||||
* [Main doc](../../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the C++ implementation of the [MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) in React Native.
|
||||
This directory contains the C++ implementation of the
|
||||
[MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
|
||||
in React Native.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
+113
-43
@@ -1,32 +1,59 @@
|
||||
# Event Loop
|
||||
|
||||
* [Main doc](../__docs__/README.md)
|
||||
- [Main doc](../__docs__/README.md)
|
||||
|
||||
The Event Loop is the formalization of the execution model for JavaScript in React Native, and how that model synchronizes with rendering work in the host platform.
|
||||
The Event Loop is the formalization of the execution model for JavaScript in
|
||||
React Native, and how that model synchronizes with rendering work in the host
|
||||
platform.
|
||||
|
||||
Its main goals are:
|
||||
- To make the behavior of the framework more predictable, to help developers build more reliable and performant apps.
|
||||
- To increase the alignment with Web specifications, to simplify the adoption of Web APIs in React Native.
|
||||
- [Secondary] Provide a solid foundation for general performance optimizations relying on better scheduling or sequencing.
|
||||
|
||||
The implementation of the event loop in React Native is aligned with [its definition in the HTML specification](https://html.spec.whatwg.org/multipage/webappapis.html#event-loop-processing-model). React Native only implements a subset of it, in order to support its existing semantics and APIs.
|
||||
- To make the behavior of the framework more predictable, to help developers
|
||||
build more reliable and performant apps.
|
||||
- To increase the alignment with Web specifications, to simplify the adoption of
|
||||
Web APIs in React Native.
|
||||
- (Secondary) Provide a solid foundation for general performance optimizations
|
||||
relying on better scheduling or sequencing.
|
||||
|
||||
> [!NOTE]
|
||||
> The Event Loop in React Native was originally proposed in this [RFC](https://github.com/react-native-community/discussions-and-proposals/blob/main/proposals/0744-well-defined-event-loop.md), which contains additional context (e.g.: how this was introduced and what React Native had before).
|
||||
The implementation of the event loop in React Native is aligned with
|
||||
[its definition in the HTML specification](https://html.spec.whatwg.org/multipage/webappapis.html#event-loop-processing-model).
|
||||
React Native only implements a subset of it, in order to support its existing
|
||||
semantics and APIs.
|
||||
|
||||
> [!NOTE] The Event Loop in React Native was originally proposed in this
|
||||
> [RFC](https://github.com/react-native-community/discussions-and-proposals/blob/main/proposals/0744-well-defined-event-loop.md),
|
||||
> which contains additional context (e.g.: how this was introduced and what
|
||||
> React Native had before).
|
||||
|
||||
## Usage
|
||||
|
||||
The event loop is an implementation detail so it is not used directly, but several APIs integrate deeply with it:
|
||||
- State updates processed by React are scheduled to be flushed (rendered in the host platform) at the end of the current event loop tick.
|
||||
- Promises, `queueMicrotask` and APIs like `MutationObserver` add microtasks to the microtask queue, processed as part of the current event loop tick.
|
||||
- Timers and APIs like `requestIdleCallback` schedule tasks to be processed by the event loop. In the case of `requestIdleCallback`, the tasks are scheduled with specific priorities.
|
||||
- `PerformanceObserver` entries like `longtask` and `event` provide timing information about different parts of the event loop.
|
||||
The event loop is an implementation detail so it is not used directly, but
|
||||
several APIs integrate deeply with it:
|
||||
|
||||
- State updates processed by React are scheduled to be flushed (rendered in the
|
||||
host platform) at the end of the current event loop tick.
|
||||
- Promises, `queueMicrotask` and APIs like `MutationObserver` add microtasks to
|
||||
the microtask queue, processed as part of the current event loop tick.
|
||||
- Timers and APIs like `requestIdleCallback` schedule tasks to be processed by
|
||||
the event loop. In the case of `requestIdleCallback`, the tasks are scheduled
|
||||
with specific priorities.
|
||||
- `PerformanceObserver` entries like `longtask` and `event` provide timing
|
||||
information about different parts of the event loop.
|
||||
|
||||
One of the most important semantics of the event loop is the **atomicity of UI
|
||||
updates in tasks**. All changes to the UI triggered from JavaScript in a task
|
||||
(processing state updates in React, dispatching view commands, etc.) are always
|
||||
flushed together to the host platform, so the UI is never updated with partial
|
||||
work done within a task. For example:
|
||||
|
||||
One of the most important semantics of the event loop is the **atomicity of UI updates in tasks**. All changes to the UI triggered from JavaScript in a task (processing state updates in React, dispatching view commands, etc.) are always flushed together to the host platform, so the UI is never updated with partial work done within a task. For example:
|
||||
1. We dispatch an event to JavaScript and execute one or more event handlers.
|
||||
2. Those event handlers do one or more state updates in React. React schedules a microtask to process them.
|
||||
3. In a microtask, React processes all those state updates together, re-rendering the necessary components and committing at the end.
|
||||
4. As part of the commit, we might execute layout effects that might trigger more state updates. Those state updates are processed synchronously at the end of the commit.
|
||||
2. Those event handlers do one or more state updates in React. React schedules a
|
||||
microtask to process them.
|
||||
3. In a microtask, React processes all those state updates together,
|
||||
re-rendering the necessary components and committing at the end.
|
||||
4. As part of the commit, we might execute layout effects that might trigger
|
||||
more state updates. Those state updates are processed synchronously at the
|
||||
end of the commit.
|
||||
5. At the end of the current microtask, we execute the rest of the microtasks.
|
||||
6. When the microtask queue is empty, we flush all changes to the host platform.
|
||||
|
||||
@@ -38,14 +65,16 @@ function App(props) {
|
||||
|
||||
return (
|
||||
<>
|
||||
<Header onPressButton={(event) => {
|
||||
// A task executes all the event handlers.
|
||||
// The state update is processed in a microtask.
|
||||
setShowContent(true);
|
||||
}} />
|
||||
<Header
|
||||
onPressButton={event => {
|
||||
// A task executes all the event handlers.
|
||||
// The state update is processed in a microtask.
|
||||
setShowContent(true);
|
||||
}}
|
||||
/>
|
||||
{showContent ? <Content /> : null}
|
||||
</>
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
function Content(props) {
|
||||
@@ -70,9 +99,14 @@ function Content(props) {
|
||||
|
||||
## Design
|
||||
|
||||
The conceptual model is **aligned with [the model on the Web](https://html.spec.whatwg.org/multipage/webappapis.html#event-loop-processing-model)** (from which it borrows some concepts and steps), while **still benefiting from the React Native threading model**.
|
||||
The conceptual model is **aligned with
|
||||
[the model on the Web](https://html.spec.whatwg.org/multipage/webappapis.html#event-loop-processing-model)**
|
||||
(from which it borrows some concepts and steps), while **still benefiting from
|
||||
the React Native threading model**.
|
||||
|
||||
The event loop continuously goes through these steps (in what we refer to as an
|
||||
"event loop tick"):
|
||||
|
||||
The event loop continuously goes through these steps (in what we refer to as an "event loop tick"):
|
||||
1. Select the next task to execute among all tasks waiting for execution.
|
||||
2. Execute the selected task.
|
||||
3. Execute **all** scheduled microtasks.
|
||||
@@ -80,59 +114,95 @@ The event loop continuously goes through these steps (in what we refer to as an
|
||||
|
||||
|
||||
|
||||
One of the key benefits of this model is that each **event loop iteration represents an atomic UI update**. This helps reason about whether work scheduled within a specific task should be rendered together or not. If it is a step in the same task, scheduled as a microtask or one of the specific sub-steps in updating the rendering, then it will be atomic. Otherwise, if it was scheduled as a separate task (e.g.: using timers, native callbacks, etc.) it would constitute a separate UI update.
|
||||
One of the key benefits of this model is that each **event loop iteration
|
||||
represents an atomic UI update**. This helps reason about whether work scheduled
|
||||
within a specific task should be rendered together or not. If it is a step in
|
||||
the same task, scheduled as a microtask or one of the specific sub-steps in
|
||||
updating the rendering, then it will be atomic. Otherwise, if it was scheduled
|
||||
as a separate task (e.g.: using timers, native callbacks, etc.) it would
|
||||
constitute a separate UI update.
|
||||
|
||||
### Detailed steps
|
||||
|
||||
#### 1. Task selection
|
||||
|
||||
On the Web, task selection is an implementation detail left to browsers to decide.
|
||||
On the Web, task selection is an implementation detail left to browsers to
|
||||
decide.
|
||||
|
||||
In React Native, we rely on `RuntimeScheduler` for task selection, which already supports the execution of tasks with priorities. The criteria it uses is:
|
||||
1. If there are expired tasks, select expired tasks in the order in which they expired.
|
||||
2. Otherwise, select tasks by priority, in the order in which they were scheduled.
|
||||
In React Native, we rely on `RuntimeScheduler` for task selection, which already
|
||||
supports the execution of tasks with priorities. The criteria it uses is:
|
||||
|
||||
The Web specification defines the concept of task queues as a mechanism to ensure that certain types of tasks execute in a specific order (e.g.: events). React Native has the concept of event queue that serve the same purpose.
|
||||
1. If there are expired tasks, select expired tasks in the order in which they
|
||||
expired.
|
||||
2. Otherwise, select tasks by priority, in the order in which they were
|
||||
scheduled.
|
||||
|
||||
The Web specification defines the concept of task queues as a mechanism to
|
||||
ensure that certain types of tasks execute in a specific order (e.g.: events).
|
||||
React Native has the concept of event queue that serve the same purpose.
|
||||
|
||||
#### 2. Task execution
|
||||
|
||||
Task execution is calling the JavaScript function or C++ callback that is associated to the task that was scheduled.
|
||||
Task execution is calling the JavaScript function or C++ callback that is
|
||||
associated to the task that was scheduled.
|
||||
|
||||
#### 3. Microtask execution
|
||||
|
||||
In this step we drain the microtask queue, executing all the microtasks in order. A microtask can schedule additional microtasks, so incorrect product logic could lead to an infinite loop. This is expected and it is the same behavior as on the Web.
|
||||
In this step we drain the microtask queue, executing all the microtasks in
|
||||
order. A microtask can schedule additional microtasks, so incorrect product
|
||||
logic could lead to an infinite loop. This is expected and it is the same
|
||||
behavior as on the Web.
|
||||
|
||||
#### 4. Update the rendering
|
||||
|
||||
The last step is to check if the previous work produced any rendering updates (transactions produced by commits in React, or view commands being dispatched). If that is the case, it notifies the host platform that it should apply the necessary mutations to reach that state.
|
||||
The last step is to check if the previous work produced any rendering updates
|
||||
(transactions produced by commits in React, or view commands being dispatched).
|
||||
If that is the case, it notifies the host platform that it should apply the
|
||||
necessary mutations to reach that state.
|
||||
|
||||
In the future, this step could be extended to do more of the work that browsers do. For example, it could run resize observations and run resize observer callbacks, or update animations and run animation frame callbacks.
|
||||
In the future, this step could be extended to do more of the work that browsers
|
||||
do. For example, it could run resize observations and run resize observer
|
||||
callbacks, or update animations and run animation frame callbacks.
|
||||
|
||||
### Synchronous execution, events and rendering
|
||||
|
||||
The formalization of the event loop also allows the efficient implementation of synchronous events. Because the event loop defines the tick as an atomic unit of work that leads to a full UI update, we can also use it as the unit of work to be executed in the UI thread.
|
||||
The formalization of the event loop also allows the efficient implementation of
|
||||
synchronous events. Because the event loop defines the tick as an atomic unit of
|
||||
work that leads to a full UI update, we can also use it as the unit of work to
|
||||
be executed in the UI thread.
|
||||
|
||||
|
||||
|
||||
### Implementation
|
||||
|
||||
Most of the implementation of the event loop is done in the [`RuntimeScheduler`](../RuntimeScheduler.h) class (specifically in [`RuntimeScheduler_modern`](../RuntimeScheduler_Modern.h), which is the version used in the new architecture).
|
||||
Most of the implementation of the event loop is done in the
|
||||
[`RuntimeScheduler`](../RuntimeScheduler.h) class (specifically in
|
||||
[`RuntimeScheduler_modern`](../RuntimeScheduler_Modern.h), which is the version
|
||||
used in the new architecture).
|
||||
|
||||
That class implements both the task scheduler that handles priorities and the processing of those tasks within the event loop.
|
||||
That class implements both the task scheduler that handles priorities and the
|
||||
processing of those tasks within the event loop.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
### Part of this
|
||||
|
||||
- The implementation of [`queueMicrotask`](../../../nativemodule/microtasks/__docs__/README.md) to schedule microtasks in the event loop.
|
||||
- The implementation of
|
||||
[`queueMicrotask`](../../../nativemodule/microtasks/__docs__/README.md) to
|
||||
schedule microtasks in the event loop.
|
||||
|
||||
### Used by this
|
||||
|
||||
- React timing primitives, to do time measurements of the execution of certain parts of the event loop to integrate with `PerformanceObserver`.
|
||||
- React timing primitives, to do time measurements of the execution of certain
|
||||
parts of the event loop to integrate with `PerformanceObserver`.
|
||||
- Indirectly, it reports long tasks and event timing to `PerformanceObserver`.
|
||||
- It also integrates with the React Native DevTools tracing infrastructure to report the timing of tasks.
|
||||
- It also integrates with the React Native DevTools tracing infrastructure to
|
||||
report the timing of tasks.
|
||||
|
||||
### Uses this
|
||||
|
||||
- [MutationObserver](../../../../../src/private/webapis/mutationobserver/__docs__/README.md) uses the event loop to schedule mutation observer callbacks as microtasks.
|
||||
- `Scheduler` integrates with the event loop to register reporters (for `PerformanceObserver`) and schedules the specific work to be done as part of the rendering updates.
|
||||
- [MutationObserver](../../../../../src/private/webapis/mutationobserver/__docs__/README.md)
|
||||
uses the event loop to schedule mutation observer callbacks as microtasks.
|
||||
- `Scheduler` integrates with the event loop to register reporters (for
|
||||
`PerformanceObserver`) and schedules the specific work to be done as part of
|
||||
the rendering updates.
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
# Feature Flags
|
||||
|
||||
* [Main doc](../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the flag definitions and codegen for the internal React Native feature flags system.
|
||||
This directory contains the flag definitions and codegen for the internal React
|
||||
Native feature flags system.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
|
||||
@@ -1,15 +1,16 @@
|
||||
# Feature Flags
|
||||
|
||||
* [Main doc](../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../__docs__/README.md)
|
||||
|
||||
Feature flags are values that determine the behavior of specific parts of React
|
||||
Native. This directory contains the configuration for those values, and scripts
|
||||
to generate files for different languages to access and customize them.
|
||||
|
||||
There are 2 types of feature flags:
|
||||
* Common: can be accessed from any language and they provide consistent values
|
||||
everywhere.
|
||||
* JS-only: they can only be accessed and customized from JavaScript.
|
||||
|
||||
- Common: can be accessed from any language and they provide consistent values
|
||||
everywhere.
|
||||
- JS-only: they can only be accessed and customized from JavaScript.
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -19,26 +20,26 @@ The source of truth for the definition of the flags is the file
|
||||
`ReactNativeFeatureFlags.config.js` in this directory.
|
||||
|
||||
Example contents:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
common: {
|
||||
enableNativeBehavior: {
|
||||
description: 'Enable some behavior both in native and in JS.',
|
||||
defaultValue: false
|
||||
}
|
||||
defaultValue: false,
|
||||
},
|
||||
},
|
||||
jsOnly: {
|
||||
enableJSBehavior: {
|
||||
description: 'Enables some behavior in the JS layer.',
|
||||
defaultValue: false
|
||||
}
|
||||
}
|
||||
defaultValue: false,
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
**After any change to these definitions**, the code that provides access to them
|
||||
must be regenerated running this from the `react-native`
|
||||
repository:
|
||||
must be regenerated running this from the `react-native` repository:
|
||||
|
||||
```shell
|
||||
yarn featureflags --update
|
||||
@@ -51,10 +52,10 @@ the `ReactNativeFeatureFlags` interface (available in C++/Objective-C++,
|
||||
Kotlin/Java and JavaScript). JS-only feature flags can only be accessed from
|
||||
JavaScript.
|
||||
|
||||
**Accessing feature flags should be considered fast for all use cases**.
|
||||
Feature flags are cached at every layer, which prevents having to go through JNI
|
||||
when accessing the values from Kotlin and through JSI when accessing the values
|
||||
from JavaScript.
|
||||
**Accessing feature flags should be considered fast for all use cases**. Feature
|
||||
flags are cached at every layer, which prevents having to go through JNI when
|
||||
accessing the values from Kotlin and through JSI when accessing the values from
|
||||
JavaScript.
|
||||
|
||||
#### C++ / Objective-C
|
||||
|
||||
@@ -147,12 +148,13 @@ ReactNativeFeatureFlags.override({
|
||||
## Design
|
||||
|
||||
The architecture of this feature flags system can be described as follows:
|
||||
* A shared C++ core, where we provide access to the flags and allow
|
||||
customizations.
|
||||
* A Kotlin/Java interface that allows accessing and customizing the values in
|
||||
the C++ core (via JNI).
|
||||
* A JavaScript interface that allows accessing the common values (via a native
|
||||
module) and accessing and customizing the JS-only values.
|
||||
|
||||
- A shared C++ core, where we provide access to the flags and allow
|
||||
customizations.
|
||||
- A Kotlin/Java interface that allows accessing and customizing the values in
|
||||
the C++ core (via JNI).
|
||||
- A JavaScript interface that allows accessing the common values (via a native
|
||||
module) and accessing and customizing the JS-only values.
|
||||
|
||||
|
||||
|
||||
@@ -167,8 +169,10 @@ module) and accessing and customizing the JS-only values.
|
||||
|
||||
### Used by this
|
||||
|
||||
- The only dependency is the C++ TurboModule infrastructure (including codegen), as the JavaScript API uses it to access the feature flag values from native.
|
||||
- The only dependency is the C++ TurboModule infrastructure (including codegen),
|
||||
as the JavaScript API uses it to access the feature flag values from native.
|
||||
|
||||
### Uses this
|
||||
|
||||
This system is used extensively throughout the codebase and it evolves over time as feature flags are added or cleaned up.
|
||||
This system is used extensively throughout the codebase and it evolves over time
|
||||
as feature flags are added or cleaned up.
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# IntersectionObserver
|
||||
|
||||
* [Main doc](../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the React Native implementation of the [IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver).
|
||||
This directory contains the React Native implementation of the
|
||||
[IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver).
|
||||
|
||||
## Usage
|
||||
|
||||
`IntersectionObserver` is meant to be used from JavaScript, exposed as a global class.
|
||||
`IntersectionObserver` is meant to be used from JavaScript, exposed as a global
|
||||
class.
|
||||
|
||||
## Design
|
||||
|
||||
@@ -14,11 +16,21 @@ This is the high-level design of the IntersectionObserver API:
|
||||
|
||||
|
||||
|
||||
The global `IntersectionObserver` class is defined in JavaScript and it does its setup using a native module.
|
||||
The global `IntersectionObserver` class is defined in JavaScript and it does its
|
||||
setup using a native module.
|
||||
|
||||
In native, it uses mount hooks from `UIManager` to run intersection calculations and update the state of the observers. When a mount operation is reported from the host platform to `UIManager`, `UIManager` notifies the mount hook that triggers a check on the observers that are observing intersections on that surface. If the intersection triggers a state change, the notification is dispatched to the JavaScript observers.
|
||||
In native, it uses mount hooks from `UIManager` to run intersection calculations
|
||||
and update the state of the observers. When a mount operation is reported from
|
||||
the host platform to `UIManager`, `UIManager` notifies the mount hook that
|
||||
triggers a check on the observers that are observing intersections on that
|
||||
surface. If the intersection triggers a state change, the notification is
|
||||
dispatched to the JavaScript observers.
|
||||
|
||||
For the initial intersection notification (which is meant to report the state at the time of observation), this system checks if there are pending transactions for the given surface. If there are, we just wait for the transaction to be mounted and use the mount hook to report the initial notification. If there aren't, we dispatch the notification immediately.
|
||||
For the initial intersection notification (which is meant to report the state at
|
||||
the time of observation), this system checks if there are pending transactions
|
||||
for the given surface. If there are, we just wait for the transaction to be
|
||||
mounted and use the mount hook to report the initial notification. If there
|
||||
aren't, we dispatch the notification immediately.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
@@ -29,9 +41,12 @@ For the initial intersection notification (which is meant to report the state at
|
||||
|
||||
### Used by this
|
||||
|
||||
- This relies on mount hooks provided by `UIManager`, and on the information provided by the shadow tree registry provided by `UIManager` as well.
|
||||
- It uses the C++ TurboModule infra for communication between JavaScript and native.
|
||||
- This relies on mount hooks provided by `UIManager`, and on the information
|
||||
provided by the shadow tree registry provided by `UIManager` as well.
|
||||
- It uses the C++ TurboModule infra for communication between JavaScript and
|
||||
native.
|
||||
|
||||
### Uses this
|
||||
|
||||
- This is an API meant to be used by end users. It is not used directly but any other parts of the platform.
|
||||
- This is an API meant to be used by end users. It is not used directly but any
|
||||
other parts of the platform.
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# MutationObserver
|
||||
|
||||
* [Main doc](../../../../../../../__docs__/README.md)
|
||||
- [Main doc](../../../../../../../__docs__/README.md)
|
||||
|
||||
This directory contains the React Native implementation of the [MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
|
||||
This directory contains the React Native implementation of the
|
||||
[MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
|
||||
|
||||
## Usage
|
||||
|
||||
`MutationObserver` is meant to be used from JavaScript, exposed as a global class.
|
||||
`MutationObserver` is meant to be used from JavaScript, exposed as a global
|
||||
class.
|
||||
|
||||
## Design
|
||||
|
||||
@@ -14,9 +16,13 @@ This is the high-level design of the MutationObserver API:
|
||||
|
||||
|
||||
|
||||
The global `MutationObserver` class is defined in JavaScript and it does its setup using a native module.
|
||||
The global `MutationObserver` class is defined in JavaScript and it does its
|
||||
setup using a native module.
|
||||
|
||||
In native, it relies on ShadowTree commit hooks to get notifications about changes in the tree, and detects mutations using the before/after revisions. It relies on referential equality of the shadow nodes for performance optimizations.
|
||||
In native, it relies on ShadowTree commit hooks to get notifications about
|
||||
changes in the tree, and detects mutations using the before/after revisions. It
|
||||
relies on referential equality of the shadow nodes for performance
|
||||
optimizations.
|
||||
|
||||
## Relationship with other systems
|
||||
|
||||
@@ -28,9 +34,13 @@ In native, it relies on ShadowTree commit hooks to get notifications about chang
|
||||
### Used by this
|
||||
|
||||
- This relies on `ShadowTree` commit hooks provided by `UIManager`.
|
||||
- It uses the C++ TurboModule infra for communication between JavaScript and native.
|
||||
- It uses the [`Event Loop`](../../../../../ReactCommon/react/renderer/runtimescheduler/__docs__/README.md) to schedule mutation observer callbacks as microtasks.
|
||||
- It uses the C++ TurboModule infra for communication between JavaScript and
|
||||
native.
|
||||
- It uses the
|
||||
[`Event Loop`](../../../../../ReactCommon/react/renderer/runtimescheduler/__docs__/README.md)
|
||||
to schedule mutation observer callbacks as microtasks.
|
||||
|
||||
### Uses this
|
||||
|
||||
- This is an API meant to be used by end users. It is not used directly but any other parts of the platform.
|
||||
- This is an API meant to be used by end users. It is not used directly but any
|
||||
other parts of the platform.
|
||||
|
||||
Reference in New Issue
Block a user