view release on metacpan or  search on metacpan

lib/Class/Publisher.pm  view on Meta::CPAN

=head2 Publisher classes and objects

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 C<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:

=over 4

=item *

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.

=item *

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 L<Publisher Objects and DESTROY> below.)

=back

=head2 Subscribers

There are three types of subscribers: classes, objects and subroutines. They
all respond to events raised by the publisher's C<notify_subscribers()> method.

The following parameters are passed to subscribers:

=over 4

=item *

The publisher class or object that generated the event

=item *

The name of the event or C<'*'> if no event was defined for the event

=item *

Additional parameters passed to the C<notify_subscribers()> method

=back

Class and object subscribers differ slightly by being passed their class
name/object an additional parameter before the publisher item

=over 4

=item Class subscribers

Class subscribers are notified of events via the class's C<update()> method:

    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 C<add_subscriber()>.

=item Object subscribers

Object subscribers are notified of events via the object's C<update()> method:

    package My::Subscriber;

    sub update {
        my ($self, $publisher, $event, @args) = @_;
        # ...
    }

Object notifications can be routed to other methods. See C<add_subscriber()>.

=item Subroutine subscribers

    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);

=back

=head2 Publisher Objects and DESTROY

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 C<DESTROY> method. This should
suffice:

  sub DESTROY {
      my ( $self ) = @_;
      $self->delete_all_subscribers;
  }

=head1 METHODS

=over 4

=item add_subscriber($event, $subscriber, [$method_name])

Registers a subscriber to receive event notifications on the publisher. Each
subscriber can be a class name, object or subroutine -- see L<Subscribers>.

Object and class notifications can be routed to C<$method_name> if
defined. Otherwise the default C<update()> method will be called.

If C<$event> is undefined or C<''>, the subscribers will be subscribed to the