Skip to content

Commit

Permalink
doc: grammar, clarity and links in timers doc
Browse files Browse the repository at this point in the history
Added appropriate in-document links. Clarified a bit of
`setImmediate`, including a quick grammar fix (plural possessive
apostrophe).

PR-URL: #5792
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
  • Loading branch information
bengl authored and benjamingr committed Mar 21, 2016
1 parent f158a86 commit 0fd3327
Showing 1 changed file with 23 additions and 18 deletions.
41 changes: 23 additions & 18 deletions doc/api/timers.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -7,43 +7,44 @@ 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.

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.

## 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
Expand All @@ -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,
Expand All @@ -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

0 comments on commit 0fd3327

Please sign in to comment.