The scheduler package

A to-do list for the main thread

The work loop lesson ended with a promise: when a transition's render stops after 5 ms, "the scheduler runs the rest in a later task". The lanes lesson showed how React picks what to render. This lesson opens the package that decides when: packages/scheduler. It is a separate npm package, scheduler, and react-dom 19.3.1 installs version 0.28.0 of it. You can use it yourself. Press the button below.

1import { useState } from "react";2import {3  unstable_scheduleCallback as scheduleCallback,4  unstable_ImmediatePriority as ImmediatePriority,5  unstable_UserBlockingPriority as UserBlockingPriority,6  unstable_NormalPriority as NormalPriority,7  unstable_LowPriority as LowPriority,8  unstable_IdlePriority as IdlePriority,9} from "scheduler@0.28.0";10 11export default function App() {12  const [log, setLog] = useState([]);13 14  function scheduleJobs() {15    const ran = [];16    const job = (name) => () => {17      ran.push(name);18      setLog([...ran]);19    };20    scheduleCallback(IdlePriority, job("Idle: send analytics"));21    scheduleCallback(NormalPriority, job("Normal: save the draft"));22    scheduleCallback(LowPriority, job("Low: prefetch the next page"));23    scheduleCallback(UserBlockingPriority, job("UserBlocking: show the typed letter"));24    scheduleCallback(ImmediatePriority, job("Immediate: fix the cart total"));25    ran.push("The click handler ends");26    setLog([...ran]);27  }28 29  return (30    <>31      <button onClick={scheduleJobs}>Schedule five jobs</button>32      <ol>33        {log.map((line) => <li key={line}>{line}</li>)}34      </ol>35    </>36  );37}

Lines 2 to 9 import the scheduler. The @0.28.0 pins the same version React uses; in a project you would install scheduler and import from "scheduler". Every export starts with unstable_: the package's README says its public API is not finalized. Then:

1. Lines 20 to 24 call scheduleCallback five times, with five priorities, starting with the least urgent. Each call adds a task to a queue and returns at once.
2. Lines 25 and 26 log The click handler ends. It is the first line of the result: the tasks run later, after your code has finished and given the main thread back.
3. Then the tasks run, by priority, not by the order you scheduled them: Immediate, UserBlocking, Normal, Low, Idle.

Priorities are deadlines

The five priorities are numbers, in SchedulerPriorities.js:

export const NoPriority = 0;
export const ImmediatePriority = 1;
export const UserBlockingPriority = 2;
export const NormalPriority = 3;
export const LowPriority = 4;
export const IdlePriority = 5;

A priority isn't used as a rank. unstable_scheduleCallback turns it into a timeout, in Scheduler.js:

  var timeout;
  switch (priorityLevel) {
    case ImmediatePriority:
      // Times out immediately
      timeout = -1;
      break;
    case UserBlockingPriority:
      // Eventually times out
      timeout = userBlockingPriorityTimeout;
      break;
    case IdlePriority:
      // Never times out
      timeout = maxSigned31BitInt;
      break;
    case LowPriority:
      // Eventually times out
      timeout = lowPriorityTimeout;
      break;
    case NormalPriority:
    default:
      // Eventually times out
      timeout = normalPriorityTimeout;
      break;
  }

  var expirationTime = startTime + timeout;

Lines 3 to 5: ImmediatePriority gets -1, a deadline already in the past. Lines 7 to 22 read the others from SchedulerFeatureFlags.js, and the idle one from a constant near the top of Scheduler.js. Line 26 adds the timeout to the task's startTime:

export const frameYieldMs = 5;

export const userBlockingPriorityTimeout = 250;
export const normalPriorityTimeout = 5000;
export const lowPriorityTimeout = 10000;

// Max 31 bit integer. The max integer size in V8 for 32-bit systems.
// Math.pow(2, 30) - 1
// 0b111111111111111111111111111111
var maxSigned31BitInt = 1073741823;

// Tasks are stored on a min heap
var taskQueue: Array<Task> = [];
var timerQueue: Array<Task> = [];

Line 1 of the flags is the 5 ms slice the work loop lesson met. Lines 3 to 5 are the timeouts: 250 ms, 5 seconds and 10 seconds. In Scheduler.js, line 4 sets the idle timeout to 1073741823 ms, about 12 days, so an idle task never expires in practice. Lines 7 and 8 declare the two queues. Here is the rest of unstable_scheduleCallback:

  var newTask: Task = {
    id: taskIdCounter++,
    callback,
    priorityLevel,
    startTime,
    expirationTime,
    sortIndex: -1,
  };
  // ... (profiling left out)
  if (startTime > currentTime) {
    // This is a delayed task.
    newTask.sortIndex = startTime;
    push(timerQueue, newTask);
    // ... (a setTimeout for the first delayed task left out)
  } else {
    newTask.sortIndex = expirationTime;
    push(taskQueue, newTask);
    // ... (profiling left out)
    // Schedule a host callback, if needed. If we're already performing work,
    // wait until the next time we yield.
    if (!isHostCallbackScheduled && !isPerformingWork) {
      isHostCallbackScheduled = true;
      requestHostCallback();
    }
  }

  return newTask;
}

