README
1NAME
2 Object::Event - A class that provides an event callback interface
3
4VERSION
5 Version 1.22
6
7SYNOPSIS
8 package foo;
9 use Object::Event;
10
11 our @ISA = qw/Object::Event/;
12
13 package main;
14 my $o = foo->new;
15
16 my $regguard = $o->reg_cb (foo => sub {
17 print "I got an event, with these args: $_[1], $_[2], $_[3]\n";
18 });
19
20 $o->event (foo => 1, 2, 3);
21
22 $o->unreg_cb ($regguard);
23 # or just:
24 $regguard = undef;
25
26DESCRIPTION
27 This module was mainly written for AnyEvent::XMPP, AnyEvent::IRC,
28 AnyEvent::HTTPD and BK to provide a consistent API for registering and
29 emitting events. Even though I originally wrote it for those modules I
30 released it separately in case anyone may find this module useful.
31
32 For more comprehensive event handling see also Glib and POE.
33
34 This class provides a simple way to extend a class, by inheriting from
35 this class, with an event callback interface.
36
37 You will be able to register callbacks for events, identified by their
38 names (a string) and call them later by invoking the "event" method with
39 the event name and some arguments.
40
41 There is even a syntactic sugar which allows to call methods on the
42 instances of Object::Event-derived classes, to invoke events. For this
43 feature see the "EVENT METHODS" section of this document.
44
45PERFORMANCE
46 In the first version as presented here no special performance
47 optimisations have been applied. So take care that it is fast enough for
48 your purposes. At least for modules like AnyEvent::XMPP the overhead is
49 probably not noticeable, as other technologies like XML already waste a
50 lot more CPU cycles. Also I/O usually introduces _much_ larger/longer
51 overheads than this simple event interface.
52
53FUNCTIONS
54 Object::Event::register_priority_alias ($alias, $priority)
55 This package function will add a global priority alias. If $priority
56 is undef the alias will be removed.
57
58 There are 4 predefined aliases:
59
60 before => 1000
61 ext_before => 500
62 ext_after => -500
63 after => -1000
64
65 See also the "reg_cb" method for more information about aliases.
66
67METHODS
68 Object::Event->new (%args)
69 Your::Subclass::Of::Object::Event->new (%args)
70 This is the constructor for Object::Event, it will create a blessed
71 hash reference initialized with %args.
72
73 $obj->init_object_events ()
74 This method should only be called if you are not able to call the
75 "new" constructor of this class. Then you need to call this method
76 to initialize the event system.
77
78 $obj->set_exception_cb ($cb->($exception, $eventname))
79 This method installs a callback that will be called when some other
80 event callback threw an exception. The first argument to $cb will be
81 the exception and the second the event name.
82
83 $guard = $obj->reg_cb ($eventname => $cb->($obj, @args), ...)
84 $guard = $obj->reg_cb ($eventname => $prio, $cb->($obj, @args), ...)
85 This method registers a callback $cb1 for the event with the name
86 $eventname1. You can also pass multiple of these eventname =>
87 callback pairs.
88
89 The return value $guard will be a guard that represents the set of
90 callbacks you have installed. You can either just "forget" the
91 contents of $guard to unregister the callbacks or call "unreg_cb"
92 with that ID to remove those callbacks again. If "reg_cb" is called
93 in a void context no guard is returned and you have no chance to
94 unregister the registered callbacks.
95
96 The first argument for callbacks registered with the "reg_cb"
97 function will always be the master object $obj.
98
99 The return value of the callbacks are ignored. If you need to pass
100 any information from a handler to the caller of the event you have
101 to establish your own "protocol" to do this. I recommend to pass an
102 array reference to the handlers:
103
104 $obj->reg_cb (event_foobar => sub {
105 my ($self, $results) = @_;
106 push @$results, time / 30;
107 });
108
109 my @results;
110 $obj->event (event_foobar => \@results);
111 for (@results) {
112 # ...
113 }
114
115 The order of the callbacks in the call chain of the event depends on
116 their priority. If you didn't specify any priority (see below) they
117 get the default priority of 0, and are appended to the other
118 priority 0 callbacks. The higher the priority number, the earlier
119 the callbacks gets called in the chain.
120
121 If $eventname1 starts with 'before_' the callback gets a priority of
122 1000, and if it starts with 'ext_before_' it gets the priority 500.
123 'after_' is mapped to the priority -1000 and 'ext_after_' to -500.
124
125 If you want more fine grained control you can pass an array
126 reference instead of the event name:
127
128 ($eventname1, $prio) = ('test_abc', 100);
129 $obj->reg_cb ([$eventname1, $prio] => sub {
130 ...
131 });
132
133 $obj->unreg_cb ($cb)
134 Removes the callback $cb from the set of registered callbacks.
135
136 my $handled = $obj->event ($eventname, @args)
137 Emits the event $eventname and passes the arguments @args to the
138 callbacks. The return value $handled is a true value in case some
139 handler was found and run. It returns false if no handler was found
140 (see also the "handles" method below). Basically: It returns the
141 same value as the "handles" method.
142
143 Please note that an event can be stopped and reinvoked while it is
144 being handled.
145
146 See also the specification of the before and after events in
147 "reg_cb" above.
148
149 NOTE: Whenever an event is emitted the current set of callbacks
150 registered to that event will be used. So, if you register another
151 event callback for the same event that is executed at the moment, it
152 will be called the next time when the event is emitted. Example:
153
154 $obj->reg_cb (event_test => sub {
155 my ($obj) = @_;
156
157 print "Test1\n";
158 $obj->unreg_me;
159
160 $obj->reg_cb (event_test => sub {
161 my ($obj) = @_;
162 print "Test2\n";
163 $obj->unreg_me;
164 });
165 });
166
167 $obj->event ('event_test'); # prints "Test1"
168 $obj->event ('event_test'); # prints "Test2"
169
170 my $bool = $obj->handles ($eventname)
171 This method returns true if any event handler has been setup for the
172 event $eventname.
173
174 It returns false if that is not the case.
175
176 $obj->event_name
177 Returns the name of the currently executed event.
178
179 $obj->unreg_me
180 Unregisters the currently executed callback.
181
182 $continue_cb = $obj->stop_event
183 This method stops the execution of callbacks of the current event,
184 and returns (in non-void context) a callback that will let you
185 continue the execution.
186
187 $obj->add_forward ($obj, $cb)
188 DEPRECATED: Don't use it! Just for backward compatibility for
189 AnyEvent::XMPP version 0.4.
190
191 $obj->remove_forward ($obj)
192 DEPRECATED: Don't use it! Just for backward compatibility for
193 AnyEvent::XMPP version 0.4.
194
195 $obj->remove_all_callbacks ()
196 This method removes all registered event callbacks from this object.
197
198 $obj->events_as_string_dump ()
199 This method returns a string dump of all registered event callbacks.
200 This method is only for debugging purposes.
201
202EVENT METHODS
203 You can define static methods in a package that act as event handler.
204 This is done by using Perl's attributes functionality. To make a method
205 act as event handler you need to add the "event_cb" attribute to it.
206
207 NOTE: Please note that for this to work the methods need to be defined
208 at compile time. This means that you are not able to add event handles
209 using "AUTOLOAD"!
210
211 NOTE: Perl's attributes have a very basic syntax, you have to take care
212 to not insert any whitespace, the attribute must be a single string that
213 contains no whitespace. That means: "event_cb (1)" is not the same as
214 event_cb(1)!
215
216 Here is an example:
217
218 package foo;
219 use base qw/Object::Event/;
220
221 sub test : event_cb { print "test event handler!\n" }
222
223 package main;
224 my $o = foo->new;
225 $o->test (); # prints 'test event handler!'
226 $o->event ('test'); # also prints 'test event handler!'!
227
228 In case you want to set a priority use this syntax:
229
230 sub test : event_cb(-1000) { ... }
231
232 Or:
233
234 sub test : event_cb(after) { ... }
235
236 You may want to have a look at the tests of the Object::Event
237 distribution for more examples.
238
239 ALIASES
240 If you want to define multiple event handlers as package method you can
241 use the "event_cb" attribute with an additional argument:
242
243 package foo;
244 use base qw/Object::Event/;
245
246 sub test : event_cb { # default prio is always 0
247 print "middle\n";
248 }
249
250 sub test_last : event_cb(-1,test) {
251 print "after\n";
252 }
253
254 sub test_first : event_cb(1,test) {
255 print "before\n";
256 }
257
258 package main;
259 my $o = foo->new;
260 $o->test (); # prints "after\n" "middle\n" "before\n"
261 $o->event ('test'); # prints the same
262 $o->test_first (); # also prints the same
263
264 NOTE: Please note that if you don't provide any order the methods are
265 sorted *alphabetically*:
266
267 package foo;
268 use base qw/Object::Event/;
269
270 sub test : event_cb { # default prio is always 0
271 print "middle\n";
272 }
273
274 sub x : event_cb(, test) { # please note the empty element before the ','!
275 print "after\n";
276 }
277
278 sub a : event_cb(, test) {
279 print "before\n";
280 }
281
282 package main;
283 my $o = foo->new;
284 $o->test (); # prints "after\n" "middle\n" "before\n"
285 $o->event ('test'); # prints the same
286 $o->x (); # also prints the same
287
288 ALIAS ORDERING
289 The ordering of how the methods event handlers are called if they are
290 all defined for the same event is strictly defined:
291
292 1. Ordering of the methods for the same event in the inheritance
293 hierarchy is always dominated by the priority of the event callback.
294
295 2. Then if there are multiple methods with the same priority the place
296 in the inheritance hierarchy defines in which order the methods are
297 executed. The higher up in the hierarchy the class is, the earlier
298 it will be called.
299
300 3. Inside a class the name of the method for the event decides which
301 event is executed first. (All if the priorities are the same)
302
303DEBUGGING
304 There exists a package global variable called $DEBUG that control
305 debugging capabilities.
306
307 Set it to 1 to produce a slightly extended "events_as_string_dump"
308 output.
309
310 Set it to 2 and all events will be dumped in a tree of event
311 invocations.
312
313 You can set the variable either in your main program:
314
315 $Object::Event::DEBUG = 2;
316
317 Or use the environment variable "PERL_OBJECT_EVENT_DEBUG":
318
319 export PERL_OBJECT_EVENT_DEBUG=2
320
321AUTHOR
322 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
323
324SUPPORT
325 You can find documentation for this module with the perldoc command.
326
327 perldoc Object::Event
328
329 You can also look for information at:
330
331 * AnnoCPAN: Annotated CPAN documentation
332
333 <http://annocpan.org/dist/Object-Event>
334
335 * CPAN Ratings
336
337 <http://cpanratings.perl.org/d/Object-Event>
338
339 * RT: CPAN's request tracker
340
341 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Object-Event>
342
343 * Search CPAN
344
345 <http://search.cpan.org/dist/Object-Event>
346
347ACKNOWLEDGEMENTS
348 Thanks go to:
349
350 - Mons Anderson for suggesting the 'handles' method and
351 the return value of the 'event' method and reporting bugs.
352
353COPYRIGHT & LICENSE
354 Copyright 2009 Robin Redeker, all rights reserved.
355
356 This program is free software; you can redistribute it and/or modify it
357 under the same terms as Perl itself.
358
359