From 86e07b7c243ce9ef90d90c7765c1b04140a70f42 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 23 May 2016 14:12:20 -0700 Subject: [PATCH] doc: general improvements to timers.md Overall improvements to timers.md documentation, Includes squashed commit from @bengl: doc: add timer classes The timers returned by `setTimeout` and friends are actually instances of `Timeout` and `Immediate`. Documenting them as such, so that the `ref` and `unref` methods can be identified as methods on `Timeout` objects. Sparked by discussion in #5792 PR-URL: https://github.com/nodejs/node/pull/6937 Reviewed-By: Robert Jefe Lindstaedt Reviewed-By: Bryan English Reviewed-By: Benjamin Gruenbaum Reviewed-By: Jeremiah Senkpiel --- doc/api/globals.md | 2 +- doc/api/timers.md | 168 ++++++++++++++++++++++++++++++--------------- 2 files changed, 114 insertions(+), 56 deletions(-) diff --git a/doc/api/globals.md b/doc/api/globals.md index f70c52aae4..1bd2dffc5f 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -208,7 +208,7 @@ but rather than loading the module, just return the resolved filename. [native addons]: addons.html [timers]: timers.html [`clearImmediate`]: timers.html#timers_clearimmediate_immediateobject -[`clearInterval`]: timers.html#timers_clearinterval_intervalobject +[`clearInterval`]: timers.html#timers_clearinterval_immediateobject [`clearTimeout`]: timers.html#timers_cleartimeout_timeoutobject [`setImmediate`]: timers.html#timers_setimmediate_callback_arg [`setInterval`]: timers.html#timers_setinterval_callback_delay_arg diff --git a/doc/api/timers.md b/doc/api/timers.md index d33bf1dc22..29a7a48e5a 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -2,90 +2,148 @@ Stability: 3 - Locked -All of the timer functions are globals. You do not need to `require()` -this module in order to use them. +The `timer` module exposes a global API for scheduling functions to +be called at some future period of time. Because the timer functions are +globals, there is no need to call `require('timers')` to use the API. -## clearImmediate(immediateObject) +The timer functions within Node.js implement a similar API as the timers API +provided by Web Browsers but use a different internal implementation that is +built around [the Node.js Event Loop][]. -Stops an `immediateObject`, as created by [`setImmediate`][], from triggering. +## Class: Immediate -## clearInterval(intervalObject) +This object is created internally and is returned from [`setImmediate()`][]. It +can be passed to [`clearImmediate()`][] in order to cancel the scheduled +actions. -Stops an `intervalObject`, as created by [`setInterval`][], from triggering. +## Class: Timeout -## clearTimeout(timeoutObject) +This object is created internally and is returned from [`setTimeout()`][] and +[`setInterval()`][]. It can be passed to [`clearTimeout`][] or +[`clearInterval()`][] (respectively) in order to cancel the scheduled actions. -Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering. +By default, when a timer is scheduled using either [`setTimeout`] or +[`setInterval()`][], the Node.js event loop will continue running as long as the +timer is active. Each of the `Timeout` objects returned by these functions +export both `timeout.ref()` and `timeout.unref()` functions that can be used to +control this default behavior. -## ref() +### timeout.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. +When called, requests that the Node.js event loop *not* exit so long as the +`Timeout` is active. Calling `timeout.ref()` multiple times will have no effect. -Returns the timer. +*Note*: By default, all `Timeout` objects are "ref'd", making it normally +unnecessary to call `timeout.ref()` unless `timeout.unref()` had been called +previously. -## setImmediate(callback[, arg][, ...]) +Returns a reference to the `Timeout`. -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. +### timeout.unref() -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. +When called, the active `Timeout` object will not require the Node.js event loop +to remain active. If there is no other activity keeping the event loop running, +the process may exit before the `Timeout` object's callback is invoked. Calling +`timout.unref()` multiple times will have no effect. -If `callback` is not a function `setImmediate()` will throw immediately. +*Note*: Calling `timout.unref()` creates an internal timer that will wake the +Node.js event loop. Creating too many of these can adversely impact performance +of the Node.js application. -## setInterval(callback, delay[, arg][, ...]) +Returns a reference to the `Timeout`. + +## Scheduling Timers + +A timer in Node.js is an internal construct that calls a given function after +a certain period of time. When a timer's function is called varies depending on +which method was used to create the timer and what other work the Node.js +event loop is doing. + +### setImmediate(callback[, ...arg]) + +* `callback` {Function} The function to call at the end of this turn of + [the Node.js Event Loop] +* `[, ...arg]` Optional arguments to pass when the `callback` is called. + +Schedules the "immediate" execution of the `callback` after I/O events' +callbacks and before timers created using [`setTimeout()`][] and +[`setInterval()`][] are triggered. Returns an `Immediate` for use with +[`clearImmediate()`][]. + +When multiple calls to `setImmediate()` are made, the `callback` functions are +queued for execution in the order in which they are created. The entire callback +queue is processed every event loop iteration. If an immediate timer is queued +from inside an executing callback, that timer will not be triggered until the +next event loop iteration. + +If `callback` is not a function, a [`TypeError`][] will be thrown. + +### setInterval(callback, delay[, ...arg]) + +* `callback` {Function} The function to call when the timer elapses. +* `delay` {number} The number of milliseconds to wait before calling the + `callback`. +* `[, ...arg]` Optional arguments to pass when the `callback` is called. 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. +Returns a `Timeout` for use with [`clearInterval()`][]. -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`. +When `delay` is larger than `2147483647` or less than `1`, the `delay` will be +set to `1`. -If `callback` is not a function `setInterval()` will throw immediately. +If `callback` is not a function, a [`TypeError`][] will be thrown. -## setTimeout(callback, delay[, arg][, ...]) +### setTimeout(callback, delay[, ...arg]) + +* `callback` {Function} The function to call when the timer elapses. +* `delay` {number} The number of milliseconds to wait before calling the + `callback`. +* `[, ...arg]` Optional arguments to pass when the `callback` is called. 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. +Returns a `Timeout` for use with [`clearTimeout()`][]. -The callback will likely not be invoked in precisely `delay` milliseconds. +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. +*Note*: When `delay` is larger than `2147483647` or less than `1`, the `delay` +will be set to `1`. + +If `callback` is not a function, a [`TypeError`][] will be thrown. + +## Cancelling Timers + +The [`setImmediate()`][], [`setInterval()`][], and [`setTimeout()`][] methods +each return objects that represent the scheduled timers. These can be used to +cancel the timer and prevent it from triggering. + +### clearImmediate(immediate) + +* `immediate` {Immediate} An `Immediate` object as returned by + [`setImmediate()`][]. + +Cancels an `Immediate` object created by [`setImmediate()`][]. + +### clearInterval(timeout) + +* `timeout` {Timeout} A `Timeout` object as returned by [`setInterval()`][]. -If `callback` is not a function `setTimeout()` will throw immediately. +Cancels a `Timeout` object created by [`setInterval()`][]. -## unref() +### clearTimeout(timeout) -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. +* `timeout` {Timeout} A `Timeout` object as returned by [`setTimeout()`][]. -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. +Cancels a `Timeout` object created by [`setTimeout()`][]. -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 +[the Node.js Event Loop]: https://github.com/nodejs/node/blob/master/doc/topics/the-event-loop-timers-and-nexttick.md +[`TypeError`]: errors.html#errors_class_typerror +[`clearImmediate()`]: timers.html#timers_clearimmediate_immediate +[`clearInterval()`]: timers.html#timers_clearinterval_timeout +[`clearTimeout()`]: timers.html#timers_cleartimeout_timeout +[`setImmediate()`]: timers.html#timers_setimmediate_callback_arg +[`setInterval()`]: timers.html#timers_setinterval_callback_delay_arg +[`setTimeout()`]: timers.html#timers_settimeout_callback_delay_arg