Are domain.enter() and domain.exit() officially supported APIs?

[hueniverse]

They are very useful when domain.run() is too restrictive in what is actually running inside (e.g. callback outside the protected realm). Since they are not listed in the docs, I want to make sure.

[isaacs]

They're tricky to get right. If you enter a domain, you have to be sure you exit it at the right time. The reason that they're not documented is that no one's taken the time to spell out the issues, and domain.run(fn) is much easier to get right.

Doc patch welcome, of course.

[hueniverse]

Is the main concern that there is no symmetry?

enter A, enter B, exit A, exit B - Bad
enter A, enter B, exit B, exit A - Good

[othiym23]

It's a little more complicated than that; if you do something like a.enter() → b.enter() → c.enter() → a.exit(), both b and c will be exited as well due to how domains nest. So yeah, you have to watch the symmetry, but also you need to be aware of how the nesting works. This is especially important because the nesting rules work for error handling but not for general-purpose state propagation (see #3733 for why this is a problem).

[hueniverse]

Much appreciated.