Class::Publisher - A simple publish-subscribe event framework
# Define a class that publishes events package My::Widget; use base 'Class::Publisher'; # Publish event sub incriment { my ($self) = @_; my $old_value = $self->{value}++; $self->notify_subscribers('changed', old_value => $old_value); } # Define a subscriber; package My::Subscriber; sub new { my $self = bless {}, shift; # Subscribe to events from My::Widget My::Widget->add_subscriber('changed', sub {$self->_widgetvalue(@_)}); # Subscribe to all events from My::Widget My::Widget->add_subscriber('*', \&_on_update_widget); return $self; } sub _widgetvalue { my $self = shift; my ($item, $event, %params) = @_; # do something with new/old value } sub _on_update_widget { my ($item, $event, %params) = @_; print STDERR "Caught event $event from '$item'\n"; }
Class::Publisher impliments the Publish-Subscribe pattern (also referred to as the Observer pattern). It is often used in user interfaces when many entities are interested in a particular event. The Publish-Subscribe pattern decouples the publisher and subscriber and provides a generic interface for publishing and subscribing to events.
This module is based on Class::Observable by Chris Winters. The main difference is that entities can subscribe to specific events raised by the publisher rather than receiving all notifications.
Like Class::Observable, entities can subscribe to events raised by a publisher class or a publisher instance:
My::Widget->add_subscriber('update', \&_on_widget_update); $widget->('update', sub {print STDERR "$widget raised update event"});
The publisher does not need to implement any extra methods or variables. Whenever it wants to let subscribers know about an event, it just needs to call notify_subscribers().
notify_subscribers()
As noted above, it does not matter if the publisher is a class or object -- the behavior is the same. The difference comes in determining which subscribers are to be notified:
If the publisher is a class, all objects instantiated from that class will use these subscribers. In addition, all subclasses and objects instantiated from the subclasses will use these subscribers.
If the publisher is an object, only that particular object will use its subscribers. Once it falls out of scope then the subscribers will no longer be available. (See "Publisher Objects and DESTROY" below.)
There are three types of subscribers: classes, objects and subroutines. They all respond to events raised by the publisher's notify_subscribers() method.
The following parameters are passed to subscribers:
The publisher class or object that generated the event
The name of the event or '*' if no event was defined for the event
'*'
Additional parameters passed to the notify_subscribers() method
Class and object subscribers differ slightly by being passed their class name/object an additional parameter before the publisher item
Class subscribers are notified of events via the class's update() method:
update()
package My::Subscriber; sub update { my ($class, $publisher, $event, @args) = @_; if ($event eq 'reload') { # ... } elsif ($event eq 'refresh') { } # ... }
Class notifications can be routed to other methods. See add_subscriber().
add_subscriber()
Object subscribers are notified of events via the object's update() method:
package My::Subscriber; sub update { my ($self, $publisher, $event, @args) = @_; # ... }
Object notifications can be routed to other methods. See add_subscriber().
package My::Subscriber; sub _refresh { my ($publisher, $event, @args) = @_; # ... } sub _reload { my $self = shift; my ($publisher, $event, @args) = @_; # ... } sub _catch_all { # ... } My::Publisher->add_subscriber('_refresh', \&_refresh); My::Publisher->add_subscriber('_refresh', sub {$self->_reload(@_)}); My::Publisher->add_subscriber('*', \&_catch_all);
One problem with this module relates to subscribed objects. Once the publisher goes out of scope, its subscribers will still be hanging around. For one-off scripts this is not a problem, but for long-lived processes this could be a memory leak.
To take care of this, it is a good idea to explicitly release subscribers attached to an object in the DESTROY method. This should suffice:
DESTROY
sub DESTROY { my ( $self ) = @_; $self->delete_all_subscribers; }
Registers a subscriber to receive event notifications on the publisher. Each subscriber can be a class name, object or subroutine -- see Subscribers.
Object and class notifications can be routed to $method_name if defined. Otherwise the default update() method will be called.
$method_name
If $event is undefined or '', the subscribers will be subscribed to the special event '*' that receives notifications of all events. Otherwise, the subscribers will only receive notifications when the notification event matches $event.
$event
''
Returns: The number of subscribers of the given topic.
Notify subscribers of a event.
$event and @params are optional. If a $event is given, subscribers to that event are notified. Subscribers to '*' (all events) are always notified.
@params
Unsubscribes a subscriber from the given event on the publishing item.
If $event is undefined, all subscriptions will be cancelled for the subscribers.
Returns: The number of remaining subscribers of the given topic.
Unsubscribes all subscribers from the publisher.
Returns: the number of subscribers removed
Return the subscribers for the given event. All subscribers for all events will be returned if no event is given.
Copy subscribers to another publisher item.
Returns: the number of subscribers copied
Return a count of the subscribers for the given event (or all subscribers of no event was given).
Class::Publisher has Log::Trace hooks. You can enable debugging with a statement like this:
Class::Publisher
Log::Trace
use Log::Trace warn => {Deep => 1, Match => 'Class::Publisher'};
See Log::Trace for more options
Simon Flack
Based quite heavily on Class::Observable by Chris Winters
Class::Publisher is free software which you can redistribute and/or modify under the same terms as Perl itself.
Class::Observable
Class::ISA
Class::Trigger
Aspect
To install Class::Publisher, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Class::Publisher
CPAN shell
perl -MCPAN -e shell install Class::Publisher
For more information on module installation, please visit the detailed CPAN module installation guide.