1. Lines 1 to 8 make the task: an id that counts up, your callback, the priority and the two times.
2. Lines 10 to 13: a task with a delay option starts later. It waits in timerQueue, sorted by its startTime, until a setTimeout moves it over.
3. Lines 16 and 17: any other task goes into taskQueue with sortIndex = expirationTime. That one number decides its place.
4. Lines 21 to 24 start the loop if it isn't running yet, and line 27 returns the task.

Because it returns the task, you can look at one. Press the button:

1import { useState } from "react";2import {3  unstable_now as now,4  unstable_scheduleCallback as scheduleCallback,5  unstable_ImmediatePriority as ImmediatePriority,6  unstable_UserBlockingPriority as UserBlockingPriority,7  unstable_NormalPriority as NormalPriority,8  unstable_LowPriority as LowPriority,9  unstable_IdlePriority as IdlePriority,10} from "scheduler@0.28.0";11 12const priorities = [13  ["Immediate", ImmediatePriority],14  ["UserBlocking", UserBlockingPriority],15  ["Normal", NormalPriority],16  ["Low", LowPriority],17  ["Idle", IdlePriority],18];19 20export default function App() {21  const [rows, setRows] = useState([]);22 23  function schedule() {24    const time = now();25    const tasks = priorities.map(([name, level]) => [name, scheduleCallback(level, () => {})]);26    tasks.push(["Normal, delay 1000", scheduleCallback(NormalPriority, () => {}, { delay: 1000 })]);27    const after = (ms) => Math.round(ms - time);28    setRows(tasks.map(([name, task]) => [name, task.priorityLevel, after(task.startTime), after(task.expirationTime), after(task.sortIndex)]));29  }30 31  return (32    <>33      <button onClick={schedule}>Schedule six tasks</button>34      <table>35        <thead>36          <tr><th>Task</th><th>priorityLevel</th><th>startTime</th><th>expirationTime</th><th>sortIndex</th></tr>37        </thead>38        <tbody>39          {rows.map((row) => (40            <tr key={row[0]}>{row.map((cell, index) => <td key={index}>{cell}</td>)}</tr>41          ))}42        </tbody>43      </table>44    </>45  );46}

Line 24 reads the scheduler's clock, unstable_now(), and line 27 shows each time as milliseconds after it. The table reads Immediate 1 0 -1 -1, UserBlocking 2 0 250 250, Normal 3 0 5000 5000, Low 4 0 10000 10000 and Idle 5 0 1073741823 1073741823. The delayed task (line 26) reads 3 1000 6000 1000: it starts in a second, so its deadline is 6 seconds away, and its sortIndex is its start. On a busy machine a row can read a millisecond later, like Normal 3 1 5001 5001: the clock moved while the tasks were being scheduled, and the timeouts stay the same. How to read the table below: each row is one priority, its number, its timeout, and what React uses it for.

The deadline is the whole trick. A Normal task scheduled 4.8 seconds ago has a smaller sortIndex than a UserBlocking task scheduled now (5000 is less than 4800 + 250), so the old task goes first. Nothing waits forever.

The queue is a min-heap

taskQueue must hand out the smallest sortIndex again and again, while new tasks keep arriving. Sorting the whole array on every push would be slow. The scheduler uses a min-heap: an array where every element is smaller than the two below it, so the smallest is always first. The whole file is SchedulerMinHeap.js:

export function push<T: Node>(heap: Heap<T>, node: T): void {
  const index = heap.length;
  heap.push(node);
  siftUp(heap, node, index);
}

export function peek<T: Node>(heap: Heap<T>): T | null {
  return heap.length === 0 ? null : heap[0];
}
// ... (pop left out)
function siftUp<T: Node>(heap: Heap<T>, node: T, i: number): void {
  let index = i;
  while (index > 0) {
    const parentIndex = (index - 1) >>> 1;
    const parent = heap[parentIndex];
    if (compare(parent, node) > 0) {
      // The parent is larger. Swap positions.
      heap[parentIndex] = node;
      heap[index] = parent;
      index = parentIndex;
    } else {
      // The parent is smaller. Exit.
      return;
    }
  }
}
// ... (siftDown left out)
function compare(a: Node, b: Node) {
  // Compare sort index first, then task id.
  const diff = a.sortIndex - b.sortIndex;
  return diff !== 0 ? diff : a.id - b.id;
}

