Skip to content

Commit 231092d

Browse files
othiym23bnoordhuis
authored andcommitted
doc: document domain.enter() and domain.exit()
Adds the documentation requested in nodejs#5017.
1 parent 6a7be99 commit 231092d

File tree

1 file changed

+34
-0
lines changed

1 file changed

+34
-0
lines changed

doc/api/domain.markdown

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,6 +384,40 @@ with a single error handler in a single place.
384384
// with the normal line number and stack message.
385385
});
386386

387+
### domain.enter()
388+
389+
The `enter` method is plumbing used by the `run`, `bind`, and `intercept`
390+
methods to set the active domain. It sets `domain.active` and `process.domain`
391+
to the domain, and implicitly pushes the domain onto the domain stack managed
392+
by the domain module (see `domain.exit()` for details on the domain stack). The
393+
call to `enter` delimits the beginning of a chain of asynchronous calls and I/O
394+
operations bound to a domain.
395+
396+
Calling `enter` changes only the active domain, and does not alter the domain
397+
itself. `Enter` and `exit` can be called an arbitrary number of times on a
398+
single domain.
399+
400+
If the domain on which `enter` is called has been disposed, `enter` will return
401+
without setting the domain.
402+
403+
### domain.exit()
404+
405+
The `exit` method exits the current domain, popping it off the domain stack.
406+
Any time execution is going to switch to the context of a different chain of
407+
asynchronous calls, it's important to ensure that the current domain is exited.
408+
The call to `exit` delimits either the end of or an interruption to the chain
409+
of asynchronous calls and I/O operations bound to a domain.
410+
411+
If there are multiple, nested domains bound to the current execution context,
412+
`exit` will exit any domains nested within this domain.
413+
414+
Calling `exit` changes only the active domain, and does not alter the domain
415+
itself. `Enter` and `exit` can be called an arbitrary number of times on a
416+
single domain.
417+
418+
If the domain on which `exit` is called has been disposed, `exit` will return
419+
without exiting the domain.
420+
387421
### domain.dispose()
388422

389423
The dispose method destroys a domain, and makes a best effort attempt to

0 commit comments

Comments
 (0)