Provided by: libpoe-component-syndicator-perl_0.06-1_all bug


       POE::Component::Syndicator - A POE component base class which implements the Observer


        package POE::Component::IRC;

        use strict;
        use warnings;
        use POE;
        use base 'POE::Component::Syndicator';

        # our constructor
        sub spawn {
            my ($package, %args) = @_;

            # process arguments...

            my $self = bless \%args, $package;

            # set up our plugin system and POE session
                prefix        => 'irc_',
                reg_prefix    => 'PCI_',
                types         => [SERVER => 'S', USER => 'U'],
                object_states => [qw(

            return $self;

        sub syndicator_started {
            my ($kernel, $self) = @_[KERNEL, OBJECT];

            # connect to a server, etc...

        # plugin handler for SERVER event 'hlagh'
        sub S_hlagh {
            # ...

        sub shutdown {
            my ($kernel, $self) = @_[KERNEL, OBJECT];

            # disconnect from a server, etc...

            # shut down the syndicator


       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 Object::Pluggable, which this module inherits from) was born out
       of 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.

   Component lifetime
       You start by calling "_syndicator_init", which will create a POE session with your object
       as its heap, and a few event handlers installed. The events described in "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 "syndicator_registered".
       In this phase, your subclass and plugins can call the methods and send the events
       documented below. When the component has been shut down, sessions (but not plugins) will
       receive a "syndicator_shutdown" event. After this, the component will become unusable.

   A note on events
       In this document, an event (unless explicitly referred to as a POE event) is defined as a
       message originating from POE::Component::Syndicator, delivered to plugins (and the
       subclass) via plugin methods and to registered sessions as POE events.

       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 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 overridden (see

       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 "send_event*" methods.  These events are delivered to
       the subclass and plugins (method "S_foo") and interested sessions (event

       USER events

       These represent commands about to be sent to a server or some other resource.

       USER events are generated by "send_user_event". In addition, all POE events sent to this
       component's session (e.g. with "yield") which do not have a handler will generate
       corresponding USER events. USER events are considered more private, so they are only
       delivered to the subclass and plugins, not to sessions.


       The following methods should only be called by a subclass.

       You should call this in your constructor. It initializes Object::Pluggable, creates the
       Syndicator's POE session, and calls the "syndicator_started" POE events. It takes the
       following arguments:

       'prefix', a prefix for all your event names, when sent to interested sessions. If you
       don't supply this, Object::Pluggable's default ('pluggable') will be used.

       'reg_prefix', the prefix for the "register()"/"unregister()" plugin methods  If you don't
       supply this, Object::Pluggable's default ('plugin_') will be used.

       'debug', a boolean, if true, will cause a warning to be printed every time a plugin event
       handler raises an exception.

       '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 "A note on events" and 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, "[ SERVER => 'S', USER
       => 'U' ]" will be used.

       'register_signal', the name of the register signal (see "SIGNALS").  Defaults to

       'shutdown_signal', the name of the shutdown signal (see "SIGNALS").  Defaults to

       'object_states' an arrayref of additional object states to add to the POE session. Same as
       the 'object_states' argument to POE::Session's "create" method. You'll want to add a
       handler for at least the "syndicator_started" event.

       'options', a hash of options for POE::Session's constructor.

       If you call "_syndicator_init" from inside another POE session, the component will
       automatically register that session as wanting all events.  That session will first
       receive a "syndicator_registered" event.

       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
       "syndicator_shutdown" event (or similar, depending on the prefix you chose) will be
       generated.  Any argument passed to "_syndicator_destroy" will be passed along with that

       Note: this method will clear all alarms for the POE session.


       Returns the component's POE session id.

       Returns the component's POE session alias.

       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.

       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.

       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, 'foo!', ['#mychan'], 'message');

       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.

       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.

       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 "EAT" constants
       listed in Object::Pluggable::Constants. After this method returns, the arrayref's contents
       may have been modified by the subclass or plugins.

        $component->send_user_event('PRIVMSG', '#mychan', 'message');

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

       This method removes a previously scheduled delayed event from the component.  Takes one
       argument, the "alarm_id" that was returned by a "delay" method call. Returns an arrayref
       of arguments to the event that was originally requested to be delayed.

        my $arrayref = $component->delay_remove($alarm_id);


   Local events
       The component will send the following POE events to its session.


       Called after the session has been started (like "_start" in POE::Kernel. This is where you
       should do your POE-related setup work such as adding new event handlers to the session.


       Called right before the session is about to die (like "_stop" in POE::Kernel).

   Input events
       Other POE sessions can send the following POE events to the Syndicator's session.


       Takes any amount of arguments: a list of event names that your session wants to listen
       for, minus the prefix (specified in "_syndicator_init" in "syndicator_init").

        $kernel->post('my syndicator', 'register', qw(join part quit kick));

       Registering for the special event 'all' will cause it to send all events to your session.
       Calling it with no event names is equivalent to calling it with 'all' as an argumente.

       Registering will generate a "syndicator_registered" event that your session can trap.

       Registering with multiple component sessions can be tricky, especially if one wants to
       marry up sessions/objects, etc. Check the SIGNALS section for an alternative method of
       registering with multiple components.


       Takes any amount of arguments: a list of event names which you don't want to receive. If
       you've previously done a "register" for a particular event which you no longer care about,
       this event will tell the component to stop sending them to you. (If you haven't, it just
       ignores you. No big deal.) Calling it with no event names is equivalent to calling it with
       'all' as an argument.

       If you have registered for the special event 'all', attempting to unregister individual
       events will not work. This is a 'feature'.


       By default, POE::Component::Syndicator sessions never go away. You can send its session a
       "shutdown" event manually to make it delete itself.  Terminating multiple Syndicators can
       be tricky. Check the "SIGNALS" section for a method of doing that.


       Any POE events sent to the Syndicator's session which do not have a handler will go to the
       Syndicator's "_default" handler, will generate "USER events" of the same name. If you
       install your own "_default" handler, make sure you do the same thing before you handle an

        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 "_default" event must be named something other than
       '_default', because that name is reserved for the plugin-type default handler (see the
       Object::Pluggable docs).

   Output events
       The Syndicator will send the following events at various times. The 'syndicator_' prefix
       in these event names can be customized with a 'prefix' argument to "_syndicator_init" in


       Sent once to the requesting session on registration (see "register"). "ARG0" is a
       reference to the component's object.


       Sent to all interested sessions when the component has been shut down. See


       Sent to the subclass, plugins, and all interested sessions on a successful addition of a
       delayed event using the "delay" method. "ARG0" will be the alarm_id which can be used
       later with "delay_remove".  Subsequent parameters are the arguments that were passed to


       Sent to the subclass, plugins, and all interested sessions when a delayed event is
       successfully removed. "ARG0" will be the alarm_id that was removed.  Subsequent parameters
       are the arguments that were passed to "delay".

       All other events

       All other events sent by the Syndicator are USER events (generated with "send_user_event")
       and SERVER events (generated with "send_event*") which will be delivered normally. Your
       subclass and plugins are responsible for generating them.


       The component will handle a number of custom signals that you may send using POE::Kernel's
       "signal" method. They allow any session to communicate with every instance of the
       component in certain ways without having references to their objects or knowing about
       their sessions. The names of these signals can be customized with "_syndicator_init".

       Registers for an event with the component. See "register".

       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


       Hinrik Oern Sigur`sson,, Chris "BinGOs" Williams, Apocalypse, and probably others.


       Copyright 2011 Hinrik Oern Sigur`sson

       This program is free software, you can redistribute it and/or modify it under the same
       terms as Perl itself.