From f26db5bfc435e49037be8464b24e14f716fbf676 Mon Sep 17 00:00:00 2001 From: Bryan English Date: Thu, 14 Apr 2016 15:47:21 -0700 Subject: [PATCH] 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 --- doc/api/timers.md | 69 +++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 29 deletions(-) diff --git a/doc/api/timers.md b/doc/api/timers.md index d33bf1dc22b559..a9ca9dc7047d65 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -5,31 +5,56 @@ All of the timer functions are globals. You do not need to `require()` this module in order to use them. -## clearImmediate(immediateObject) +## Class: Immediate -Stops an `immediateObject`, as created by [`setImmediate`][], from triggering. +This object is created internally and is returned from [`setImmediate`][]. It +can be passed to [`clearImmediate`] in order to cancel the scheduled actions. -## clearInterval(intervalObject) +## Class: Timeout -Stops an `intervalObject`, as created by [`setInterval`][], from triggering. +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. -## clearTimeout(timeoutObject) +### ref() -Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering. +If a `Timeout` was previously `unref()`d, then `ref()` can be called to +explicitly request the `Timeout` hold the program open. If the `Timeout` is +already `ref`d calling `ref` again will have no effect. -## ref() +Returns the `Timeout`. -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. +### unref() -Returns the timer. +The `Timeout` returned by [`setTimeout`][] and [`setInterval`][] also has the +method `timeout.unref()` which allows the creation of a `Timeout` that is active +but if it is the only item left in the event loop, it won't keep the program +running. If the `Timeout` is already `unref`d calling `unref` again will have no +effect. + +In the case of [`setTimeout`][], `unref` creates a separate underlying timer +handle that will wakeup the event loop, creating too many of these may adversely +effect event loop performance -- use wisely. + +Returns the `Timeout`. + +## clearImmediate(immediate) + +Stops an `Immediate`, as created by [`setImmediate`][], from triggering. + +## clearInterval(timeout) + +Stops a `Timeout`, as created by [`setInterval`][], from triggering. + +## clearTimeout(timeout) + +Stops a `Timeout`, as created by [`setTimeout`][], from triggering. ## 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 +callbacks and before timers (`Timeout`s) set by [`setTimeout`][] and +[`setInterval`][] are triggered. Returns an `Immediate` for possible use with [`clearImmediate`][]. Additional optional arguments may be passed to the callback. @@ -43,7 +68,7 @@ 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 +Returns a `Timeout` for possible use with [`clearInterval`][]. Additional optional arguments may be passed to the callback. To follow browser behavior, when using delays larger than 2147483647 @@ -55,7 +80,7 @@ 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 +Returns a `Timeout` 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. @@ -69,20 +94,6 @@ 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