doc: add guide for Node.js Timers

Refs: https://github.com/nodejs/docs/issues/76 PR-URL: https://github.com/nodejs/node/pull/6825 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
9 years ago · 1299c2764e
2 changed files with 214 additions and 22 deletions
--- a/doc/guides/timers-in-node.md
+++ b/doc/guides/timers-in-node.md
@ -0,0 +1,192 @@
 ---
 title: Timers in Node.js
 layout: docs.hbs
 ---
 # Timers in Node.js and beyond
 The Timers module in Node.js contains functions that execute code after a set
 period of time. Timers do not need to be imported via `require()`, since
 all the methods are available globally to emulate the browser JavaScript API.
 To fully understand when timer functions will be executed, it's a good idea to
 read up on the the Node.js
 [Event Loop](../topics/the-event-loop-timers-and-nexttick).
 ## Controlling the Time Continuum with Node.js
 The Node.js API provides several ways of scheduling code to execute at
 some point after the present moment. The functions below may seem familiar,
 since they are available in most browsers, but Node.js actually provides
 its own implementation of these methods. Timers integrate very closely
 with the system, and despite the fact that the API mirrors the browser
 API, there are some differences in implementation.
 ### "When I say so" Execution ~ *`setTimeout()`*
 `setTimeout()` can be used to schedule code execution after a designated
 amount of milliseconds. This function is similar to
 [`window.setTimeout()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setTimeout)
 from the browser JavaScript API, however a string of code cannot be passed
 to be executed.
 `setTimeout()` accepts a function to execute as its first argument and the
 millisecond delay defined as a number as the second argument. Additional
 arguments may also be included and these will be passed on to the function. Here
 is an example of that:
 ```js
 function myFunc (arg) {
  console.log('arg was => ' + arg);
 }
 setTimeout(myFunc, 1500, 'funky');
 ```
 The above function `myFunc()` will execute as close to 1500
 milliseconds (or 1.5 seconds) as possible due to the call of `setTimeout()`.
 The timeout interval that is set cannot be relied upon to execute after
 that *exact* number of milliseconds. This is because other executing code that
 blocks or holds onto the event loop will push the execution of the timeout
 back. The *only* guarantee is that the timeout will not execute *sooner* than
 the declared timeout interval.
 `setTimeout()` returns a `Timeout` object that can be used to reference the
 timeout that was set. This returned object can be used to cancel the timeout (
 see `clearTimeout()` below) as well as change the execution behavior (see
 `unref()` below).
 ### "Right after this" Execution ~ *`setImmediate()`*
 `setImmediate()` will execute code at the end of the current event loop cycle.
 This code will execute *after* any I/O operations in the current event loop and
 *before* any timers scheduled for the next event loop. This code execution
 could be thought of as happening "right after this", meaning any code following
 the `setImmediate()` function call will execute before the `setImmediate()`
 function argument.
 The first argument to `setImmediate()` will be the function to execute. Any
 subsequent arguments will be passed to the function when it is executed.
 Here's an example:
 ```js
 console.log('before immediate');
 setImmediate((arg) => {
  console.log(`executing immediate: ${arg}`);
 }, 'so immediate');
 console.log('after immediate');
 ```
 The above function passed to `setImmediate()` will execute after all runnable
 code has executed, and the console output will be:
 ```shell
 before immediate
 after immediate
 executing immediate: so immediate
 ```
 `setImmediate()` returns and `Immediate` object, which can be used to cancel
 the scheduled immediate (see `clearImmediate()` below).
 Note: Don't get `setImmediate()` confused with `process.nextTick()`. There are
 some major ways they differ. The first is that `process.nextTick()` will run
 *before* any `Immediate`s that are set as well as before any scheduled I/O.
 The second is that `process.nextTick()` is non-clearable, meaning once
 code has been scheduled to execute with `process.nextTick()`, the execution
 cannot be stopped, just like with a normal function. Refer to [this guide](../topics/the-event-loop-timers-and-nexttick#processnexttick)
 to better understand the operation of `process.nextTick()`.
 ### "Infinite Loop" Execution ~ *`setInterval()`*
 If there is a block of code that should execute multiple times, `setInterval()`
 can be used to execute that code. `setInterval()` takes a function
 argument that will run an infinite number of times with a given millisecond
 delay as the second argument. Just like `setTimeout()`, additional arguments
 can be added beyond the delay, and these will be passed on to the function call.
 Also like `setTimeout()`, the delay cannot be guaranteed because of operations
 that may hold on to the event loop, and therefore should be treated as an
 approximate delay. See the below example:
 ```js
 function intervalFunc () {
  console.log('Cant stop me now!');
 }
 setInterval(intervalFunc, 1500);
 ```
 In the above example, `intervalFunc()` will execute about every 1500
 milliseconds, or 1.5 seconds, until it is stopped (see below).
 Just like `setTimeout()`, `setInterval()` also returns a `Timeout` object which
 can be used to reference and modify the interval that was set.
 ## Clearing the Future
 What can be done if a `Timeout` or `Immediate` object needs to be cancelled?
 `setTimeout()`, `setImmediate()`, and `setInterval()` return a timer object
 that can be used to reference the set `Timeout` or `Immediate` object.
 By passing said object into the respective `clear` function, execution of
 that object will be halted completely. The respective functions are
 `clearTimeout()`, `clearImmediate()`, and `clearInterval()`. See the example
 below for an example of each:
 ```js
 let timeoutObj = setTimeout(() => {
  console.log('timeout beyond time');
 }, 1500);
 let immediateObj = setImmediate(() => {
  console.log('immediately executing immediate');
 });
 let intervalObj = setInterval(() => {
  console.log('interviewing the interval');
 }, 500);
 clearTimeout(timeoutObj);
 clearImmediate(immediateObj);
 clearInterval(intervalObj);
 ```
 ## Leaving Timeouts Behind
 Remember that `Timeout` objects are returned by `setTimeout` and `setInterval`.
 The `Timeout` object provides two functions intended to augment `Timeout`
 behavior with `unref()` and `ref()`. If there is a `Timeout` object scheduled
 using a `set` function, `unref()` can be called on that object. This will change
 the behavior slightly, and not call the `Timeout` object *if it is the last
 code to execute*. The `Timeout` object will not keep the process alive, waiting
 to execute.
 In similar fashion, a `Timeout` object that has had `unref()` called on it
 can remove that behavior by calling `ref()` on that same `Timeout` object,
 which will then ensure its execution. Be aware, however, that this does
 not *exactly* restore the initial behavior for performance reasons. See
 below for examples of both:
 ```js
 let timerObj = setTimeout(() => {
  console.log('will i run?');
 });
 // if left alone, this statement will keep the above
 // timeout from running, since the timeout will be the only
 // thing keeping the program from exiting
 timerObj.unref();
 // we can bring it back to life by calling ref() inside
 // an immediate
 setImmediate(() => {
  timerObj.ref();
 });
 ```
 ## Further Down the Event Loop
 There's much more to the Event Loop and Timers than this guide
 has covered. To learn more about the internals of the Node.js
 Event Loop and how Timers operate during execution, check out
 this Node.js guide: [The Node.js Event Loop, Timers, and
 process.nextTick()](../topics/the-event-loop-timers-and-nexttick).