doc/api/timers.markdown

   1 # Timers
   2
   3     Stability: 3 - Locked
   4
   5 All of the timer functions are globals.  You do not need to `require()`
   6 this module in order to use them.
   7
   8 ## clearImmediate(immediateObject)
   9
  10 Stops an `immediateObject`, as created by [`setImmediate`][], from triggering.
  11
  12 ## clearInterval(intervalObject)
  13
  14 Stops an `intervalObject`, as created by [`setInterval`][], from triggering.
  15
  16 ## clearTimeout(timeoutObject)
  17
  18 Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering.
  19
  20 ## ref()
  21
  22 If a timer was previously `unref()`d, then `ref()` can be called to explicitly
  23 request the timer hold the program open. If the timer is already `ref`d calling
  24 `ref` again will have no effect.
  25
  26 Returns the timer.
  27
  28 ## setImmediate(callback[, arg][, ...])
  29
  30 Schedules "immediate" execution of `callback` after I/O events'
  31 callbacks and before timers set by [`setTimeout`][] and [`setInterval`][] are
  32 triggered. Returns an `immediateObject` for possible use with
  33 [`clearImmediate`][]. Additional optional arguments may be passed to the
  34 callback.
  35
  36 Callbacks for immediates are queued in the order in which they were created.
  37 The entire callback queue is processed every event loop iteration. If an
  38 immediate is queued from inside an executing callback, that immediate won't fire
  39 until the next event loop iteration.
  40
  41 ## setInterval(callback, delay[, arg][, ...])
  42
  43 Schedules repeated execution of `callback` every `delay` milliseconds.
  44 Returns a `intervalObject` for possible use with [`clearInterval`][]. Additional
  45 optional arguments may be passed to the callback.
  46
  47 To follow browser behavior, when using delays larger than 2147483647
  48 milliseconds (approximately 25 days) or less than 1, Node.js will use 1 as the
  49 `delay`.
  50
  51 ## setTimeout(callback, delay[, arg][, ...])
  52
  53 Schedules execution of a one-time `callback` after `delay` milliseconds.
  54 Returns a `timeoutObject` for possible use with [`clearTimeout`][]. Additional
  55 optional arguments may be passed to the callback.
  56
  57 The callback will likely not be invoked in precisely `delay` milliseconds.
  58 Node.js makes no guarantees about the exact timing of when callbacks will fire,
  59 nor of their ordering. The callback will be called as close as possible to the
  60 time specified.
  61
  62 To follow browser behavior, when using delays larger than 2147483647
  63 milliseconds (approximately 25 days) or less than 1, the timeout is executed
  64 immediately, as if the `delay` was set to 1.
  65
  66 ## unref()
  67
  68 The opaque value returned by [`setTimeout`][] and [`setInterval`][] also has the
  69 method `timer.unref()` which allows the creation of a timer that is active but
  70 if it is the only item left in the event loop, it won't keep the program
  71 running. If the timer is already `unref`d calling `unref` again will have no
  72 effect.
  73
  74 In the case of [`setTimeout`][], `unref` creates a separate timer that will
  75 wakeup the event loop, creating too many of these may adversely effect event
  76 loop performance -- use wisely.
  77
  78 Returns the timer.
  79
  80 [`clearImmediate`]: timers.html#timers_clearimmediate_immediateobject
  81 [`clearInterval`]: timers.html#timers_clearinterval_intervalobject
  82 [`clearTimeout`]: timers.html#timers_cleartimeout_timeoutobject
  83 [`setImmediate`]: timers.html#timers_setimmediate_callback_arg
  84 [`setInterval`]: timers.html#timers_setinterval_callback_delay_arg
  85 [`setTimeout`]: timers.html#timers_settimeout_callback_delay_arg