Module: Ably::Modules::EventEmitter

Includes:
SafeYield
Included in:
Realtime::Channel, Realtime::Connection, Realtime::Connection::WebsocketTransport, Realtime::Models::NilChannel, Realtime::Presence, Realtime::Presence::MembersMap, Util::PubSub
Defined in:
lib/ably/modules/event_emitter.rb

Overview

Note:

This module requires that the method #logger is defined.

EventEmitter provides methods to attach to public events and emit events on any class instance

EventEmitter are typically used for public interfaces, and as such, may be overriden in the classes to enforce ‘event` names match expected values.

Examples:

class Example
  include Modules::EventEmitter
end

event_emitter = Example.new
event_emitter.on(:signal) { |name| puts "Signal #{name} received" }
event_emitter.emit :signal, "Test"
#=> "Signal Test received"

Defined Under Namespace

Modules: ClassMethods

Instance Method Summary collapse

Instance Method Details

#emit(event_name, *args) ⇒ Object

Emits an event, calling registered listeners with the given event name and any other given arguments. If an exception is raised in any of the listeners, the exception is caught by the EventEmitter and the exception is logged to the Ably logger.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/ably/modules/event_emitter.rb', line 90

def emit(event_name, *args)
  [callbacks_any, callbacks[callbacks_event_coerced(event_name)]].each do |callback_arr|
    callback_arr.clone.
    select do |proc_hash|
      if proc_hash[:unsafe]
        proc_hash[:emit_proc].call(*args)
      else
        safe_yield proc_hash[:emit_proc], *args
      end
    end.each do |callback|
      callback_arr.delete callback
    end
  end
end

#off(*event_names, &block) ⇒ void

This method returns an undefined value.

Remove all callbacks for event_name.

If a block is provided, only callbacks matching that block signature will be removed. If block is not provided, all callbacks matching the event_name will be removed.

Parameters:

  • event_names (Array<String>) —

    event name



116
117
118
 
# File 'lib/ably/modules/event_emitter.rb', line 116

def off(*event_names, &block)
  off_internal(false, *event_names, &block)
end

#on(*event_names, &block) ⇒ void

This method returns an undefined value.

On receiving an event matching the event_name, call the provided block

Parameters:

  • event_names (Array<String>) —

    event name



55
56
57
 
# File 'lib/ably/modules/event_emitter.rb', line 55

def on(*event_names, &block)
  add_callback event_names, proc_for_block(block)
end

#once(*event_names, &block) ⇒ void

This method returns an undefined value.

On receiving an event maching the event_name, call the provided block only once and remove the registered callback

Parameters:

  • event_names (Array<String>) —

    event name



74
75
76
 
# File 'lib/ably/modules/event_emitter.rb', line 74

def once(*event_names, &block)
  add_callback event_names, proc_for_block(block, delete_once_run: true)
end

#unsafe_off(*event_names, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Equivalent of #off but only unsafe listeners are removed. This method is designed to be used internally by the client library.



123
124
125
 
# File 'lib/ably/modules/event_emitter.rb', line 123

def unsafe_off(*event_names, &block)
  off_internal(true, *event_names, &block)
end

#unsafe_on(*event_names, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Equivalent of #on but any exception raised in a block will bubble up and cause this client library to fail. This method is designed to be used internally by the client library.



62
63
64
 
# File 'lib/ably/modules/event_emitter.rb', line 62

def unsafe_on(*event_names, &block)
  add_callback event_names, proc_for_block(block, unsafe: true)
end

#unsafe_once(*event_names, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Equivalent of #once but any exception raised in a block will bubble up and cause this client library to fail. This method is designed to be used internally by the client library.



81
82
83
 
# File 'lib/ably/modules/event_emitter.rb', line 81

def unsafe_once(*event_names, &block)
  add_callback event_names, proc_for_block(block, delete_once_run: true, unsafe: true)
end