joyent/node — pull request #5990 by othiym23 (2013-08-04 00:16:03+00:00)
Title: WIP: add new continuation-local-storage module

This module adds continuation-local storage that works analogously to the thread-local variables used in multithreaded programming. It allows you to set variables specific to a particular request or handler execution, and can be used to create things like pure-JS execution tracers and long stacktrace generators, and to replace the grotesque hack of stashing per-request state on `req` and `res`. It is also a more generalized version of `domains`, and is intended, eventually, to be used as the mechanism by which domains are implemented.

This is the first part of an implementation of the API described on #5243 & #3733. There is also a [userland implementation](https://github.com/othiym23/node-continuation-local-storage) of the API and [another module that monkeypatches the API](https://github.com/othiym23/node-continuation-local-storage-glue) onto 0.10. @creationix and I have been hacking on this for a few months now and feel pretty good about the core API.

So far, this PR includes the core API (with its documentation) as well as a sort of hacky implementation that applies over `process.nextTick` and the timer functions (`setImmediate`, `setTimeout`, and `setInterval`). The next piece of work @creationix and I intend to tackle is dealing with Make(Domain)Callback and net.Socket. The final step is to rework domains to run on top of this and to take advantage, as much as possible, of the optimization work that @trevnorris has already put into domains.

All of the tests pass and there is a first pass of the documentations, but I haven't done any benchmarking yet. Style and performance review on what's there so far would be great. I know this thing is wacky and may be coming out of nowhere for some of you, but @isaacs and I have been talking about this for a while and I think we're agreed that it's useful (and low-level) enough to belong in core.