Class Jabber::CallbackList
In: lib/xmpp4r/callbacks.rb
Parent: Object

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 ?

Methods

add   delete   each   length   new   process  

Included Modules

Enumerable

Public Class methods

Create a new list of callbacks

[Source]

    # File lib/xmpp4r/callbacks.rb, line 45
45:     def initialize
46:       @list = []
47:     end

Public Instance methods

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

[Source]

    # File lib/xmpp4r/callbacks.rb, line 58
58:     def add(prio = 0, ref = nil, proc = nil, &block)
59:       block = proc if proc
60:       @list.push(Callback.new(prio, ref, block))
61:       @list.sort! { |a, b| b.priority <=> a.priority }
62:       self
63:     end

Delete a callback by reference

ref:[String] the reference of the callback to delete
return:[CallBackList] The list, for chaining

[Source]

    # File lib/xmpp4r/callbacks.rb, line 69
69:     def delete(ref)
70:       @list.delete_if { |item| item.ref == ref }
71:       self
72:     end

[Source]

    # File lib/xmpp4r/callbacks.rb, line 74
74:     def each(&block)
75:       @list.each(&block)
76:     end

Number of elements in the list

return:[Integer] The number of elements

[Source]

    # File lib/xmpp4r/callbacks.rb, line 81
81:     def length
82:       @list.length
83:     end

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

[Source]

     # File lib/xmpp4r/callbacks.rb, line 90
 90:     def process(*e)
 91:       # If somebody adds a new callback the list will get modified
 92:       # and sorted(!) while still iterating through it. So we use a
 93:       # local copy of @list. Any freshly added callback will receive
 94:       # the next stanzas, not the current.
 95:       list = @list.dup
 96: 
 97:       # process through callbacks
 98:       list.each do |item|
 99:         return true if item.block.call(*e) == true
100:       end
101:       false
102:     end

[Validate]