Node.js Reference ยท Globals and Console
Node.js setImmediate() function
Reference for setImmediate() in Node.js: when it runs in the event loop, how it differs from setTimeout(0) and nextTick, and how to split long work into chunks.
setImmediate(callback, ...args) schedules a callback to run in the "check" phase of the event loop, which comes right after the poll phase where I/O callbacks are handled. It returns an Immediate object that you can cancel with clearImmediate().
The name is misleading: the callback is not run immediately, but on the next pass of the loop after pending I/O has been processed. It is the right tool for "let I/O and other callbacks run first, then continue", for example when splitting a long computation into small pieces.
setImmediate(() => console.log('after I/O'));
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
setImmediate(callback[, ...args]): Immediate // node:timers/promises setImmediate([value[, options]]): Promise
| Name | Description |
|---|---|
callback |
Function to run in the check phase. |
...args |
Extra arguments passed to callback. |
value |
(promise version) The value the promise resolves with. |
options |
(promise version) signal to cancel and ref to control whether the process is kept alive. |
Returns: an Immediate object with ref(), unref() and hasRef() methods.
Errors: ERR_INVALID_ARG_TYPE if callback is not a function.
Usage notes
- Versus
setTimeout(fn, 0): from the main module the order of the two is not guaranteed because it depends on how fast the loop starts. Inside an I/O callback,setImmediatealways runs first. - Versus
process.nextTick()and microtasks: those run before the loop continues at all. OnlysetImmediategives I/O and timers a turn. - Callbacks queued during the check phase run on the next loop iteration, not in the same pass, so a self-rescheduling immediate cannot starve I/O the way a recursive
nextTickcan. - Order: immediates run in the order they were created.
- Cancellation: use
clearImmediate(); an already-run immediate is ignored. unref(): an unref'd immediate does not keep the process alive on its own.- Not in browsers. It is a Node.js (and legacy IE) API; browsers use
setTimeout,MessageChannelorscheduler.postTask(). - Promise form:
await setImmediate()fromnode:timers/promisesyields to the event loop, a handy "let others run" call inside long loops.