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

SYNOPSIS
     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
         $self->_syndicator_init(
             prefix        => 'irc_',
             reg_prefix    => 'PCI_',
             types         => [SERVER => 'S', USER => 'U'],
             object_states => [qw(
                 syndicator_started
                 shutdown
             )],
         );

         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
         $self->_syndicator_destroy();
     }

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 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 overriden (see "_syndicator_init").

   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 "syndicator_foo").

   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.

PRIVATE METHODS
    The following methods should only be called by a subclass.

  "_syndicator_init"
    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 'SYNDICATOR_REGISTER'.

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

    '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.

  "_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 "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
    event.

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

PUBLIC METHODS
  "session_id"
    Returns the component's POE session id.

  "session_alias"
    Returns the component's POE session alias.

  "yield"
    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.

  "call"
    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.

  "send_event"
    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!bar@baz.com', ['#mychan'], 'message');

  "send_event_next"
    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.

  "send_event_now"
    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.

  "send_user_event"
    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');

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

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

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

   "syndicator_started"
    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.

   "syndicator_stopped"
    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.

   "register"
    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.

   "unregister"
    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'.

   "shutdown"
    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.

   "_default"
    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 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 "_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 "_syndicator_init".

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

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

   "syndicator_delay_set"
    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 "delay".

   "syndicator_delay_removed"
    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.

SIGNALS
    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".

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

  "SYNDICATOR_SHUTDOWN"
    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 "_syndicator_destroy".

AUTHOR
    Hinrik Örn Sigurðsson, hinrik.sig@gmail.com, Chris "BinGOs" Williams
    chris@bingosnet.co.uk, Apocalypse apocal@cpan.org, and probably others.

LICENSE AND COPYRIGHT
    Copyright 2011 Hinrik Örn Sigurðsson

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