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