mirror of
https://github.com/nodejs/node.git
synced 2025-05-15 04:53:30 +00:00
ac153bd2a6
`setTimeout()`, `setInterval()` and `setIntermediate` currently throw errors when receiving non-function objects as their first argument, but only do so when trying to execute the callback, i.e. after the waited time has passed. This may complicate debugging when a lot of calls to `setTimeout()`/etc. are involved, so failing as early as possible seems like a good idea. `setTimeout()` historically ignored an falsy first argument, while the other functions do not and throw instead. This patch changes this behaviour to make all three match and adds remarks in the corresponding documentation. PR-URL: https://github.com/nodejs/node/pull/4362 Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Brian White <mscdex@mscdex.net> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: Rod Vagg <rod@vagg.org>
87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
# Timers
|
|
|
|
Stability: 3 - Locked
|
|
|
|
All of the timer functions are globals. You do not need to `require()`
|
|
this module in order to use them.
|
|
|
|
## clearImmediate(immediateObject)
|
|
|
|
Stops an immediate from triggering.
|
|
|
|
## clearInterval(intervalObject)
|
|
|
|
Stops an interval from triggering.
|
|
|
|
## clearTimeout(timeoutObject)
|
|
|
|
Prevents a timeout from triggering.
|
|
|
|
## ref()
|
|
|
|
If you had previously `unref()`d a timer you can call `ref()` to explicitly
|
|
request the timer hold the program open. If the timer is already `ref`d calling
|
|
`ref` again will have no effect.
|
|
|
|
Returns the timer.
|
|
|
|
## setImmediate(callback[, arg][, ...])
|
|
|
|
To schedule the "immediate" execution of `callback` after I/O events
|
|
callbacks and before [`setTimeout`][] and [`setInterval`][]. Returns an
|
|
`immediateObject` for possible use with `clearImmediate()`. Optionally you
|
|
can also pass arguments to the callback.
|
|
|
|
Callbacks for immediates are queued in the order in which they were created.
|
|
The entire callback queue is processed every event loop iteration. If you queue
|
|
an immediate from inside an executing callback, that immediate won't fire
|
|
until the next event loop iteration.
|
|
|
|
If `callback` is not a function `setImmediate()` will throw immediately.
|
|
|
|
## setInterval(callback, delay[, arg][, ...])
|
|
|
|
To schedule the repeated execution of `callback` every `delay` milliseconds.
|
|
Returns a `intervalObject` for possible use with `clearInterval()`. Optionally
|
|
you can also pass arguments to the callback.
|
|
|
|
To follow browser behavior, when using delays larger than 2147483647
|
|
milliseconds (approximately 25 days) or less than 1, Node.js will use 1 as the
|
|
`delay`.
|
|
|
|
If `callback` is not a function `setInterval()` will throw immediately.
|
|
|
|
## setTimeout(callback, delay[, arg][, ...])
|
|
|
|
To schedule execution of a one-time `callback` after `delay` milliseconds.
|
|
Returns a `timeoutObject` for possible use with `clearTimeout()`. Optionally you
|
|
can also pass arguments to the callback.
|
|
|
|
The callback will likely not be invoked in precisely `delay` milliseconds.
|
|
Node.js makes no guarantees about the exact timing of when callbacks will fire,
|
|
nor of their ordering. The callback will be called as close as possible to the
|
|
time specified.
|
|
|
|
To follow browser behavior, when using delays larger than 2147483647
|
|
milliseconds (approximately 25 days) or less than 1, the timeout is executed
|
|
immediately, as if the `delay` was set to 1.
|
|
|
|
If `callback` is not a function `setTimeout()` will throw immediately.
|
|
|
|
## unref()
|
|
|
|
The opaque value returned by [`setTimeout`][] and [`setInterval`][] also has the
|
|
method `timer.unref()` which will allow you to create a timer that is active but
|
|
if it is the only item left in the event loop, it won't keep the program
|
|
running. If the timer is already `unref`d calling `unref` again will have no
|
|
effect.
|
|
|
|
In the case of `setTimeout` when you `unref` you create a separate timer that
|
|
will wakeup the event loop, creating too many of these may adversely effect
|
|
event loop performance -- use wisely.
|
|
|
|
Returns the timer.
|
|
|
|
[`setInterval`]: timers.html#timers_setinterval_callback_delay_arg
|
|
[`setTimeout`]: timers.html#timers_settimeout_callback_delay_arg
|