# Implementation notes on react's scheduling model as of (shortly before) 16.8.0 While the public API intended for users to use is the `scheduler` package, the reconciler currently does _not_ use `scheduler`'s priority classes internally. `ReactFiberScheduler` has its own internal "mini-scheduler" that uses the `scheduler` package indirectly for its deadline-capable scheduleCallback. This is kind of a documentation of implementation details that I suppose will be gone by the end of the year, but what can you do. ## Basics `ReactFiberScheduler` keeps a list of pending batches of updates, which it internally calls "work". Each individual fiber in the tree is a "unit" on which a "unit of work" will be "performed". Updates caused from inside a React render, lifecycle method/hook, or React-controlled event handler belong to an implicit batch. Updates triggered from outside React are effectively a single-update batch unless it's inside the scope of one of the batching method wrappers, shown later. Any update on any fiber traverses the entire tree mounted on the root (`ReactDOM.render` or `createRoot`) where the update happened. React is very good at bailing out of fibers that are not the subject of the update. ## Priority classes `ReactFiberScheduler` has its own priority classes that are independent from the priority classes in the `scheduler` package. In non-`ConcurrentMode`, any and all updates are sync no matter what. The only difference is whether they are batched or not. When the fiber where an update is triggered is in `ConcurrentMode`, there are 3 possible priority classes: - `deferred` (equivalent to `scheduler.NormalPriority`): - 5000ms deadline, async - This is the default priority for any update that does not otherwise have its own priority or deadline. - `interactive` (roughly equivalent to `scheduler.UserBlockingPriority`): - 150ms deadline, async - in development builds it's 500ms to make slow interactions feel worse - At most one `interactive` priority work may be scheduled. - `sync` (equivalent to `scheduler.ImmediatePriority` but "more immediate"): - sync (duh) - unlike `ImmediatePriority` this won't involve the `scheduler` at all and just immediately start work. - a `sync` update will skip over any pending non-`sync` update, even if it has expired - is the default (instead of `deferred`) for updates triggered in the commit phase - `componentDid{Mount,Update}` and `useLayoutEffect` run effectively in a single batch belonging to this priority. Any updates they trigger will be `sync`. Any update triggered directly during a render phase inherits the deadline of the current render phase. However, because any one fiber's update is atomic, this part of the processing is synchronous per fiber even in `ConcurrentMode`. In class components, this means any update caused in a lifecycle that runs before `render` itself; this includes `setState`s called in the `UNSAFE_` family and the lifecycles that derive state, which are processed like a `setState` call with function argument. All state updates are accumulated while the lifecycle is invoked and then applied synchronously after each lifecyle method returns. Calling `setState` inside `render` itself is either a guaranteed noop or a guaranteed infinite loop, unless your `render` is impure. In function components, all state updates (i.e. invoking dispatchers from `useState` or `useReducer`) that happen during the render function are accumulated into a queue during the render pass. If the queue is non-empty, the component re-renders, and `useState` / `useReducer` apply their respective queued updates from the previous pass as they are reached; until a render pass produces no further queued updates. The number of re-renders is currently limited to 50. **NOTE: this is not in any alpha but will be in 16.8.0**: any function component that invokes any hook will be double-rendered in `StrictMode`, and this is _outside_ the render pass loop described above. Both the hooks and the components themselves must be pure. This also means that, whenever `useMemo` or `useState` would invoke their callbacks, they will always be double-invoked. On mount, the first `useRef` object will always be discarded, and only the one from the second invocation will persist. `useEffect` are all collected into a single independent batch, called the "passive effects", and run inside a `scheduler.scheduleCallback` with no deadline, queued right before the commit phase ends. However, should any further React update happens, regardless of priority class or deadline, the schedule will be canceled and all pending `useEffect`s for the entire previous commit will be invoked synchronously before any work starts. This happens even when calling `setState` or a `useState` / `useReducer` dispatcher. If the value is a callback, the previous commit's pending `useEffect`s will all have been processed by the time the callback is invoked. Any `interactive` update forces the previous `interactive` update, as well as any other outstanding updates with a shorter remaining deadline than that to commit synchronously first before the new `interactive` update itself is calculated. In other words, it converts the previous `interactive` update, as well as _all work_ that should have expired by the time it expired into a single `sync` batch. These are the only cases I found where a non-`sync` update may be, effectively, upgraded to `sync` by the reconciler. ## Batch wrappers, or how to request a priority level It seems to be intended that user generic code uses priority classes and the methods from the `scheduler` package instead of these. However, sometimes it is needed to interact with React specifically, so ReactDOM exposes these (mostly prefixed with `unstable_`, just like `scheduler` exports). - `batchedUpdates` causes all updates triggered inside it to share the same deadline. In other words, they will all belong to the same unit of work, and will all be rendered and committed together. - `batchedUpdates` does not have its own priority class, instead the callback inherits the current one. - `batchedUpdates` can be nested; this merely merges the updates inside it with the outermost batch (batches are flattened). - Other batching methods are not implemented as, but behave as if their callbacks were themselves wrapped in `batchedUpdates`. - If `batchedUpdates` does not otherwise inherit a specific priority class, it defaults to `deferred`. - `interactiveUpdates` is a batch that has `interactive` priority. React synthetic event handlers run as an `interactiveUpdates` batch. - Remember again that at most one `interactive` priority work may be scheduled. Should another `interactive` batch be queued, the previous `interactive` work is synchronously committed. - `syncUpdates` is a batch that has `sync` priority. React will immediately render and commit all updates inside this batch, before the `syncUpdates` function returns. - In non-`ConcurrentMode` any kind of batching just behaves like this one. - Explicitly requesting `sync` priority during `render` or a lifecycle method/hook (except `useEffect` specifically) is an assertion error. The only implicit batches where you are allowed to request `sync` priority are `useEffect` (_not_ `useLayoutEffect`) and in an event handler, which is just an `interactiveUpdates` batch. If any `useEffect` callback or destructor triggers a `sync` update through either being in a non-`ConcurrentMode` tree, or by using `syncUpdates` as mentioned above, there will be a `sync` commit done before any new update can even begin evaluation. If the callback or destructer triggers an async update instead, the deadline will be calculated as if the `useEffect` had been invoked synchronously when the previous update committed[^2]. If any work being processed that's not yet in the commit phase, be it `interactive` or `deferred`, is interrupted by a higher priority work, all progress done so far is completely thrown out. Anything done in the commit phase is always `sync` or belongs to a cascading `sync` batch so the commit phase can never be interrupted. After React commits the higher priority (shorter deadline) work, it will start or restart the next higher priority work on top of the freshly committed state. This will typically be `interactive` batches before `deferred` batches, but if a particular `deferred` batch has fallen too far behind (i.e. its deadline is too close to expiry) it will run ahead of `interactive`. This means that any lifecycle or render method (function component body) not in the commit phase can potentially be called multiple times per render. `StrictMode` ensures that is always done at least twice per render during development mode. The only things called by React that are guaranteed to only be invoked once per React update are the commit phase lifecycles (`componentWillUnmount`, `componentDidMount`, `componentDidUpdate`, `useLayoutEffect`), passive effects (`useEffect`) and, for completeness, event handlers. There is a non-`ConcurrentMode` hack to only invoke class component `constructor`s once if the component or another child or sibling sharing the same Suspense boundary suspends when the class is being mounted. This does not apply to `ConcurrentMode` and classes are also subject to multiple construction if the update where they are being first mounted is interrupted by a higher priority update. These instances, regardless of mode, will be discarded without invoking `componentDidMount` or `componentWillUnmount` if they are never part of a finished commit. Note that that any update caused inside a `scheduler.scheduleCallback` does not count as a batch unless the update is itself wrapped in `batchedUpdates`, `interactiveUpdates` or `syncUpdates`. React currently is not aware of `scheduler` tasks and only uses it as a `requestIdleCallback` with a timeout. ## Work loop and consequences This also means that the behavior of state updates is different in subtler ways than I thought in `ConcurrentMode` than in non-`ConcurrentMode`. I will use the traditional `setState` to represent an update but calls to `ReactDOM.render`, `ReactRoot#render`, updates to `useState` or `useReducer` values also cause updates. In non-`ConcurrentMode`, a non-batched `setState` will _always_ commit synchronously no matter what. Any batching of them will also commit synchronously, but as a single update that is computed on top of the result of all of the `setState`s combined. In `ConcurrentMode`, non-batched `setStates` may or may not form incidental mini-batches, depending on how busy the renderer is and on whether their deadlines get exceeded. If the deadlines are not exceeded, the renderer will render and commit them one-by-one, stopping whenever it is going to exceed its frame time budget which it receives from `scheduler`. This can happen even in the middle of processing a single batch. There is a cooperative yield point after processing each individual fiber. If there is an incomplete work, or any non-`sync` batch is still remaining after the renderer yields, another `scheduler.scheduleCallback` is queued with the deadline of the batch that is closest to expire. It normally uses a `requestIdleCallback`-like mechanism, but if the batch is already expired it will immediately queue a macrotask. In other words, as long as nothing has expired, only the singular work, or batch with the deadline closest to expiration is worked on in a particular render + commit loop. This is why batching is important: it ensures the requested work shares the same deadline and thus belong to the same render + commit loop. When the work loop is resumed, if there was another work queued with a shorter deadline than the current work, all non-committed work done so far is thrown out. The higher priority work skips ahead of the queue and is done in its own commit. If the work loop is resumed because any pending work's deadlines got exceeded, similarly all non-committed work done so far is thrown out, but all work with expired deadlines is done together in a single batch. The renderer will still yield when it exceeds its frame time budget, but because it has already expired it will be immediately resumed[^1]. This _can_ be catastrophic if there are a significant number of pending updates with deadlines spaced together just enough that none of them can finish in time before the next one. Each time the partial work is thrown out there will be even more work to do for this single deadline expiration batch. Probably just one of the reasons why it's not considered ready for release. This continues until React exhausts the work queue, and then it's up to user interactions or other application code to cause updates. Any `sync` batch ignores the scheduling. Any partial, non-committed work will be thrown out and the loop will process and commit all `sync` updates while ignoring everything else, even expired non-`sync` work. If this interrupted a partial update, it will then start over on top of the new tree when the loop resumes as was originally scheduled. React will protect you against infinite recursion of `sync` updates in the commit phase by counting how many times you caused a cascading update. Currently this limit is 50. However, there is currently nothing to protect you against infinite _async_ updates, other than the max limit of a single queued `interactive` update. [^1]: Yielding is intended to let the browser at least render a frame before continuing, but if we are already rendering an expired task, [this](https://github.com/facebook/react/blob/e19c9e106401fd41c91b67273d4c22289ed0917c/packages/scheduler/src/Scheduler.js#L193-L213) will continuously synchronously drain the queue as long as there are expired tasks, even the [freshly inserted](https://github.com/facebook/react/blob/e19c9e106401fd41c91b67273d4c22289ed0917c/packages/scheduler/src/Scheduler.js#L329-L333) already-expired continuation callback. [^2]: `useEffect` don't really run inside a batch, but they just forbid the scheduler from updating the `currentSchedulerTime` which is used for deriving expirations. This means that all updates inside it will share the same deadline, as the scheduler time has not advanced, and any deadlines will be calculated as if the `useEffect`s had been synchronously invoked on the previous commit.