From 231092d236de590a7448ed4257e121f308875326 Mon Sep 17 00:00:00 2001 From: Forrest L Norvell Date: Thu, 14 Mar 2013 13:31:18 -0700 Subject: [PATCH] doc: document domain.enter() and domain.exit() Adds the documentation requested in #5017. --- doc/api/domain.markdown | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/doc/api/domain.markdown b/doc/api/domain.markdown index b93c3fcd62..d3b714c85d 100644 --- a/doc/api/domain.markdown +++ b/doc/api/domain.markdown @@ -384,6 +384,40 @@ with a single error handler in a single place. // with the normal line number and stack message. }); +### domain.enter() + +The `enter` method is plumbing used by the `run`, `bind`, and `intercept` +methods to set the active domain. It sets `domain.active` and `process.domain` +to the domain, and implicitly pushes the domain onto the domain stack managed +by the domain module (see `domain.exit()` for details on the domain stack). The +call to `enter` delimits the beginning of a chain of asynchronous calls and I/O +operations bound to a domain. + +Calling `enter` changes only the active domain, and does not alter the domain +itself. `Enter` and `exit` can be called an arbitrary number of times on a +single domain. + +If the domain on which `enter` is called has been disposed, `enter` will return +without setting the domain. + +### domain.exit() + +The `exit` method exits the current domain, popping it off the domain stack. +Any time execution is going to switch to the context of a different chain of +asynchronous calls, it's important to ensure that the current domain is exited. +The call to `exit` delimits either the end of or an interruption to the chain +of asynchronous calls and I/O operations bound to a domain. + +If there are multiple, nested domains bound to the current execution context, +`exit` will exit any domains nested within this domain. + +Calling `exit` changes only the active domain, and does not alter the domain +itself. `Enter` and `exit` can be called an arbitrary number of times on a +single domain. + +If the domain on which `exit` is called has been disposed, `exit` will return +without exiting the domain. + ### domain.dispose() The dispose method destroys a domain, and makes a best effort attempt to