-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
178 lines (133 loc) · 6.52 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
NAME
Object::Event - A class that provides an event callback interface
VERSION
Version 0.6
SYNOPSIS
package foo;
use Object::Event;
our @ISA = qw/Object::Event/;
package main;
my $o = foo->new;
my $regid = $o->reg_cb (foo => sub {
print "I got an event, with these args: $_[1], $_[2], $_[3]\n";
});
$o->event (foo => 1, 2, 3);
$o->unreg_cb ($regid);
DESCRIPTION
This module was mainly written for Net::XMPP2, Net::IRC3,
AnyEvent::HTTPD and BS to provide a consistent API for registering and
emitting events. Even though I originally wrote it for those modules I
relased it seperately in case anyone may find this module useful.
For more comprehensive event handling see also Glib and POE.
This class provides a simple way to extend a class, by inheriting from
this class, with an event callback interface.
You will be able to register callbacks for event names and call them
later.
PERFORMANCE
In the first version as presented here no special performance
optimisations have been applied. So take care that it is fast enough for
your purposes. At least for modules like Net::XMPP2 the overhead is
probably not noticeable, as other technologies like XML already waste a
lot more CPU cycles.
METHODS
new (%hashcontent)
This is a convenience constructor. It will create a blessed
hashreference initialized with %hashcontent.
set_exception_cb ($cb)
This method installs a callback that will be called when some other
event callback threw an exception. The first argument to $cb will be
the exception.
reg_cb ($eventname1, $cb1, [$eventname2, $cb2, ...])
This method registers a callback $cb1 for the event with the name
$eventname1. You can also pass multiple of these eventname =>
callback pairs.
The return value will be an ID that represents the set of callbacks
you have installed. Call "unreg_cb" with that ID to remove those
callbacks again.
The callbacks will be called in an array context. If a callback
doesn't want to return any value it should return an empty list. All
results from the callbacks will be appended and returned by the
"event" method.
For every event there will also be two other event callbacks called:
Before the callbacks for $eventname is being exectued the callback
for "before_$eventname" is being called. And after the callbacks for
$eventname have been run, the callback "after_$eventname" is being
called.
The "before_$eventname" callbacks allow you to stop the execution of
all callbacks for the event $eventname and "after_$eventname". This
can be used to intercept events and stop them.
If you give reg_cb a special argument called "_while_referenced" you
can prevent callbacks from being executed once the reference in the
second argument becomes undef. This works by converting the internal
reference of the argument to "_while_referenced" to a weak reference
and looking whether that reference becomes undef.
It works like this:
Scalar::Util::weaken $window;
$event_source->reg_cb (
_while_referenced => $window,
disconnect => sub { $window->destroy }
);
Whenever the "disconnect" event is emitted now and $window doesn't
exist anymore the callback will be removed.
unreg_cb ($id)
Removes the set $id of registered callbacks. $id is the return value
of a "reg_cb" call.
event ($eventname, @args)
Emits the event $eventname and passes the arguments @args. The
return value is a list of defined return values from the event
callbacks.
See also the specification of the before and after events in
"reg_cb" above.
NOTE: Whenever an event is emitted the current set of callbacks
registered to that event will be used. So, if you register another
event callback for the same event that is executed at the moment, it
will be called the next time when the event is emitted. Example:
$obj->reg_cb (event_test => sub {
my ($obj) = @_;
print "Test1\n";
$obj->unreg_me;
$obj->reg_cb (event_test => sub {
print "Test2\n";
$obj->unreg_me;
});
});
$obj->event ('event_test'); # prints "Test1"
$obj->event ('event_test'); # prints "Test2"
_event ($eventname, @args)
This directly executes the event $eventname without executing
callbacks of the before and after events (as specified in "reg_cb"
above).
unreg_me
If this method is called from a callback on the first argument to
the callback (i.e. $self) the callback will be deleted after it is
finished.
stop_event
When called in a 'before_' event callback then the execution of the
event is stopped after all 'before_' callbacks have been run.
When callend in the main event callback, the event is stopped after
all the main event callbacks have been run.
add_forward ($obj, $forward_cb)
This method allows to forward all events to an object. $forward_cb
will be called everytime an event is generated in $self. The first
argument to the callback $forward_cb will be $self, the second will
be $obj, the third will be the event name and the rest will be the
event arguments. (For third and rest of argument also see
description of "event").
(Please note that it might be most useful to call "_event" in the
callback to allow objects that receive the forwarded events to react
better.)
remove_forward ($obj)
This method removes a forward. $obj must be the same object that was
given "add_forward" as the $obj argument.
remove_all_callbacks
This method removes all registered event callbacks and forwards from
this object.
events_as_string_dump
This method returns a string dump of all registered event callbacks.
This method is only for debugging purposes.
AUTHOR
Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
COPYRIGHT & LICENSE
Copyright 2007 Robin Redeker, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.