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

Emit an event with event_name that will in turn call all matching callbacks setup with ‘on`



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

def emit(event_name, *args)
  callbacks[callbacks_event_coerced(event_name)].
    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|
      callbacks[callbacks_event_coerced(event_name)].delete callback
    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



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/ably/modules/event_emitter.rb', line 110

def off(*event_names, &block)
  keys = if event_names.empty?
    callbacks.keys
  else
    event_names
  end

  keys.each do |event_name|
    if block_given?
      callbacks[callbacks_event_coerced(event_name)].delete_if { |proc_hash| proc_hash[:block] == block }
    else
      callbacks[callbacks_event_coerced(event_name)].clear
    end
  end
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



52
53
54
55
56
 
# File 'lib/ably/modules/event_emitter.rb', line 52

def on(*event_names, &block)
  event_names.each do |event_name|
    callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block)
  end
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



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

def once(*event_names, &block)
  event_names.each do |event_name|
    callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block, delete_once_run: true)
  end
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 should only be used internally by the client library.



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

def unsafe_on(*event_names, &block)
  event_names.each do |event_name|
    callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block, unsafe: true)
  end
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 should only be used internally by the client library.



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

def unsafe_once(*event_names, &block)
  event_names.each do |event_name|
    callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block, delete_once_run: true, unsafe: true)
  end
end