1. Lines 1 to 5: push adds the task at the end of the array, then lets it rise.
2. Lines 7 to 9: peek is the first element: the next task, without searching.
3. Lines 11 to 26: siftUp finds the parent at (index - 1) >>> 1 (line 14), and swaps the two while the parent is larger (lines 16 to 20). It stops as soon as the parent is smaller.
4. Lines 28 to 32: compare looks at sortIndex, and on a tie at id, so tasks with the same deadline run in the order they were scheduled.

Taking the first task, in pop, does the opposite:

export function pop<T: Node>(heap: Heap<T>): T | null {
  if (heap.length === 0) {
    return null;
  }
  const first = heap[0];
  const last = heap.pop();
  if (last !== first) {
    heap[0] = last;
    siftDown(heap, last, 0);
  }
  return first;
}

Line 5 keeps the first task, line 6 removes the last one, and lines 8 and 9 put the last one at the top and let it sink with siftDown, which swaps it with its smaller child until both children are larger. A push or a pop touches one element per level of the tree: with 1,000 tasks, about 10. Try it below. The playground starts with three tasks scheduled at 0 ms, the heap in the picture.

Schedule a few tasks and watch each one rise to its place. Press Run the next task: the top task leaves, and the last one sinks. Then press Wait 1,000 ms five times and schedule a UserBlocking task: its sortIndex is 5250, so task 1, the Normal task from 0 ms with 5000, stays ahead of it, and task 1 turns red: it has expired.

workLoop runs tasks until the slice is used up

Running the queue is workLoop, called by flushWork. The work loop lesson showed shouldYieldToHost, which says yes once 5 ms have passed since the slice began, or when React has asked for a paint with requestPaint. Here is the loop that asks it:

function workLoop(initialTime: number) {
  let currentTime = initialTime;
  advanceTimers(currentTime);
  currentTask = peek(taskQueue);
  while (currentTask !== null) {
    if (!enableAlwaysYieldScheduler) {
      if (currentTask.expirationTime > currentTime && shouldYieldToHost()) {
        // This currentTask hasn't expired, and we've reached the deadline.
        break;
      }
    }
    const callback = currentTask.callback;
    if (typeof callback === 'function') {
      currentTask.callback = null;
      currentPriorityLevel = currentTask.priorityLevel;
      const didUserCallbackTimeout = currentTask.expirationTime <= currentTime;
      const continuationCallback = callback(didUserCallbackTimeout);
      currentTime = getCurrentTime();
      if (typeof continuationCallback === 'function') {
        // If a continuation is returned, immediately yield to the main thread
        // regardless of how much time is left in the current time slice.
        currentTask.callback = continuationCallback;
        advanceTimers(currentTime);
        return true;
      } else {
        if (currentTask === peek(taskQueue)) {
          pop(taskQueue);
        }
        advanceTimers(currentTime);
      }
    } else {
      pop(taskQueue);
    }
    currentTask = peek(taskQueue);
    // ... (a variant behind enableAlwaysYieldScheduler, off in this release, left out)
  }
  // Return whether there's additional work
  if (currentTask !== null) {
    return true;
  } else {
    const firstTimer = peek(timerQueue);
    if (firstTimer !== null) {
      requestHostTimeout(handleTimeout, firstTimer.startTime - currentTime);
    }
    return false;
  }
}

1. Line 3, advanceTimers, moves delayed tasks whose start time has come from timerQueue to taskQueue, and line 4 takes the top task.
2. Lines 7 to 10: stop when the slice is used up, but only if the task hasn't expired. An expired task runs even past the 5 ms.
3. Lines 14 to 17: clear the task's callback, set the current priority, and call it with didUserCallbackTimeout: whether it has expired.
4. Lines 19 to 24: if the callback returns a function, that function is a continuation. It becomes the task's new callback, the task keeps its place at the top, and the loop returns true at once: more work, later.
5. Lines 25 to 30: otherwise the task is done, and line 27 pops it.
6. Lines 31 to 33: a task whose callback is null was cancelled with unstable_cancelCallback. A heap can't remove an element from the middle, so cancelling only clears the callback, and the loop drops the task when it reaches the top.
7. Lines 37 to 46: return whether tasks are left; if only delayed ones are, start a timer for the first with requestHostTimeout.

A continuation is how a long job shares the main thread. Here are 300 slow orders, 1 ms each, processed in one scheduler task. Press Process in one go, then Process in slices.

