Node.js API —— Events（事件）

// 说明

    Node API 版本为 v0.10.31。
    中文参考：http://nodeapi.ucdok.com/#/api/，http://blog.sina.com.cn/oleoneoy

    本段为博主注解。

目录

● 事件
    ○ Class: events.EventEmitter

       ■ emitter.addListener(event, listener)

       ■ emitter.on(event, listener)

       ■ emitter.once(event, listener)

       ■ emitter.removeListener(event, listener)

       ■ emitter.removeAllListener([events])

       ■ emitter.setMaxListener(n)

       ■ emitter.listeners(event)

       ■ emitter.emit(event, [arg1], [arg2], [...])

       ■ Class Method: EventEmitter.listenerCount(emitter, event)

       ■ Event: 'new listener'

       ■ Event: 'removeListener'

 事件

稳定性：4 - API 冻结

    Node 的不少对象都会发射事件：net.Server 在每次对等链接链接过来时发射一个事件，fs.readStream 在文件打开时发射一个事件。全部发射事件的对象都是 events.eventEmitter 的实例。你能够这样来访问本模块：require("events");
    典型地，事件名用一个驼峰格式字符串表明，然而，那没有任何严格的约束，由于任何的字符串均可被接受。
    而后函数就能够被关联到对象上，当一个事件被发射后函数会被执行。这些函数被称为监听器。在监听器函数里面，this 指向监听器关联的 EventEmitter。

Class: events.EventEmitter

    为了访问 EventEmitter 类，require('events').EventEmitter。
    当一个 EventEmitter 实例遇到一个错误，典型的操做是发射一个 'error' 事件。 在node 中 Error 事件做为特殊状况对待。若是它没有任何监听器，那么默认的操做是打印堆栈跟踪信息而后退出程序。
    全部的 EventEmitter 都会在新的监听器添加时发射事件 'newListener'，在监听器移除时发射事件 'removeListener'。

emitter.addListener(event, listener)
emitter.on(event, listener)

    为特定的事件添加一个监听器到监听器数组的末尾。

1 server.on('connection', function(stream) {
2   console.log('someone connected!');
3 });

    返回发射器，于是能够链式调用。

emitter.once(event, listener)

   为事件添加一个执行一次的监听器。监听器只在下次事件触发的时候调用，以后它会被移除。

1 server.once('connection', function(streams) {
2   console.log('Ah, we have our first user!');
3 });

   返回发射器，于是能够链式调用。

emitter.removeListener(event, listener)

    为指定的事件从监听器数组里移除指定的监听器。警告：这将改变该监听器后面的监听器元素的数组下标。

1 var callback = function(stream) {
2   console.log('someone connected!');
3 };
4 server.on('connection', callback);
5 // ...
6 server.removeListener('connection', callback);

     返回发射器，于是能够链式调用。

emitter.removeAllListener([event])

    移除全部的监听器，或特定时间的全部监听器。移除在代码其它地方添加的监听器不是一个好主意，特别是当它关联在一个不是你建立的发射器上（例如 socket 或文件流）。
    返回发射器，于是能够链式调用。

emitter.setMaxListeners(n)

     默认状况下若是超过10个监听器被添加到特定的事件上， EventEmitter 将打印一个警告。这是一个有用的默认值，能够帮助找到内存泄露。明显地不是全部发射器应该限制为10。本函数容许它增加。若无限制设置为0。

emitter.listeners(event)

    返回特定事件的监听器数组。

1 server.on('connection', function(stream) {
2   console.log('someone connected!');
3 });
4 console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]

emitter.emit(event, [arg1], [arg2], [...])

    使用提供的参数按顺序执行每一个监听器。
    若是有监听器返回 true，不然返回 false。

Class Method: EventEmitter.listenerCount(emitter, event)

    返回给出事件的监听器数量。

Event: 'newListener'

    ● event 字符串类型 事件名
    ● listener 函数类型 事件处理函数

    在每次添加新的监听器时本事件被发射。若是 listener 在 emitter.listeners(event) 返回的列表中，本函数的行为未明确指明。

Event: 'removeListener'

    ● event 字符串类型 事件名
    ● listener 函数类型 事件处理函数

    在每次移除监听器时本事件被发射。若是 listener 在 emitter.listeners(event) 返回的列表中，本函数的行为未明确指明。