diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown index 7e4efb47c12929..56c41e2de35d93 100644 --- a/doc/api/timers.markdown +++ b/doc/api/timers.markdown @@ -7,19 +7,19 @@ this module in order to use them. ## clearImmediate(immediateObject) -Stops an immediate from triggering. +Stops an `immediateObject`, as created by [`setImmediate`][], from triggering. ## clearInterval(intervalObject) -Stops an interval from triggering. +Stops an `intervalObject`, as created by [`setInterval`][], from triggering. ## clearTimeout(timeoutObject) -Prevents a timeout from triggering. +Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering. ## ref() -If you had previously `unref()`d a timer you can call `ref()` to explicitly +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. @@ -27,14 +27,15 @@ 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. +To schedule the "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 you queue -an immediate from inside an executing callback, that immediate won't fire +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. @@ -42,8 +43,8 @@ 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. +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 @@ -54,8 +55,8 @@ 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. +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, @@ -71,16 +72,20 @@ 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 +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` 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. +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