一起读nodejs(八)----域(domain)

　　  本文是对nodejs0.8.9版本的api开发手册解读.nodejs网址
　　
　　  域(Domain)
　　  stability:1 - experimental
　　  域提供了一种简单把多个不同的io操作看作一个单独的组的方法.如果任何一个事件发射器或者已在域中注册的回调函数发出了一个error事件,或者抛出一个error错误信息,域将会被通知,而不是在process.on('caughtException')处理函数一样丢失上下文,或者用一个code引起程序退出.(有点像数据库的事物的样子)
　　  这是在node0.8版本中新增加的特性.这是它第一次亮相,其他它能在未来有更重要的作用.请使用它,并提供使用反馈.
　　  由于它的试验性质,域的特性只有在domain模块加载一次以后才会生效.没有域是默认被创建或者注册的.这是故意设计成这样的,为了避免在现在的程序中产生一些不利的影响.在未来node的版本中期待改成默认启用.
　　

　　 错误对象的补充(additions to Error objects)
　　  任何时候一个error对象被路由传递到一个domain(域看着别扭)中时,需要添加一些额外的字段到error对象上.

• error.domainThe domain that first handled the error.第一次处理error的domain对象
  
• error.domain_emitterThe event emitter that emitted an 'error' event with the error object.发出error事件的对象.
  
• error.domain_boundThe callback function which was bound to the domain, and passed an error as its first
  argument.绑定到domain上的callback,callback的第一个参数需要指定为error.
  
• error.domain_thrownA boolean indicating whether the error was thrown, emitted, or passed to a bound callback
  function.一个boolean对象,指定这个error对象是被抛出的还是发出的,或者传到到domain 绑定的callback中.
  

　　  当一个EventEmitter遇到一个错误时,典型的动作时发出一个error事件.在node里面,error事件将会被作为特殊情况处理,如果没有相应的监听函数,默认的动作是打印堆栈信息,然后退出程序.
　　  当所有的EventEmitter对象在添加新的监听函数时都会发出newListener事件.
　　  
隐式绑定(Implicit Binding)
　　  如果domain被启用的,那么所有的新的EventEmitter对象(包括:Stream对象,request对象,response对象等等)都将会在他们被创建的时候隐式的绑定到这个激活的domain上.
　　  此外,传递给低级别的事件循环请求(例如:fs.open,或者的callback-taking方法)将会自动的绑定到激活的domain上.如果他们抛出异常,domain会捕获错误信息.
　　  为了避免使用过多的内存,domain对象不会被隐式的添加为当前激活的domain的子对象.如果他们存在,这将不容易阻止request和response对象成为合适的垃圾收集对象.
　　  如果你需要内嵌一个domain对象到一个父domain对象中,你必须明确的添加他们,并且稍后调用dispose()方法(dispose是销毁domain对象,稍后有介绍).
　　  隐式绑定路由跑出错误信息和error事件到domain的error事件中.但是不会在domain对象上注册事件触发器,所以domain.dispose()不会关闭事件触发器.隐式绑定只是处理抛出的错误信息和error事件.
　　

　　  显示绑定(Explicit binding)
　　  有时,domain对象不应该被当成一个指定事件的事件发射器(Emitter)来使用.或者,事件发射器已经在一个domain中的环境变量中被创建,但是应该被绑定到其他domain上.
　　  例如这里有一个http服务器的domain对象,但是我们想在每个request上使用一个单独的domain.
　　  通过显示绑定就有可能实现.
　　  例如:

// create a top-level domain for the server
var serverDomain = domain.create();
serverDomain.run(function() {
// server is created in the scope of serverDomain
http.createServer(function(req, res) {
// req and res are also created in the scope of serverDomain
// however, we'd prefer to have a separate domain for each request.
// create it first thing, and add req and res to it.
var reqd = domain.create();
reqd.add(req);
reqd.add(res);
reqd.on('error', function(er) {
console.error('Error', er, req.url);
try {
res.writeHead(500);
res.end('Error occurred, sorry.');
res.on('close', function() {
// forcibly shut down any other things added to this domain
reqd.dispose();
});
} catch (er) {
console.error('Error sending 500', er, req.url);
// tried our best.  clean up anything remaining.
reqd.dispose();
}
});
}).listen(1337);
});
　　


　　  domain.create()

• return:Domain
  

  返回一个新的domain对象.
　　


　　  Class:Domain

  domain类封装了路由error和uncaught 异常到基于的domain中.

  domain类是EventEmitter的一个子类,如果想要处理domain捕获的错误信息,可以监听error事件.
　　


　　  domain.run(fn)

