Poe-component-syndicator is a project mainly written in Perl, it's free.
A POE component base class which implements the Observer pattern
=encoding utf8
=head1 NAME
POE::Component::Syndicator - A POE component base class which implements the Observer pattern
=head1 SYNOPSIS
package POE::Component::IRC;
use strict; use warnings; use POE; use base 'POE::Component::Syndicator';
sub spawn { my ($package, %args) = @_;
# process arguments...
my $self = bless \%args, $package;
# set up our plugin system and POE session
$self->_syndicator_init(
prefix => 'irc_',
reg_prefix => 'PCI_',
types => [SERVER => 'S', USER => 'U'],
object_states => [qw(
syndicator_started
shutdown
)],
);
return $self;
}
sub syndicatorstarted { my ($kernel, $self) = @[KERNEL, OBJECT];
# connect to a server, etc...
}
sub S_hlagh {
}
sub shutdown { my ($kernel, $self) = @_[KERNEL, OBJECT];
# disconnect from a server, etc...
# shut down the syndicator
$self->_syndicator_destroy();
}
=head1 DESCRIPTION
POE::Component::Syndicator is a base class for POE components which need to handle a persistent resource (e.g. a connection to an IRC server) for one or more sessions in an extendable way.
This module (as well as L<Object::Pluggable|Object::Pluggable>, which this module inherits from) was born out of L<POE::Component::IRC|POE::Component::IRC>, the guts of which quickly spread to other POE components. Now they can all inherit from this module instead.
The component provides an event queue, which can be managed with the methods documented below. It handles delivery of events to the object itself, all interested plugins, and all interested sessions.
=head2 Component lifetime
You start by calling L<C<_syndicator_init>|/_syndicator_init>, which will
create a POE session with your object as its heap, and a few event handlers
installed. The events described in L</Local events> delimit the start and
end of the session's lifetime. In between those, interested plugins and
sessions will receive various events, usually starting with
L<C
=head2 A note on events
In this document, an I
Interested sessions are considered consumers only, so they always receive copies of event arguments, whereas interested plugins and subclasses receive scalar references to them. This allows them to alter, add, or remove event arguments before sessions (or even other plugins) receive them. For more information about plugins, see L<Object::Pluggable|Object::Pluggable>'s documentation. A subclass does not have to register for plugin events.
Two event types are supported: SERVER and USER, though their names can be overriden (see L<C<_syndicator_init>|/_syndicator_init>).
=head3 SERVER events
These represent data received from the network or some other outside resource (usually a server, hence the default name).
SERVER events are generated by the L<C<send_event*>|/send_event> methods.
These events are delivered to the subclass and plugins (method C
=head3 USER events
These represent commands about to be sent to a server or some other resource.
USER events are generated by L<C
=head1 PRIVATE METHODS
The following methods should only be called by a subclass.
=head2 C<_syndicator_init>
You should call this in your constructor. It initializes
L<Object::Pluggable|Object::Pluggable>, creates the Syndicator's POE session,
and calls the L<C
B<'prefix'>, a prefix for all your event names, when sent to interested sessions. If you don't supply this, L<Object::Pluggable|Object::Pluggable>'s default (B<'pluggable'>) will be used.
B<'regprefix'>, the prefix for the C<register()>/C<unregister()> plugin methods If you don't supply this, L<Object::Pluggable|Object::Pluggable>'s default (B<'plugin'>) will be used.
B<'debug'>, a boolean, if true, will cause a warning to be printed every time a plugin event handler raises an exception.
B<'types'>, a 2-element arrayref of the types of events that your component will support, or a 4-element (2 pairs) arrayref where the event types are keys and their abbrevations (used as plugin event method prefixes) are values (see L</A note on events> and L<Object::Pluggable|Object::Pluggable> for more information). The two event types are fundamentally different, so make sure you supply them in the right order. If you don't provide this argument, C<< [ SERVER => 'S', USER => 'U' ] >> will be used.
B<'register_signal'>, the name of the register signal (see L). Defaults to B<'SYNDICATOR_REGISTER'>.
B<'shutdown_signal'>, the name of the shutdown signal (see L). Defaults to B<'SYNDICATOR_SHUTDOWN'>.
B<'object_states'> an arrayref of additional object states to add to
the POE session. Same as the 'object_states' argument to
L<POE::Session|POE::Session>'s C
B<'options'>, a hash of options for L<POE::Session|POE::Session>'s constructor.
If you call C<_syndicator_init> from inside another POE session, the
component will automatically register that session as wanting all events.
That session will first receive a
L<C
=head2 C<_syndicator_destroy>
Call this method when you want Syndicator to clean up (delete all plugins,
etc) and make sure it won't keep the POE session alive after all remaining
events have been processed. A L<C
B
=head1 PUBLIC METHODS
=head2 C
Returns the component's POE session id.
=head2 C
Returns the component's POE session alias.
=head2 C
This method provides an alternative, object-based means of posting events to the component. First argument is the event to post, following arguments are sent as arguments to the resultant post.
=head2 C
This method provides an alternative, object-based means of calling events to the component. First argument is the event to call, following arguments are sent as arguments to the resultant call.
=head2 C
Adds a new SERVER event onto the end of the queue. The event will be processed after other pending events, if any. First argument is an event name, the rest are the event arguments.
$component->send_event('irc_public, '[email protected]', ['#mychan'], 'message');
=head2 C
Adds a new SERVER event to the start of the queue. The event will be the next one to be processed. First argument is an event name, the rest are the event arguments.
=head2 C
Sends a new SERVER event immediately. Execution of the current POE event will be suspended (i.e. this call will block) until the new event has been processed by the component class and all plugins. First argument is an event name, the rest are the event arguments.
=head2 C
Sends a new USER event immediately. You should call this before every command
you send to your remote server/resource. Only the subclass and plugins will
see this event. Takes two arguments, an event name and an arrayref of
arguments. Returns one of the C
$component->send_user_event('PRIVMSG', '#mychan', 'message');
=head2 C
This method provides a way of posting delayed events to the component. The first argument is an arrayref consisting of the delayed command to post and any command arguments. The second argument is the time in seconds that one wishes to delay the command being posted.
my $alarm_id = $component->delay(['mode', $channel, '+o', $dude], 60);
=head2 C
This method removes a previously scheduled delayed event from the component.
Takes one argument, the C that was returned by a
L<C
my $arrayref = $component->delay_remove($alarm_id);
=head1 EVENTS
=head2 Local events
The component will send the following POE events to its session.
=head3 C
Called after the session has been started (like C<_start> in L<POE::Kernel|POE::Kernel/Session Management>. This is where you should do your POE-related setup work such as adding new event handlers to the session.
=head3 C
Called right before the session is about to die (like C<_stop> in L<POE::Kernel|POE::Kernel/Session Management>).
=head2 Input events
Other POE sessions can send the following POE events to the Syndicator's session.
=head3 C
Takes any amount of arguments: a list of event names that your session wants
to listen for, minus the prefix (specified in
L<C
$kernel->post('my syndicator', 'register', qw(join part quit kick));
Registering for the special event B<'all'> will cause it to send all events to your session. Calling it with no event names is equivalent to calling it with B<'all'> as an argumente.
Registering will generate a L<C
Registering with multiple component sessions can be tricky, especially if one wants to marry up sessions/objects, etc. Check the L<SIGNALS|/SIGNALS> section for an alternative method of registering with multiple components.
=head3 C
Takes any amount of arguments: a list of event names which you I<don't> want
to receive. If you've previously done a L<C
If you have registered for the special event B<'all'>, attempting to unregister individual events will not work. This is a 'feature'.
=head3 C
By default, POE::Component::Syndicator sessions never go away. You can send
its session a C
=head3 C<_default>
Any POE events sent to the Syndicator's session which do not have a handler will go to the Syndicator's C<_default> handler, will generate L</USER events> of the same name. If you install your own C<_default> handler, make sure you do the same thing before you handle an event:
use Object::Pluggable::Constants 'PLUGIN_EAT_ALL';
$poe_kernel->state('_default', $self, '__default');
sub _default { my ($self, $event, $args) = @[OBJECT, ARG0, ARG1];
# do nothing if a plugin eats the event
return if $self->send_user_event($event, [@$args]) == PLUGIN_EAT_ALL;
# handle the event
# ...
}
Note that the handler for the C<_default> event must be named something other than '_default', because that name is reserved for the plugin-type default handler (see the L<Object::Pluggable|Object::Pluggable/PLUGINS> docs).
=head2 Output events
The Syndicator will send the following events at various times. The B<'syndicator_'> prefix in these event names can be customized with a B<'prefix'> argument to L<C<_syndicator_init>/_syndicator_init>.
=head3 C
Sent once to the requesting session on registration (see
L<C
=head3 C
Sent to all interested sessions when the component has been shut down. See L<C<_syndicator_destroy>|/_syndicator_destroy>.
=head3 C
Sent to the subclass, plugins, and all interested sessions on a successful
addition of a delayed event using the L<C
=head3 C
Sent to the subclass, plugins, and all interested sessions when a delayed
event is successfully removed. C
=head3 All other events
All other events sent by the Syndicator are USER events (generated with
L<C
=head1 SIGNALS
The component will handle a number of custom signals that you may send using
L<POE::Kernel|POE::Kernel>'s C
=head2 C
Registers for an event with the component. See L<C
=head2 C
Causes a 'shutdown' event to be sent to your session. Any arguments to the signal will be passed along to the event. That's where you should clean up and call L<C<_syndicator_destroy>|/_syndicator_destroy>.
=head1 AUTHOR
Hinrik E
=head1 LICENSE AND COPYRIGHT
Copyright 2011 Hinrik E
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
=cut