The Events::Emitter mixin provides a clone of the Node.js EventEmitter API for Ruby.

Instances of classes including Events::Emitter will emit events, events are represented by symbols, underscored in the usual Ruby fashion. Examples: :connection, :data, :message_begin

Blocks can be attached to objects to be executed when an event is emitted, these blocks are called listeners.

All EventEmitters emit the event :new_listener when new listeners are added, this listener is provided with the event and new listener added. Example:

server.on(:new_listener) do |event, listener|
  puts "added new listener #{listener} for event #{event}"
end

server.on(:connection) do |socket|
  puts "someone connected!"
end

Outputs “added new listener #<Proc:[email protected]:12> for event connection”.

The Events::EventEmitter class is provided as a convenience for those who wish to inherit from a class. It simply includes the Events::Emitter module.

emitter.on(event, &block)

Adds a listener to the end of the listeners array for the specified event.

server.on(:connection) do |socket|
  puts "someone connected!"
end

emitter.once(event, &block)

Adds a one time listener for the event. The listener is invoked only the first time the event is fired, after which it is removed.

server.once(:connection) do |socket|
  puts "Ah, we have our first user!"
end

emitter.remove_listener(event, proc)

Remove a listener from the listener array for the specified event.

emitter.max_listeners = n

By default an EventEmitter will print a warning if more than 10 listeners are added to it. This is a useful default which helps finding memory leaks. Obviously not all Emitters should be limited to 10. This method allows that to be increased. Set to zero for unlimited.

emitter.listeners(event)

Returns an array of listeners for the specified event. This array can be manipulated, e.g. to remove listeners.

emitter.emit(event[, arguments...])

Execute each of the listeners in order with the supplied arguments.