1import { useState } from "react";2import {3  unstable_scheduleCallback as scheduleCallback,4  unstable_shouldYield as shouldYield,5  unstable_NormalPriority as NormalPriority,6} from "scheduler@0.28.0";7 8function busy(ms) {9  const end = performance.now() + ms;10  while (performance.now() < end) {}11}12 13export default function App() {14  const [report, setReport] = useState("Press a button.");15 16  function start(canYield) {17    let done = 0;18    let slices = 0;19    let ticks = 0;20    let ticking = true;21    const tick = () => {22      if (!ticking) return;23      ticks += 1;24      setTimeout(tick, 0);25    };26    setReport("Processing 300 orders...");27 28    function processOrders() {29      slices += 1;30      if (slices === 1) setTimeout(tick, 0);31      while (done < 300) {32        if (canYield && shouldYield()) return processOrders;33        busy(1); // one order34        done += 1;35      }36      ticking = false;37      setReport(`300 orders in ${slices} slices. A timer ran ${ticks} times meanwhile.`);38      return null;39    }40 41    scheduleCallback(NormalPriority, processOrders);42  }43 44  return (45    <>46      <button onClick={() => start(false)}>Process in one go</button>47      <button onClick={() => start(true)}>Process in slices</button>48      <p>{report}</p>49    </>50  );51}

Lines 21 to 25 make a timer that counts how often the browser gets a turn, and line 30 starts it in the job's first slice. Process in one go (line 46) runs all 300 orders in one call: 300 orders in 1 slices. A timer ran 0 times meanwhile. The page is frozen for 300 ms. Process in slices (line 47) checks shouldYield() before each order (line 32). When it says yes, the function returns itself, a continuation, and the report reads about 60 slices, with the timer running about as often: the browser got a turn every 5 ms. The exact numbers depend on your computer.

This is exactly what React's concurrent work loop does: workLoopConcurrentByScheduler stops when shouldYield() says so, and React's scheduler task returns a continuation. The last section shows that code.

A MessageChannel starts each slice

Each slice is one browser task, run by performWorkUntilDeadline:

const performWorkUntilDeadline = () => {
  if (enableRequestPaint) {
    needsPaint = false;
  }
  if (isMessageLoopRunning) {
    const currentTime = getCurrentTime();
    // Keep track of the start time so we can measure how long the main thread
    // has been blocked.
    startTime = currentTime;

    // ... (a comment about errors left out)
    let hasMoreWork = true;
    try {
      hasMoreWork = flushWork(currentTime);
    } finally {
      if (hasMoreWork) {
        // If there's more work, schedule the next message event at the end
        // of the preceding one.
        schedulePerformWorkUntilDeadline();
      } else {
        isMessageLoopRunning = false;
      }
    }
  }
};

Lines 2 to 4 clear the request for a paint. Line 9 notes when the slice started, the startTime that shouldYieldToHost measures from. Line 14 runs flushWork, which calls workLoop. Lines 16 to 19: if work is left, schedule the next slice. In the published build, flushWork and workLoop are copied into this function, so a stack trace shows only performWorkUntilDeadline. How the next slice is scheduled depends on where the code runs:

let schedulePerformWorkUntilDeadline;
if (typeof localSetImmediate === 'function') {
  // ... (comments on why Node.js uses setImmediate left out)
  schedulePerformWorkUntilDeadline = () => {
    localSetImmediate(performWorkUntilDeadline);
  };
} else if (typeof MessageChannel !== 'undefined') {
  // DOM and Worker environments.
  // We prefer MessageChannel because of the 4ms setTimeout clamping.
  const channel = new MessageChannel();
  const port = channel.port2;
  channel.port1.onmessage = performWorkUntilDeadline;
  schedulePerformWorkUntilDeadline = () => {
    port.postMessage(null);
  };
} else {
  // We should only fallback here in non-browser environments.
  schedulePerformWorkUntilDeadline = () => {
    localSetTimeout(performWorkUntilDeadline, 0);
  };
}

1. Lines 2 to 6: Node.js (and tests that run React on jsdom) use setImmediate. Unlike a MessageChannel, it doesn't keep a Node.js process alive.
2. Lines 7 to 15: browsers make one MessageChannel, a pair of ports. postMessage on one port queues a task that runs performWorkUntilDeadline on the other. Line 9 gives the reason.
3. Lines 16 to 21: anywhere else, setTimeout.

The "4ms setTimeout clamping" is a rule in the HTML standard: once timers have nested more than five deep, each setTimeout(fn, 0) waits at least 4 ms (the timers lesson). A scheduler that posts a task every 5 ms would lose almost half its time to that wait. Run this chain of 50 tasks, each scheduling the next:

const channel = new MessageChannel();
let onMessage = null;
channel.port1.onmessage = () => onMessage();

function viaTimeout(callback) {
  setTimeout(callback, 0);
}

function viaMessage(callback) {
  onMessage = callback;
  channel.port2.postMessage(null);
}

function chain(schedule, name) {
  const start = performance.now();
  let count = 0;
  return new Promise((resolve) => {
    function step() {
      count += 1;
      if (count < 50) schedule(step);
      else resolve(`${name}: 50 tasks in ${Math.round(performance.now() - start)} ms`);
    }
    schedule(step);
  });
}

chain(viaTimeout, "setTimeout")
  .then((line) => console.log(line))
  .then(() => chain(viaMessage, "MessageChannel"))
  .then((line) => console.log(line))
  .then(() => channel.port1.close());

Lines 5 to 7 schedule with a timer, and lines 9 to 12 with a message. In a browser, the setTimeout line reports at least 180 ms, because 45 of the 50 timers wait 4 ms or more. The MessageChannel line reports far less: its tasks run as soon as the browser gets to them. Two other browser features don't fit either. requestIdleCallback only calls back when the browser has nothing else to do, so on a busy page a render could wait a long time; the scheduler wants to run soon, just in short pieces. requestAnimationFrame runs once per frame, before a paint, and browsers pause it in background tabs. A message task runs as soon as it can, between the browser's other tasks (the event loop lesson shows how tasks take turns).

How React hands work to the scheduler

A set call doesn't render. As the What setState really does lesson showed, it marks a lane and calls ensureRootIsScheduled, which queues one microtask with scheduleImmediateRootScheduleTask:

function scheduleImmediateRootScheduleTask() {
  // ... (the queue that the act test helper uses left out)
  if (supportsMicrotasks) {
    scheduleMicrotask(() => {
      // ... (a comment about a Safari bug left out)
      const executionContext = getExecutionContext();
      if ((executionContext & (RenderContext | CommitContext)) !== NoContext) {
        // ... (a comment left out)
        Scheduler_scheduleCallback(
          ImmediateSchedulerPriority,
          processRootScheduleInImmediateTask,
        );
        return;
      }
      processRootScheduleInMicrotask();
    });
  } else {
    // If microtasks are not supported, use Scheduler.
    Scheduler_scheduleCallback(
      ImmediateSchedulerPriority,
      processRootScheduleInImmediateTask,
    );
  }
}

Lines 3 and 4 queue a microtask (the microtasks lesson), and line 15 does the real work in it, in processRootScheduleInMicrotask. Lines 7 to 13: if the microtask runs in the middle of a render or a commit (Safari can run microtasks there), React schedules an ImmediatePriority scheduler task instead, and lines 17 to 22 do the same where there are no microtasks. That is the only place react-dom schedules ImmediatePriority work. In the microtask, for each root, scheduleTaskForRootDuringMicrotask asks getNextLanes what to render, then:

  if (
    includesSyncLane(nextLanes) &&
    // ... (a comment about prerendering left out)
    !checkIfRootIsPrerendering(root, nextLanes)
  ) {
    // Synchronous work is always flushed at the end of the microtask, so we
    // don't need to schedule an additional task.
    if (existingCallbackNode !== null) {
      cancelCallback(existingCallbackNode);
    }
    root.callbackPriority = SyncLane;
    root.callbackNode = null;
    return SyncLane;
  } else {
    // ... (keeping a task that already has the right priority left out)
    let schedulerPriorityLevel;
    switch (lanesToEventPriority(nextLanes)) {
      // Scheduler does have an "ImmediatePriority", but now that we use
      // microtasks for sync work we no longer use that. Any sync work that
      // reaches this path is meant to be time sliced.
      case DiscreteEventPriority:
      case ContinuousEventPriority:
        schedulerPriorityLevel = UserBlockingSchedulerPriority;
        break;
      case DefaultEventPriority:
        schedulerPriorityLevel = NormalSchedulerPriority;
        break;
      case IdleEventPriority:
        schedulerPriorityLevel = IdleSchedulerPriority;
        break;
      default:
        schedulerPriorityLevel = NormalSchedulerPriority;
        break;
    }

    const newCallbackNode = scheduleCallback(
      schedulerPriorityLevel,
      performWorkOnRootViaSchedulerTask.bind(null, root),
    );

    root.callbackPriority = newCallbackPriority;
    root.callbackNode = newCallbackNode;
    return newCallbackPriority;

1. Lines 1 to 13: SyncLane gets no scheduler task at all. The microtask renders it at its end, right after your event handler.
2. Lines 17 to 34 turn the lanes into a scheduler priority, through the event priority of their most urgent lane (lanesToEventPriority).
3. Lines 36 to 39 schedule performWorkOnRootViaSchedulerTask for this root, and lines 41 and 42 remember the task, so a later update can keep it or cancel it.

How to read the table: each row is the lanes React picked, their event priority, and what React asks of the scheduler.

When the task runs, it renders, and if the work loop yielded, it hands the scheduler a continuation. This is the end of performWorkOnRootViaSchedulerTask:

  const forceSync = !disableSchedulerTimeoutInWorkLoop && didTimeout;
  performWorkOnRoot(root, lanes, forceSync);

  // The work loop yielded, but there may or may not be work left at the current
  // priority. Need to determine whether we need to schedule a continuation.
  // Usually `scheduleTaskForRootDuringMicrotask` only runs inside a microtask;
  // however, since most of the logic for determining if we need a continuation
  // versus a new task is the same, we cheat a bit and call it here. This is
  // only safe to do because we know we're at the end of the browser task.
  // So although it's not an actual microtask, it might as well be.
  scheduleTaskForRootDuringMicrotask(root, now());
  if (root.callbackNode != null && root.callbackNode === originalCallbackNode) {
    // The task node scheduled for this root is the same one that's
    // currently executed. Need to return a continuation.
    return performWorkOnRootViaSchedulerTask.bind(null, root);
  }
  return null;

Line 1: didTimeout is the scheduler's didUserCallbackTimeout; an expired task renders without yielding. Line 2 renders. Line 11 decides what comes next, and lines 12 to 15 return a continuation when the same task should carry on: the scheduler keeps it at the top of the queue, and the next slice goes on from the same fiber. You can see these functions on the stack. Try each button, and move the pointer over the line.

1import { startTransition, useState } from "react";2 3const steps = [4  "processRootScheduleInMicrotask",5  "performSyncWorkOnRoot",6  "performWorkUntilDeadline",7  "performWorkOnRootViaSchedulerTask",8  "workLoopSync",9  "workLoopConcurrentByScheduler",10];11 12function pathOnTheStack() {13  Error.stackTraceLimit = 80;14  const lines = new Error().stack.split("\n");15  const names = lines.map((line) => line.trim().replace(/^at /, "").split(/[ @(]/)[0].split(".").at(-1));16  return names.filter((name) => steps.includes(name)).reverse().join(" > ");17}18 19function Probe({ round }) {20  return <p>Render {round}: {pathOnTheStack()}</p>;21}22 23export default function App() {24  const [round, setRound] = useState(0);25 26  return (27    <>28      <button onClick={() => setRound(round + 1)}>Click</button>29      <button onClick={() => setTimeout(() => setRound(round + 1), 0)}>Timer</button>30      <button onClick={() => startTransition(() => setRound(round + 1))}>Transition</button>31      <p onPointerMove={() => setRound(round + 1)}>Move the pointer over this line.</p>32      <Probe round={round} />33    </>34  );35}

Lines 12 to 17 read the stack, as the work loop lesson's example did (the stack trace API lesson explains stack). Line 15 keeps the part of each name after the last dot, because browsers write MessagePort.performWorkUntilDeadline. You'll see:

• Click: processRootScheduleInMicrotask > performSyncWorkOnRoot > workLoopSync. No scheduler task: the microtask rendered it.
• Timer: performWorkUntilDeadline > performWorkOnRootViaSchedulerTask > workLoopSync. A DefaultLane update gets a NormalPriority task, but it's blocking, so it renders without yielding.
• Transition: the same task, with workLoopConcurrentByScheduler at the end: 5 ms slices.
• Moving the pointer gives the timer's path too, from a UserBlockingPriority task.

The link also runs the other way. Inside a scheduler task, window.event is the message event, and getEventPriority asks the scheduler for its current priority:

    case 'message': {
      // We might be in the Scheduler callback.
      // Eventually this mechanism will be replaced by a check
      // of the current priority on the native scheduler.
      const schedulerPriority = getCurrentSchedulerPriorityLevel();
      switch (schedulerPriority) {
        case ImmediateSchedulerPriority:
          return DiscreteEventPriority;
        case UserBlockingSchedulerPriority:
          return ContinuousEventPriority;
        case NormalSchedulerPriority:
        case LowSchedulerPriority:
          // TODO: Handle LowSchedulerPriority, somehow. Maybe the same lane as hydration.
          return DefaultEventPriority;
        case IdleSchedulerPriority:
          return IdleEventPriority;
        default:
          return DefaultEventPriority;
      }
    }

So a set call made inside a UserBlockingPriority task gets InputContinuousLane (lines 9 and 10), and one inside a NormalPriority task gets DefaultLane (lines 11 to 14).

Which scheduler task renders my update?

In Chrome's Performance panel, a slow click shows one long task that starts with a microtask. A transition shows a row of short tasks, each a message event with performWorkUntilDeadline inside: one per slice. React also uses NormalPriority tasks for a few jobs of its own, such as running useEffect callbacks after a commit. The profiling lesson shows how to record one. Sort these updates by the scheduler task React uses to render them:

Should you call the scheduler yourself? Rarely. In a React app, startTransition and useDeferredValue (transitions, deferred values) already put slow renders in sliced, interruptible tasks. For long work outside React, the same idea works with any API: do a piece, check the time, and give the main thread back.

Common mix-ups

• "The scheduler runs the highest priority first, always." No. It runs the smallest deadline first. A Normal task that has waited long enough goes before a new UserBlocking one.
• "IdlePriority waits until the browser is idle." No. It only has a very late deadline. If nothing else is queued, an idle task runs in the next slice.
• "A click's render is a scheduler task." No. SyncLane renders in a microtask, with no scheduler task.
• "The scheduler uses requestIdleCallback." No. Browsers get a MessageChannel, Node.js setImmediate.
• "Cancelling a task removes it from the queue." No. It clears the callback, and the loop drops the task when it reaches the top.
• "Returning a function from a task schedules a new task." No. It becomes the same task's new callback, which keeps its place and deadline.
• "Each slice lasts one frame, about 16 ms." No. A slice lasts about 5 ms, and several can fit in one frame.

Practice exercises

import { useState } from "react";
import {
  unstable_scheduleCallback as scheduleCallback,
  unstable_UserBlockingPriority as UserBlockingPriority,
  unstable_NormalPriority as NormalPriority,
  unstable_IdlePriority as IdlePriority,
} from "scheduler@0.28.0";

export default function App() {
  const [order, setOrder] = useState([]);

  function go() {
    const ran = [];
    const add = (name) => {
      ran.push(name);
      setOrder([...ran]);
    };
    scheduleCallback(IdlePriority, () => add("analytics"));
    scheduleCallback(NormalPriority, () => add("results"));
    scheduleCallback(UserBlockingPriority, () => add("letter"));
    add("click");
  }

  return (
    <>
      <button onClick={go}>Go</button>
      <p>{order.join(", ")}</p>
    </>
  );
}

import { useState } from "react";
import {
  unstable_scheduleCallback as scheduleCallback,
  unstable_UserBlockingPriority as UserBlockingPriority,
  unstable_NormalPriority as NormalPriority,
  unstable_IdlePriority as IdlePriority,
} from "scheduler@0.28.0";

export default function App() {
  const [order, setOrder] = useState([]);

  function go() {
    const ran = [];
    const add = (name) => {
      ran.push(name);
      setOrder([...ran]);
    };
    scheduleCallback(IdlePriority, () => add("analytics"));
    scheduleCallback(NormalPriority, () => add("results"));
    scheduleCallback(UserBlockingPriority, () => add("letter"));
    add("click");
  }

  return (
    <>
      <button onClick={go}>Go</button>
      <p>{order.join(", ")}</p>
    </>
  );
}

const tasks = [
  { id: 1, name: "save the draft", sortIndex: 5100 },
  { id: 2, name: "show the letter", sortIndex: 350 },
  { id: 3, name: "old render", sortIndex: 350 },
];

function compare(a, b) {
  const diff = a.sortIndex - b.sortIndex;
  return diff !== 0 ? diff : a.id - b.id;
}

console.log(tasks.sort(compare).map((task) => task.name).join(", "));

const tasks = [
  { id: 1, name: "save the draft", sortIndex: 5100 },
  { id: 2, name: "show the letter", sortIndex: 350 },
  { id: 3, name: "old render", sortIndex: 350 },
];

function compare(a, b) {
  const diff = a.sortIndex - b.sortIndex;
  return diff !== 0 ? diff : a.id - b.id;
}

console.log(tasks.sort(compare).map((task) => task.name).join(", "));

const heap = [];

function push(heap, task) {
  heap.push(task);
  // Then: while the task isn't at the top and its parent's sortIndex is bigger,
  // swap them. The parent of index i is at (i - 1) >>> 1.
}

push(heap, { id: 1, sortIndex: 30 });
push(heap, { id: 2, sortIndex: 20 });
push(heap, { id: 3, sortIndex: 10 });
console.log(heap.map((task) => task.sortIndex).join(" "));

const heap = [];

function push(heap, task) {
  heap.push(task);
  let index = heap.length - 1;
  while (index > 0) {
    const parentIndex = (index - 1) >>> 1;
    const parent = heap[parentIndex];
    if (parent.sortIndex <= task.sortIndex) return;
    heap[parentIndex] = task;
    heap[index] = parent;
    index = parentIndex;
  }
}

push(heap, { id: 1, sortIndex: 30 });
push(heap, { id: 2, sortIndex: 20 });
push(heap, { id: 3, sortIndex: 10 });
console.log(heap.map((task) => task.sortIndex).join(" "));

1import { useState } from "react";2import {3  unstable_scheduleCallback as scheduleCallback,4  unstable_shouldYield as shouldYield,5  unstable_NormalPriority as NormalPriority,6} from "scheduler@0.28.0";7 8function busy(ms) {9  const end = performance.now() + ms;10  while (performance.now() < end) {}11}12 13export default function App() {14  const [report, setReport] = useState("Press Build.");15 16  function build() {17    let row = 0;18    let slices = 0;19    let ticks = 0;20    let ticking = true;21    const tick = () => {22      if (!ticking) return;23      ticks += 1;24      setTimeout(tick, 0);25    };26 27    function buildRows() {28      slices += 1;29      if (slices === 1) setTimeout(tick, 0);30      while (row < 200) {31        busy(1); // one row of the report32        row += 1;33      }34      ticking = false;35      setReport(`200 rows in ${slices} slices. A timer ran ${ticks} times meanwhile.`);36      return null;37    }38 39    scheduleCallback(NormalPriority, buildRows);40  }41 42  return (43    <>44      <button onClick={build}>Build</button>45      <p>{report}</p>46    </>47  );48}

1import { useState } from "react";2import {3  unstable_scheduleCallback as scheduleCallback,4  unstable_shouldYield as shouldYield,5  unstable_NormalPriority as NormalPriority,6} from "scheduler@0.28.0";7 8function busy(ms) {9  const end = performance.now() + ms;10  while (performance.now() < end) {}11}12 13export default function App() {14  const [report, setReport] = useState("Press Build.");15 16  function build() {17    let row = 0;18    let slices = 0;19    let ticks = 0;20    let ticking = true;21    const tick = () => {22      if (!ticking) return;23      ticks += 1;24      setTimeout(tick, 0);25    };26 27    function buildRows() {28      slices += 1;29      if (slices === 1) setTimeout(tick, 0);30      while (row < 200) {31        if (shouldYield()) return buildRows;32        busy(1); // one row of the report33        row += 1;34      }35      ticking = false;36      setReport(`200 rows in ${slices} slices. A timer ran ${ticks} times meanwhile.`);37      return null;38    }39 40    scheduleCallback(NormalPriority, buildRows);41  }42 43  return (44    <>45      <button onClick={build}>Build</button>46      <p>{report}</p>47    </>48  );49}

let now = 0;
const queue = [
  { name: "letter", expirationTime: 250, cost: 3 },
  { name: "results", expirationTime: 5000, cost: 3 },
  { name: "analytics", expirationTime: 1073741823, cost: 3 },
];

// Runs tasks from the front of the queue and returns their names. Before each
// task, stop if 5 ms have passed since startTime, unless that task has expired
// (expirationTime <= now). Running a task removes it and adds its cost to now.
function workLoop(startTime) {
  const ran = [];
  return ran;
}

console.log("slice 1:", workLoop(now).join(", "));
console.log("slice 2:", workLoop(now).join(", "));

let now = 0;
const queue = [
  { name: "letter", expirationTime: 250, cost: 3 },
  { name: "results", expirationTime: 5000, cost: 3 },
  { name: "analytics", expirationTime: 1073741823, cost: 3 },
];

// Runs tasks from the front of the queue and returns their names. Before each
// task, stop if 5 ms have passed since startTime, unless that task has expired
// (expirationTime <= now). Running a task removes it and adds its cost to now.
function workLoop(startTime) {
  const ran = [];
  while (queue.length > 0) {
    const task = queue[0];
    if (task.expirationTime > now && now - startTime >= 5) break;
    queue.shift();
    now += task.cost;
    ran.push(task.name);
  }
  return ran;
}

console.log("slice 1:", workLoop(now).join(", "));
console.log("slice 2:", workLoop(now).join(", "));

const heap = [10, 30, 20, 40, 50].map((sortIndex, id) => ({ id, sortIndex }));

function pop(heap) {
  // This takes the first task, but leaves the rest out of heap order.
  return heap.shift();
}

const order = [];
while (heap.length > 0) order.push(pop(heap).sortIndex);
console.log(order.join(" "));

const heap = [10, 30, 20, 40, 50].map((sortIndex, id) => ({ id, sortIndex }));

function pop(heap) {
  const first = heap[0];
  const last = heap.pop();
  if (last === first) return first;
  heap[0] = last;
  let index = 0;
  while (true) {
    const left = 2 * index + 1;
    const right = left + 1;
    let smallest = index;
    if (left < heap.length && heap[left].sortIndex < heap[smallest].sortIndex) smallest = left;
    if (right < heap.length && heap[right].sortIndex < heap[smallest].sortIndex) smallest = right;
    if (smallest === index) return first;
    [heap[index], heap[smallest]] = [heap[smallest], heap[index]];
    index = smallest;
  }
}

const order = [];
while (heap.length > 0) order.push(pop(heap).sortIndex);
console.log(order.join(" "));

Check your understanding

Key takeaways

• unstable_scheduleCallback turns a priority into a deadline: now plus -1, 250, 5,000 or 10,000 ms, or about 12 days for idle work.
• taskQueue is a min-heap sorted by that deadline, then by id. push sifts up, pop sifts down, and the next task is always at index 0.
• workLoop runs tasks until about 5 ms have passed, except expired ones. A task that returns a function keeps its place and carries on in the next slice.
• Browsers start each slice with a MessageChannel, because setTimeout waits at least 4 ms once nested; Node.js uses setImmediate.
• React renders SyncLane in a microtask, and everything else in a scheduler task: UserBlockingPriority for continuous input, NormalPriority for default updates and transitions, IdlePriority for idle and offscreen work.

Coming next: Concurrent rendering, Suspense and transitions inside.