This module was mainly written for AnyEvent::XMPP, AnyEvent::IRC, AnyEvent::HTTPD and BK 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.

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 AnyEvent::XMPP the overhead is probably not noticeable, as other technologies like XML already waste a lot more CPU cycles. Also I/O usually introduces _much_ larger/longer overheads than this simple event interface.

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 $guard will be a guard that represents the set of callbacks you have installed. You can either just "forget" the contents of $guard to unregister the callbacks or call unreg_cb with that ID to remove those callbacks again. If reg_cb is called in a void context no guard is returned and you have no chance to unregister the registered callbacks.

The first argument for callbacks registered with the reg_cb function will always be the master object $obj.

The return value of the callbacks are ignored. If you need to pass any information from a handler to the caller of the event you have to establish your own "protocol" to do this. I recommend to pass an array reference to the handlers:

The order of the callbacks in the call chain of the event depends on their priority. If you didn't specify any priority (see below) they get the default priority of 0, and are appended to the other priority 0 callbacks. The higher the priority number, the earlier the callbacks gets called in the chain.

If $eventname1 starts with 'before_' the callback gets a priority of 1000, and if it starts with 'ext_before_' it gets the priority 500. 'after_' is mapped to the priority -1000 and 'ext_after_' to -500.

If you want more fine grained control you can pass an array reference instead of the event name:

Emits the event $eventname and passes the arguments @args to the callbacks. The return value $handled is a true value in case some handler was found and run. It returns false if no handler was found (see also the handles method below). Basically: It returns the same value as the handles method.

Please note that an event can be stopped and reinvoked while it is being handled.

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:

You can define static methods in a package that act as event handler. This is done by using Perl's attributes functionality. To make a method act as event handler you need to add the event_cb attribute to it.

NOTE: Please note that for this to work the methods need to be defined at compile time. This means that you are not able to add event handles using AUTOLOAD!

NOTE: Perl's attributes have a very basic syntax, you have to take care to not insert any whitespace, the attribute must be a single string that contains no whitespace. That means: event_cb (1) is not the same as event_cb(1)!

The ordering of how the methods event handlers are called if they are all defined for the same event is strictly defined:

Ordering of the methods for the same event in the inheritance hierarchy is always dominated by the priority of the event callback.

Then if there are multiple methods with the same priority the place in the inheritance hierarchy defines in which order the methods are executed. The higher up in the hierarchy the class is, the earlier it will be called.

Inside a class the name of the method for the event decides which event is executed first. (All if the priorities are the same)