Class: Jabber::CallbackList

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/xmpp4r/callbacks.rb

Overview

This class manages a list of callbacks.

==Callbacks management and priority

Callbacks are managed by the class CallbackList. When they are added, a priority (just a number or anything Comparable with other priorities) is specified. The biggest the priority is, the earliest the callback will be considered.

Callbacks are processed for a given set of objects as long as they return false. If you want to stop processing, you must return true. Example : cbl = CallbackList.new c1 = false c2 = false c3 = false cbl.add(10) { c1 = true; 1 } cbl.add(5) { c2 = true; true } cbl.add(0) { c3 = true } cbl.process('aa') puts "#c1 #c2 #c3" This example would display "true true false" as callbacks processing was stopped after the second callback returned true.

In XMPP4R, callbacks' priorities are quite normalized since we want to be able to "cascade" callbacks in a clean way. Here are values your code should take into account :

>= 200

logging & debugging callbacks. Those callbacks should not consume elements.

100-199

Where Helpers register their callbacks. The normal value is 100, and Helpers shouldn't register something else unless there's a very good reason to.

< 100

all those numbers are normally available for your application. That's enough, don't you think ?

Instance Method Summary collapse

Constructor Details

#initialize ⇒ CallbackList

Create a new list of callbacks



45
46
47
 
# File 'lib/xmpp4r/callbacks.rb', line 45

def initialize
  @list = []
end

Instance Method Details

#add(prio = 0, ref = nil, proc = nil, &block) ⇒ Object

Add a callback to the list

List will be sorted afterwards

prio

[Integer] the callback's priority, the higher, the sooner.

ref

[String] the callback's reference

block

[Block] a block to execute

return

[Jabber::CallbackList] The list, for chaining



58
59
60
61
62
63
 
# File 'lib/xmpp4r/callbacks.rb', line 58

def add(prio = 0, ref = nil, proc = nil, &block)
  block = proc if proc
  @list.push(Callback.new(prio, ref, block))
  @list.sort! { |a, b| b.priority <=> a.priority }
  self
end

#delete(ref) ⇒ Object

Delete a callback by reference

ref

[String] the reference of the callback to delete

return

[CallBackList] The list, for chaining



69
70
71
72
 
# File 'lib/xmpp4r/callbacks.rb', line 69

def delete(ref)
  @list.delete_if { |item| item.ref == ref }
  self
end

#each(&block) ⇒ Object 



74
75
76
 
# File 'lib/xmpp4r/callbacks.rb', line 74

def each(&block)
  @list.each(&block)
end

#length ⇒ Object

Number of elements in the list

return

[Integer] The number of elements



81
82
83
 
# File 'lib/xmpp4r/callbacks.rb', line 81

def length
  @list.length
end

#process(*e) ⇒ Object

Process an element through all my callbacks. returns e.consumed?

e

[Object] The elements to pass to the callback. You can pass

several, but of course, you block must know how to handle them.

return

[Boolean] true if the element has been consumed



90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/xmpp4r/callbacks.rb', line 90

def process(*e)
  # If somebody adds a new callback the list will get modified
  # and sorted(!) while still iterating through it. So we use a
  # local copy of @list. Any freshly added callback will receive
  # the next stanzas, not the current.
  list = @list.dup

  # process through callbacks
  list.each do |item|
    return true if item.block.call(*e) == true
  end
  false
end