NAME

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

VERSION

Version 0.7

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 released it separately 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.

NOTE: This is the last release that will come with add_forward. The next Object::Event release will contain some minor incompatible changes.

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 hash reference 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 executed 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 ($cb)

Removes the callback $cb from the set of registered callbacks.

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.

unreg_my_set

This method will remove all callbacks registered together with the currently executed callback.

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>

ACKNOWLEDGEMENTS

Thanks to Pedro Melo for fixes and tests.

COPYRIGHT & LICENSE

Copyright 2007-2009 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.