Yield between event-loop phases
Defer non-urgent work until after the current I/O callback processing.
Node.js · Function
setImmediate
Schedules a callback after I/O callbacks, returning an Immediate handle that can be canceled with clearImmediate(). Multiple immediates execute in creation order.
- Since
- v0.9.1
How it works
setImmediate() queues a callback for execution after I/O callback processing. Calls are handled in creation order during the event loop, and the returned Immediate can be supplied to clearImmediate() if cancellation is needed.
Syntax
setImmediate(callback[, ...args])Parameters
| Name | Type | Description |
|---|---|---|
callback | Function | Function invoked at the end of this turn of the Node.js event loop. |
...args | any | Optional values passed to callback when it runs. |
Returns
An Immediate object that can be passed to clearImmediate().
Key points
- The callback is scheduled for execution after I/O event callbacks.
- Several calls preserve creation order in the immediate queue.
- Node.js processes the queued immediate callbacks during each event-loop iteration.
- Arguments after the callback are forwarded when the callback executes.
- The return value is an Immediate handle that can be used for cancellation.
Common mistakes
- A large queue of immediates can run within one event-loop iteration, so avoid using it as an unbounded work queue.
- Scheduling an immediate can keep the process alive; use the returned object’s unref() behavior when appropriate for shutdown-sensitive code.
Example: Schedule an immediate
setImmediate((message) => {
console.log(message);
}, 'runs after I/O callbacks');Schedules a callback for a later event-loop turn and passes it an optional argument.
When to use it
Queue asynchronous continuation
Schedule ordered follow-up callbacks without a timer delay.
Cancelable deferred work
Obtain a cancellation handle for work that may become unnecessary.
Interview questions
QWhat does setImmediate() do, and what does it return?
It schedules a callback after I/O callbacks, and it returns an Immediate handle. Optional arguments supplied after the callback are passed to that callback.
Follow-up: How can the scheduled callback be canceled? Pass the returned Immediate to clearImmediate() before it runs.
QHow are multiple immediates ordered?
Multiple calls are queued in the order they are created. Node.js processes the immediate callback queue on each event-loop iteration.
Follow-up: What happens if an immediate schedules another immediate? The newly scheduled one is deferred to a later event-loop iteration rather than being inserted into the current processing pass.
QHow does setImmediate() relate to timers and I/O?
The callback is scheduled after I/O callbacks and before timers created by setTimeout() and setInterval() are triggered. The function is available as a global timer API, so importing the timers module is not required.
Follow-up: Which API cancels an immediate? clearImmediate() accepts the Immediate returned by setImmediate().
Related
clearImmediateImmediatesetTimeoutsetInterval