• fnFunction
  

  在domain的上下文中运行提供的function,隐式绑定所有的事件触发器,定时器,和在domain上下文中创建的低级的requests.

  这是使用domain最基本的一种方式.

  例子:
var d = domain.create();
d.on('error', function(er) {
console.error('Caught error!', er);
});
d.run(function() {
process.nextTick(function() {
setTimeout(function() { // simulating some various async stuff
fs.open('non-existent file', 'r', function(er, fd) {
if (er) throw er;
// proceed...
});
}, 100);
});
});


  在这个例子中,do.on('error')处理器将会被触发,而不是程序挂掉.(在不使用domain的情况下,遇见未捕获的异常或者抛出error事件会导致程序死掉.)



　　  domain.members

• Array
  

  显示绑定到domain中的定时器和事件触发器的数组.




　　  domain.add(emitter)

• event Emitter|timer Emitter|timer to be added to the domain. 事件触发器或者定时器触发器或者定时器被添加到domain中.
  

  显式的添加一个触发器到domain中.当事件触发器抛出一个错误时任何一个事件处理函数被调用时,或者这个事件触发器发出一个error时,他们都将会被路由到domain的error事件中,就像隐式绑定一样.

  当定时器从setInterval或者setTimeout返回时也将这样操作.如果他们的回调函数抛出异常时,将会被domain的error事件处理函数所捕获.

  如果定时器或者事件触发器已经绑定到了domain中,node会将他们从原先的domain中移除,并且添加到当前的domain中.



　　  domain.remove(emitter)

• event Emitter|timer Emitter|timer to be added to the domain. 事件触发器或者定时器触发器或者定时器被从domain中移除.
  

  和domain.add(emitter)相反,这个方法是从指定的触发器上移除domain的处理操作.



　　


　　  domain.bind(cb)

• cb function 回调函数.
  
• return:function,绑定后的函数.
  

  返回的函数,将是一个包裹了所提供的回调函数的函数.当这个返回的函数被调用,抛出的任何错误都将会被路由到domain的error事件中.
var d = domain.create();
function readSomeFile(filename, cb) {
fs.readFile(filename, 'utf8', d.bind(function(er, data) {
// if this throws, it will also be passed to the domain
return cb(er, data ? JSON.parse(data) : null);
}));
}
d.on('error', function(er) {
// an error occurred somewhere.
// if we throw it now, it will crash the program
// with the normal line number and stack message.
});



　　  domain.intercept(cb)

• cb function 回调函数.
  
• return:function,被拦截的函数.
  

  这个方法几乎和domain.bind(cb)方法一样.然而,除了会捕获抛出的错误信息之外,将会拦截error对象,并当作需要返回的函数的第一个参数.

  这样一来,比较常见的:if(er)return cb(er)这种方式就可以被取代,你只需要单独的在一个错误处理handler里面处理所有的error信息了.
　　
  例子:

var d = domain.create();
function readSomeFile(filename, cb) {
fs.readFile(filename, 'utf8', d.intercept(function(data) {
//也就是说只要使用了d.intercept()方法包裹的回调函数,如果他们发生错误或者发出error事件,都会被统一的下面的d.on('error',fn)所处理.这种情况和domain.run的区别是domain.run是需要所有的把所有东西都放在一个domain里面,才能拦截domain的对象的事件.而domain.intercept(),你想包裹哪一个回调函数都行.可以对异常类型进行全局处理.
// note, the first argument is never passed to the
// callback since it is assumed to be the 'Error' argument
// and thus intercepted by the domain.
// if this throws, it will also be passed to the domain
// so the error-handling logic can be moved to the 'error'
// event on the domain instead of being repeated throughout
// the program.
return cb(null, JSON.parse(data));
}));
}
d.on('error', function(er) {
// an error occurred somewhere.
// if we throw it now, it will crash the program
// with the normal line number and stack message.
});
　　


　　

domain.dispose()
　　  dispose方法用来销毁一个domain对象,并且在清空任何一个和所有io和这个domain有关联的对象或事件时,努力做到最好.流(Streams)可以被终止,结束,关闭,并且/或者 销毁.定时器是被清除.显示绑定的回调函数不会在会调用.任何一个从domain中出现的error事件也会被忽略.
　　  调用dispose的意图通常是为了当domain的环境变量被发现在一个错误的状态时避免发生级联错误.
　　  一旦domain被disposed掉,dispose事件将会发出.
　　  注意:io操作可能还会继续执行.然而,为了达到最大限度的可能性,一旦一个domain被disposed,在domain中的发射器集合中产生的或者发出的错误信息将会被忽略.所以,甚至如果一些剩下的动作依然在执行,node也不会在和他们有深层次的交流.