diff options
Diffstat (limited to 'doc/api/timers.md')
-rw-r--r-- | doc/api/timers.md | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/doc/api/timers.md b/doc/api/timers.md new file mode 100644 index 00000000000..d33bf1dc22b --- /dev/null +++ b/doc/api/timers.md @@ -0,0 +1,91 @@ +# 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 `immediateObject`, as created by [`setImmediate`][], from triggering. + +## clearInterval(intervalObject) + +Stops an `intervalObject`, as created by [`setInterval`][], from triggering. + +## clearTimeout(timeoutObject) + +Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering. + +## ref() + +If a timer was previously `unref()`d, then `ref()` can be called 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][, ...]) + +Schedules "immediate" execution of `callback` after I/O events' +callbacks and before timers set by [`setTimeout`][] and [`setInterval`][] are +triggered. Returns an `immediateObject` for possible use with +[`clearImmediate`][]. Additional optional arguments may be passed 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 an +immediate is queued 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][, ...]) + +Schedules repeated execution of `callback` every `delay` milliseconds. +Returns a `intervalObject` for possible use with [`clearInterval`][]. Additional +optional arguments may be passed 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][, ...]) + +Schedules execution of a one-time `callback` after `delay` milliseconds. +Returns a `timeoutObject` for possible use with [`clearTimeout`][]. Additional +optional arguments may be passed 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 allows the creation of 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`][], `unref` creates 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. + +[`clearImmediate`]: timers.html#timers_clearimmediate_immediateobject +[`clearInterval`]: timers.html#timers_clearinterval_intervalobject +[`clearTimeout`]: timers.html#timers_cleartimeout_timeoutobject +[`setImmediate`]: timers.html#timers_setimmediate_callback_arg +[`setInterval`]: timers.html#timers_setinterval_callback_delay_arg +[`setTimeout`]: timers.html#timers_settimeout_callback_delay_arg |