skip to content

In a Node.js job scheduler that processes records in batches, why is setImmediate the usual way to yield between batches?

level: juniorimportance: should knowfreq 55%

answer

  1. give the loop a turn
  2. check phase sits after poll
  3. no 1 ms threshold
  4. queued during check waits a turn

basics

~20 s

setImmediate queues the next batch for the check phase, after poll, so pending socket and file callbacks run between batches. Unlike setTimeout(next, 0) it waits for no 1 ms timer, and unlike process.nextTick it lets the loop poll for I/O first.

solid answer

~50 s

A job that processes a whole backlog in one synchronous loop holds Node's only JavaScript thread, so no request is served until it ends. Batching helps only if each batch hands control back to the event loop. `setImmediate(next)` does that cheaply: its callback runs in the check phase, which comes right after poll, and an immediate queued while the check phase is running waits for the next iteration, so the loop polls sockets and files between every two batches. `setTimeout(next, 0)` also yields, but it is a 1 ms timer, so a quiet loop can sit in poll waiting for it. `process.nextTick` runs before the loop moves on, so a batch loop built on it never lets I/O in. In async code, `await setImmediate()` from `node:timers/promises` does the same. Keep each batch to a few milliseconds, because a batch still blocks while it runs.

code

javascript · 15 lines
javascript
const { setImmediate: yieldToLoop } = require('node:timers/promises');

async function processBacklog(jobs, handle, budgetMs = 5) {
  let i = 0;
  while (i < jobs.length) {
    const start = performance.now();
    while (i < jobs.length && performance.now() - start < budgetMs) {
      handle(jobs[i++]);
    }
    await yieldToLoop(); // the poll phase runs before the next slice
  }
}

const jobs = Array.from({ length: 100_000 }, (_, n) => n);
processBacklog(jobs, (n) => Math.sqrt(n)).then(() => console.log('backlog done'));

go deeper

for a junior

Recall that setImmediate runs a callback after the loop has handled pending I/O, which makes it the standard way to split long work so requests keep being served.

for a middle

Explain the mechanics: check runs after poll, immediates queued during check wait a full iteration, setTimeout(0) carries a 1 ms threshold, and nextTick never yields to I/O.

for a senior

Show how you would size batches by time, verify the effect with loop-delay measurements, and decide when the work belongs in a worker thread instead.

for a principal

Treat yielding as a latency budget: agree how long any one batch may hold the loop and when a job must leave the request-serving process entirely.

## The problem: one long loop holds the only thread Node runs your JavaScript on a single thread. While one function is running, the event loop cannot poll sockets, accept connections, run timers or call I/O callbacks. A job scheduler that works through a large backlog in one synchronous loop therefore freezes every request the same process serves, for as long as the loop takes. Splitting the work into **batches** helps only if each batch hands control back to the event loop before the next one starts, and the way you hand it back decides whether pending I/O actually gets a turn. ## What `setImmediate` does in Node `setImmediate(callback)` is a Node API (browsers never standardised it) with three properties that make it the natural yield point: - The callback runs in the **check phase**, which libuv runs **right after the poll phase**, the phase where socket reads, new connections and finished file operations are handled. - **Immediates queued while the check phase is running wait for the next iteration.** The `node:timers` documentation says so: an immediate queued from inside an executing callback is not triggered until the next event loop iteration. A self-rescheduling batch loop therefore always lets the loop poll once between batches. - There is **no time threshold**. When an immediate is waiting, the poll phase does not block for I/O; it collects whatever is ready and moves on to check. ## Comparing the ways to hand control back | How the next batch is scheduled | When it runs | Is I/O polled first? | Cost | |---|---|---|---| | `setImmediate(next)` | check phase of the next iteration | yes | negligible | | `setTimeout(next, 0)` | when due timers run, 1 ms or more later | yes | a 1 ms threshold per batch | | `process.nextTick(next)` | before the loop moves on | no | starves I/O if repeated | | `await setImmediate()` from `node:timers/promises` | check phase, as a promise | yes | one promise per batch | | `scheduler.yield()` from `node:timers/promises` | same as the line above | yes | still marked Experimental | `setTimeout(next, 0)` does yield, but each batch now waits for a 1 ms timer: on a quiet loop the poll phase can block until that timer is due, and short batches spend more time waiting than working. `process.nextTick` runs before the loop continues to the next phase, so recursing with it never lets I/O in; that queue is a topic of its own. ## One cycle of a batch loop that yields 1. Batch N runs, in the check phase, because it was started by an immediate. 2. It finishes by scheduling the next batch with `setImmediate`; that immediate is held for the next iteration. 3. Close callbacks and any due timers run. 4. Pending callbacks and the **poll phase** run: requests that arrived during batch N are read and handled. 5. The next check phase starts batch N + 1. ```js const { setImmediate: yieldToLoop } = require('node:timers/promises'); async function processBacklog(jobs, handle, batchSize = 200) { for (let i = 0; i < jobs.length; i += batchSize) { for (const job of jobs.slice(i, i + batchSize)) handle(job); await yieldToLoop(); // sockets and file results are handled here } } ``` ## Choosing the batch size - **A batch still blocks while it runs.** Yielding bounds the stall to one batch; it does not remove it. Aim for batches that take a few milliseconds. - **Budget by time when items vary.** Process items until a few milliseconds have passed (`performance.now()` works), then yield, rather than a fixed count that one slow item can blow through. - **Yielding makes the job slower, on purpose.** Every yield trades a little job throughput for request latency. - **Errors still need a home.** An exception thrown inside an immediate callback is not caught by a `try` around the code that scheduled it; with `await` on the promise version, an ordinary `try`/`catch` around the loop does catch it. - **Measure the effect.** Event-loop delay measurement shows whether the batches are short enough; that tooling is covered with blocking and lag measurement. - **Heavy CPU work belongs off the main thread.** If a single item takes tens of milliseconds, batching cannot fix it, and a worker thread is the better tool.

  • Why does a batch loop that recurses with process.nextTick freeze the server even though every call is asynchronous?
    Node drains the whole `process.nextTick` queue before the loop moves on to its next phase, including callbacks added while draining. A loop that keeps adding one never lets the loop reach poll, so no socket is read. Asynchronous is not the same as yielding to I/O; `setImmediate` is the call that waits for the next check phase.
  • Does yielding with setImmediate make the job itself finish sooner?
    No, a little later. Each yield adds a trip around the loop, and other callbacks now run between batches. The gain is latency for everything else in the process: no request waits longer than one batch. If the job's own duration matters more, move it to a worker thread or a separate process instead of yielding more often.

  • process.nextTick is the right way to yield between batches
  • setTimeout(next, 0) and setImmediate(next) cost exactly the same per batch
  • A self-rescheduling setImmediate loop runs every batch in one check phase
  • Yielding between batches makes the CPU work itself run faster
  • Once work is batched, the size of each batch no longer matters