Node.js v0.11.11 マニュアル & ドキュメンテーション

Events#

Stability: 4 - API Frozen

Node のオブジェクトの多くはイベントを生成します: net.Serverは相手から接続するたびにイベントを生成し、 fs.readStreamはファイルがオープンされるたびにイベントを生成します。 イベントを生成する全てのオブジェクトは events.EventEmitter のインスタンスです。 次のようにすることでこのモジュールにアクセスできます: require("events");

通常、イベント名はキャメル記法による文字列で表現されますが、 厳格な制限ではなく、どんな文字列でも受け入れられます。

関数をオブジェクトにアタッチすることができ、それはイベントが生成された時に実行されます。 これらの関数はリスナと呼ばれます。 リスナ関数の中では、this はリスナがアタッチされている EventEmitter を参照します。

Class: events.EventEmitter#

EventEmitterクラスにアクセスするには、require('events').EventEmitter を使います。

EventEmitter のインスタンスがエラーに遭遇した時、 典型的な動作は 'error' イベントを生成することです。 node ではエラーイベントは特別に扱われます． もしそのリスナーがなければ、デフォルトの動作はスタックトレースを出力してプログラムを終了することです。

全ての EventEmitter は、新しいリスナーが加えられるとイベント 'newListener' を生成し、リスナーが削除されると 'removeListener' を生成します。

emitter.addListener(event, listener)#

emitter.on(event, listener)#

指定されたイベントに対するリスナー配列の最後にリスナーを追加します。 

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

EventEmitter 自身を返すので、呼び出しをチェーンすることができます。

emitter.once(event, listener)#

一回限りのリスナーをイベントに追加します。 このリスナーは次にイベントが発生した時に限り起動され、その後で削除されます。 

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

EventEmitter 自身を返すので、呼び出しをチェーンすることができます。

emitter.removeListener(event, listener)#

指定されたイベントに対するリスナー配列からリスナーを削除します。 注意: リスナーの背後にあるリスナー配列のインデックスが変化します。 

var callback = function(stream) {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

EventEmitter 自身を返すので、呼び出しをチェーンすることができます。

emitter.removeAllListeners([event])#

全てのリスナーまたは指定されたイベントに対するリスナーを削除します。

EventEmitter 自身を返すので、呼び出しをチェーンすることができます。

emitter.setMaxListeners(n)#

デフォルトでは、10 を越えるリスナが特定のイベントに追加されると、 EventEmitter は警告を出力します。 これはメモリリークを見つけるために役に立つデフォルト値です。 全ての EventEmitter が 10 に制限されなければならないわけではないことは 明らかです。この関数は制限を増やすことを許可します。 0 を設定すると無制限になります。

EventEmitter 自身を返すので、呼び出しをチェーンすることができます。

EventEmitter.defaultMaxListeners#

emitter.setMaxListeners(n) はインスタンス毎の上限を設定します。 このクラスプロパティは、現在と将来の 全ての EventEmitter インスタンスの上限を即座に設定します。 注意して使用してください。

emitter.setMaxListeners(n) は EventEmitter.defaultMaxListeners よりも 優先されることに注意してください。

emitter.listeners(event)#

指定されたイベントに対するリスナー配列を返します。 

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

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

提供された引数の並びでそれぞれのリスナーを実行します。

イベントに対応するリスナがあった場合は true、それ以外は false を返します。

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

与えられたイベントのリスナー数を返します。

Event: 'newListener'#

  • event String The event name
  • listener Function The event handler function

このイベントは新しいリスナーが追加されるたびに生成されます。 emitter.listeners(event) が返すリストに listener が含まれるかどうかは未定義です。

Event: 'removeListener'#

  • event {String} イベント名
  • listener {Function} イベントハンドラ関数

このイベントはリスナが取り除かれるたびに生成されます。 emitter.listeners(event) が返すリストに listener が含まれるかどうかは未定義です。