diff options
| author | Anatoli Papirovski <apapirovski@mac.com> | 2018-01-14 00:51:28 +0300 |
|---|---|---|
| committer | Anatoli Papirovski <apapirovski@mac.com> | 2018-01-18 23:55:59 +0300 |
| commit | c1234673bbba1ac6c8425dffb2604ccf647bbfcf (patch) | |
| tree | a23f91d29eb1c1209e74c37b2aef8ef8a98b5e76 /doc/api/timers.md | |
| parent | 7809f386b03d6f2f570fe41060a7ef6e158f5cdb (diff) | |
timers: allow Immediates to be unrefed
Refactor Immediates handling to allow for them to be unrefed, similar
to setTimeout, but without extra handles.
Document the new `immediate.ref()` and `immediate.unref()` methods.
Add SetImmediateUnref on the C++ side.
PR-URL: https://github.com/nodejs/node/pull/18139
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'doc/api/timers.md')
| -rw-r--r-- | doc/api/timers.md | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/doc/api/timers.md b/doc/api/timers.md index 09502dee100..13f2dea37d9 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -18,6 +18,38 @@ This object is created internally and is returned from [`setImmediate()`][]. It can be passed to [`clearImmediate()`][] in order to cancel the scheduled actions. +By default, when an immediate is scheduled, the Node.js event loop will continue +running as long as the immediate is active. The `Immediate` object returned by +[`setImmediate()`][] exports both `immediate.ref()` and `immediate.unref()` +functions that can be used to control this default behavior. + +### immediate.ref() +<!-- YAML +added: REPLACEME +--> + +When called, requests that the Node.js event loop *not* exit so long as the +`Immediate` is active. Calling `immediate.ref()` multiple times will have no +effect. + +*Note*: By default, all `Immediate` objects are "ref'd", making it normally +unnecessary to call `immediate.ref()` unless `immediate.unref()` had been called +previously. + +Returns a reference to the `Immediate`. + +### immediate.unref() +<!-- YAML +added: REPLACEME +--> + +When called, the active `Immediate` object will not require the Node.js event +loop to remain active. If there is no other activity keeping the event loop +running, the process may exit before the `Immediate` object's callback is +invoked. Calling `immediate.unref()` multiple times will have no effect. + +Returns a reference to the `Immediate`. + ## Class: Timeout This object is created internally and is returned from [`setTimeout()`][] and |