domains: deprecate domain.dispose().

Follows @isaacs's recommendations in joyent/node#5018. Includes some
updates to documentation but not examples.

Conflicts:
	lib/domain.js

doc/api/domain.markdown

@@ -420,21 +420,11 @@ without exiting the domain.
 
 ### domain.dispose()
 
-The dispose method destroys a domain, and makes a best effort attempt to
-clean up any and all IO that is associated with the domain.  Streams are
-aborted, ended, closed, and/or destroyed.  Timers are cleared.
-Explicitly bound callbacks are no longer called.  Any error events that
-are raised as a result of this are ignored.
-
-The intention of calling `dispose` is generally to prevent cascading
-errors when a critical part of the Domain context is found to be in an
-error state.
-
-Once the domain is disposed the `dispose` event will emit.
-
-Note that IO might still be performed.  However, to the highest degree
-possible, once a domain is disposed, further errors from the emitters in
-that set will be ignored.  So, even if some remaining actions are still
-in flight, Node.js will not communicate further about them.
+    Stability: 0 - Deprecated.  Please recover from failed IO actions
+    explicitly via error event handlers set on the domain.
+
+Once `dispose` has been called, the domain will no longer be used by callbacks
+bound into the domain via `run`, `bind`, or `intercept`, and a `dispose` event
+is emitted.
 
 [EventEmitter]: events.html#events_class_events_eventemitter

lib/domain.js

@@ -24,9 +24,6 @@ var events = require('events');
 var EventEmitter = events.EventEmitter;
 var inherits = util.inherits;
 
-// methods that are called when trying to shut down explicitly bound EEs
-var endMethods = ['end', 'abort', 'destroy', 'destroySoon'];
-
 // communicate with events module, but don't require that
 // module to have to load this one, since this module has
 // a few side effects.
@@ -259,53 +256,19 @@ Domain.prototype.bind = function(cb, interceptError) {
   return b;
 };
 
-Domain.prototype.dispose = function() {
+Domain.prototype.dispose = util.deprecate(function() {
   if (this._disposed) return;
 
   // if we're the active domain, then get out now.
   this.exit();
 
-  this.emit('dispose');
-
-  // remove error handlers.
-  this.removeAllListeners();
-  this.on('error', function() {});
-
-  // try to kill all the members.
-  // XXX There should be more consistent ways
-  // to shut down things!
-  this.members.forEach(function(m) {
-    // if it's a timeout or interval, cancel it.
-    clearTimeout(m);
-
-    // drop all event listeners.
-    if (m instanceof EventEmitter) {
-      m.removeAllListeners();
-      // swallow errors
-      m.on('error', function() {});
-    }
-
-    // Be careful!
-    // By definition, we're likely in error-ridden territory here,
-    // so it's quite possible that calling some of these methods
-    // might cause additional exceptions to be thrown.
-    endMethods.forEach(function(method) {
-      if (util.isFunction(m[method])) {
-        try {
-          m[method]();
-        } catch (er) {}
-      }
-    });
-
-  });
-
   // remove from parent domain, if there is one.
   if (this.domain) this.domain.remove(this);
 
   // kill the references so that they can be properly gc'ed.
   this.members.length = 0;
 
-  // finally, mark this domain as 'no longer relevant'
+  // mark this domain as 'no longer relevant'
   // so that it can't be entered or activated.
   this._disposed = true;
-};
+});