1Object::Event(3)      User Contributed Perl Documentation     Object::Event(3)
2
3
4

NAME

6       Object::Event - A class that provides an event callback interface
7

VERSION

9       Version 1.23
10

SYNOPSIS

12          package foo;
13          use Object::Event;
14
15          our @ISA = qw/Object::Event/;
16
17          package main;
18          my $o = foo->new;
19
20          my $regguard = $o->reg_cb (foo => sub {
21             print "I got an event, with these args: $_[1], $_[2], $_[3]\n";
22          });
23
24          $o->event (foo => 1, 2, 3);
25
26          $o->unreg_cb ($regguard);
27          # or just:
28          $regguard = undef;
29

DESCRIPTION

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
36       For more comprehensive event handling see also Glib and POE.
37
38       This class provides a simple way to extend a class, by inheriting from
39       this class, with an event callback interface.
40
41       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
45       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

PERFORMANCE

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

FUNCTIONS

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
62           There are 4 predefined aliases:
63
64              before     =>  1000
65              ext_before =>   500
66              ext_after  =>  -500
67              after      => -1000
68
69           See also the "reg_cb" method for more information about aliases.
70

METHODS

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
77       $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
82       $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
87       $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
93           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
100           The first argument for callbacks registered with the "reg_cb"
101           function will always be the master object $obj.
102
103           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
108              $obj->reg_cb (event_foobar => sub {
109                 my ($self, $results) = @_;
110                 push @$results, time / 30;
111              });
112
113              my @results;
114              $obj->event (event_foobar => \@results);
115              for (@results) {
116                 # ...
117              }
118
119           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
125           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
130           If you want more fine grained control you can pass an array
131           reference instead of the event name:
132
133              ($eventname1, $prio) = ('test_abc', 100);
134              $obj->reg_cb ([$eventname1, $prio] => sub {
135                 ...
136              });
137
138       $obj->unreg_cb ($cb)
139           Removes the callback $cb from the set of registered callbacks.
140
141       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
148           Please note that an event can be stopped and reinvoked while it is
149           being handled.
150
151           See also the specification of the before and after events in
152           "reg_cb" above.
153
154           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
159              $obj->reg_cb (event_test => sub {
160                 my ($obj) = @_;
161
162                 print "Test1\n";
163                 $obj->unreg_me;
164
165                 $obj->reg_cb (event_test => sub {
166                    my ($obj) = @_;
167                    print "Test2\n";
168                    $obj->unreg_me;
169                 });
170              });
171
172              $obj->event ('event_test'); # prints "Test1"
173              $obj->event ('event_test'); # prints "Test2"
174
175       my $bool = $obj->handles ($eventname)
176           This method returns true if any event handler has been setup for
177           the event $eventname.
178
179           It returns false if that is not the case.
180
181       $obj->event_name
182           Returns the name of the currently executed event.
183
184       $obj->unreg_me
185           Unregisters the currently executed callback.
186
187       $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
192       $obj->add_forward ($obj, $cb)
193           DEPRECATED: Don't use it! Just for backward compatibility for
194           AnyEvent::XMPP version 0.4.
195
196       $obj->remove_forward ($obj)
197           DEPRECATED: Don't use it! Just for backward compatibility for
198           AnyEvent::XMPP version 0.4.
199
200       $obj->remove_all_callbacks ()
201           This method removes all registered event callbacks from this
202           object.
203
204       $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

EVENT METHODS

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
213       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
217       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
222       Here is an example:
223
224          package foo;
225          use base qw/Object::Event/;
226
227          sub test : event_cb { print "test event handler!\n" }
228
229          package main;
230          my $o = foo->new;
231          $o->test ();        # prints 'test event handler!'
232          $o->event ('test'); # also prints 'test event handler!'!
233
234       In case you want to set a priority use this syntax:
235
236          sub test : event_cb(-1000) { ... }
237
238       Or:
239
240          sub test : event_cb(after) { ... }
241
242       You may want to have a look at the tests of the Object::Event
243       distribution for more examples.
244
245   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
249          package foo;
250          use base qw/Object::Event/;
251
252          sub test : event_cb { # default prio is always 0
253             print "middle\n";
254          }
255
256          sub test_last : event_cb(-1,test) {
257             print "after\n";
258          }
259
260          sub test_first : event_cb(1,test) {
261             print "before\n";
262          }
263
264          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
270       NOTE: Please note that if you don't provide any order the methods are
271       sorted alphabetically:
272
273          package foo;
274          use base qw/Object::Event/;
275
276          sub test : event_cb { # default prio is always 0
277             print "middle\n";
278          }
279
280          sub x : event_cb(, test) { # please note the empty element before the ','!
281             print "after\n";
282          }
283
284          sub a : event_cb(, test) {
285             print "before\n";
286          }
287
288          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
294   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
298       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
302       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
307       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

DEBUGGING

311       There exists a package global variable called $DEBUG that control
312       debugging capabilities.
313
314       Set it to 1 to produce a slightly extended "events_as_string_dump"
315       output.
316
317       Set it to 2 and all events will be dumped in a tree of event
318       invocations.
319
320       You can set the variable either in your main program:
321
322          $Object::Event::DEBUG = 2;
323
324       Or use the environment variable "PERL_OBJECT_EVENT_DEBUG":
325
326          export PERL_OBJECT_EVENT_DEBUG=2
327

AUTHOR

329       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
330

SUPPORT

332       You can find documentation for this module with the perldoc command.
333
334           perldoc Object::Event
335
336       You can also look for information at:
337
338       •   AnnoCPAN: Annotated CPAN documentation
339
340           <http://annocpan.org/dist/Object-Event>
341
342       •   CPAN Ratings
343
344           <http://cpanratings.perl.org/d/Object-Event>
345
346       •   RT: CPAN's request tracker
347
348           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Object-Event>
349
350       •   Search CPAN
351
352           <http://search.cpan.org/dist/Object-Event>
353

ACKNOWLEDGEMENTS

355       Thanks go to:
356
357         - 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
363       This program is free software; you can redistribute it and/or modify it
364       under the same terms as Perl itself.
365
366
367
368perl v5.32.1                      2021-01-27                  Object::Event(3)
Impressum