NAME

POE::Component::Pluggable - A base class for creating plugin enabled POE Components.

SYNOPSIS

# A simple POE Component that sends ping events to registered sessions
# every 30 seconds. A rather convoluted example to be honest.

{
    package SimplePoCo;
 
    use strict;
    use base qw(POE::Component::Pluggable);
    use POE;
    use POE::Component::Pluggable::Constants qw(:ALL);
 
    sub spawn {
        my ($package, %opts) = @_;
        $opts{lc $_} = delete $opts{$_} for keys %opts;
        my $self = bless \%opts, $package;
        
        $self->_pluggable_init(prefix => 'simplepoco_');
        POE::Session->create(
 	     object_states => [
 	         $self => { shutdown => '_shutdown' },
 		 $self => [qw(_send_ping _start register unregister __send_event)],
 	     ],
 	     heap => $self,
        );
        
        return $self;
    }
 
    sub shutdown {
        my ($self) = @_;
        $poe_kernel->post($self->{session_id}, 'shutdown');
    }
 
    sub _pluggable_event {
        my ($self) = @_;
        $poe_kernel->post($self->{session_id}, '__send_event', @_);
    }
 
    sub _start {
        my ($kernel,$self) = @_[KERNEL,OBJECT];
        $self->{session_id} = $_[SESSION]->ID();
        
        if ($self->{alias}) {
 	     $kernel->alias_set($self->{alias});
        }
        else {
 	     $kernel->refcount_increment($self->{session_id}, __PACKAGE__);
        }
     
        $kernel->delay(_send_ping => $self->{time} || 300);
        return;
    }
 
    sub _shutdown {
         my ($kernel, $self) = @_[KERNEL, OBJECT];
         $self->_pluggable_destroy();
         $kernel->alarm_remove_all();
         $self->alias_remove($_) for $kernel->alias_list();
         $kernel->refcount_decrement($self->{session_id}, __PACKAGE__) if !$self->{alias};
         $kernel->refcount_decrement($_, __PACKAGE__) for keys %{ $self->{sessions} };
        
         return;
    }
 
    sub register {
        my ($kernel, $sender, $self) = @_[KERNEL, SENDER, OBJECT];
        my $sender_id = $sender->ID();
        $self->{sessions}->{$sender_id}++;
        
        if ($self->{sessions}->{$sender_id} == 1) { 
            $kernel->refcount_increment($sender_id, __PACKAGE__);
            $kernel->yield(__send_event => $self->{_pluggable_prefix} . 'registered', $sender_id);
        }
        
        return;
    }
 
    sub unregister {
        my ($kernel, $sender, $self) = @_[KERNEL, SENDER, OBJECT];
        my $sender_id = $sender->ID();
        my $record = delete $self->{sessions}->{$sender_id};
        
        if ($record) {
            $kernel->refcount_decrement($sender_id, __PACKAGE__);
            $kernel->yield(__send_event => $self->{_pluggable_prefix} . 'unregistered', $sender_id);
        }
        
        return;
    }
 
    sub __send_event {
        my ($kernel, $self, $event, @args) = @_[KERNEL, OBJECT, ARG0..$#_];
 
        return 1 if $self->_pluggable_process(PING => $event, \(@args)) == PLUGIN_EAT_ALL;
 
        $kernel->post($_, $event, @args) for keys %{ $self->{sessions} };
    }
 
    sub _send_ping {
        my ($kernel, $self) = @_[KERNEL, OBJECT];
        my $event = $self->{_pluggable_prefix} . 'ping';
        my @args = ('Wake up sleepy');
        $kernel->yield(__send_event => $event, @args);
        $kernel->delay(_send_ping => $self->{time} || 300);
        
        return;
    }
}       
 
    use POE;
 
    my $pluggable = SimplePoCo->spawn(
        alias => 'pluggable',
        time => 30,
    );
 
    POE::Session->create(
        package_states => [
 	     main => [qw(_start simplepoco_registered simplepoco_ping)],
 	 ],
    );
 
    $poe_kernel->run();
 
    sub _start {
        my ($kernel, $heap) = @_[KERNEL, HEAP];
        $kernel->post(pluggable => 'register');
        return;
    }
 
    sub simplepoco_registered {
        print "Yay, we registered\n";
        return;
    }
 
    sub simplepoco_ping {
        my ($sender, $text) = @_[SENDER, ARG0];
        print "Got '$text' from ", $sender->ID, "\n";
        return;
    }

DESCRIPTION

POE::Component::Pluggable is a base class for creating plugin enabled POE Components. It is a generic port of POE::Component::IRC's plugin system.

If your component dispatches events to registered POE sessions, then POE::Component::Pluggable may be a good fit for you.

Basic use would involve subclassing POE::Component::Pluggable, then overriding _pluggable_event() and inserting _pluggable_process() wherever you dispatch events from.

Users of your component can then load plugins using the plugin methods provided to handle events generated by the component.

You may also use plugin style handlers within your component as _pluggable_process() will attempt to process any events with local method calls first. The return value of these handlers has the same significance as the return value of 'normal' plugin handlers.

PRIVATE METHODS

Subclassing POE::Component::Pluggable gives your object the following 'private' methods:

`_pluggable_init`

This should be called on your object after initialisation, but before you want to start processing plugins. It accepts a number of argument/value pairs:

'prefix', the prefix for your events (default: 'pluggable_');
'reg_prefix', the prefix for the register()/unregister() plugin methods 
              (default: 'plugin_');
'types', an arrayref of the types of events that your poco will support,
         OR a hashref with the event types as keys and their abbrevations
         (used as plugin event method prefixes) as values;

Notes: 'prefix' should probably end with a '_'. The types specify the prefixes for plugin handlers. You can specify as many different types as you require.

`_pluggable_destroy`

This should be called from any shutdown handler that your poco has. The method unloads any loaded plugins.

`_pluggable_process`

This should be called before events are dispatched to interested sessions. This gives pluggable a chance to discard events if requested to by a plugin.

The first argument is a type, as specified to _pluggable_init().

sub _dispatch {
    # stuff
   
    return 1 if $self->_pluggable_process($type, $event, \(@args)) == PLUGIN_EAT_ALL;

    # dispatch event to interested sessions.
}

This example demonstrates event arguments being passed as scalar refs to the plugin system. This enables plugins to mangle the arguments if necessary.

`_pluggable_event`

This method should be overridden in your class so that pipeline can dispatch events through your event dispatcher. Pipeline sends a prefixed 'plugin_add' and 'plugin_del' event whenever plugins are added or removed, respectively.

sub _pluggable_event {
    my $self = shift;
    $poe_kernel->post($self->{session_id}, '__send_event', @_);
}

There is an example of this in the SYNOPSIS.

PUBLIC METHODS

Subclassing POE::Component::Pluggable gives your object the following public methods:

`pipeline`

Returns the POE::Component::Pluggable::Pipeline object.

`plugin_add`

Accepts two arguments:

The alias for the plugin
The actual plugin object

The alias is there for the user to refer to it, as it is possible to have multiple plugins of the same kind active in one POE::Component::Pluggable object.

This method goes through the pipeline's push() method, which will call $plugin-plugin_register($pluggable)>.

Returns the number of plugins now in the pipeline if plugin was initialized, undef/an empty list if not.

`plugin_del`

Accepts one argument:

The alias for the plugin or the plugin object itself

This method goes through the pipeline's remove() method, which will call $plugin-plugin_unregister($pluggable)>.

Returns the plugin object if the plugin was removed, undef/an empty list if not.

`plugin_get`

Accepts one argument:

The alias for the plugin

This method goes through the pipeline's get() method.

Returns the plugin object if it was found, undef/an empty list if not.

`plugin_list`

Takes no arguments.

Returns a hashref of plugin objects, keyed on alias, or an empty list if there are no plugins loaded.

`plugin_order`

Takes no arguments.

Returns an arrayref of plugin objects, in the order which they are encountered in the pipeline.

`plugin_register`

Accepts the following arguments:

The plugin object
The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
The event name[s] to watch

The event names can be as many as possible, or an arrayref. They correspond to the prefixed events and naturally, arbitrary events too.

You do not need to supply events with the prefix in front of them, just the names.

It is possible to register for all events by specifying 'all' as an event.

Returns 1 if everything checked out fine, undef/an empty list if something is seriously wrong.

`plugin_unregister`

Accepts the following arguments:

The plugin object
The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
The event name[s] to unwatch

The event names can be as many as possible, or an arrayref. They correspond to the prefixed events and naturally, arbitrary events too.

You do not need to supply events with the prefix in front of them, just the names.

It is possible to register for all events by specifying 'all' as an event.

Returns 1 if all the event name[s] was unregistered, undef if some was not found.

PLUGINS

The basic anatomy of a pluggable plugin is:

# Import the constants, of course you could provide your own 
# constants as long as they map correctly.
use POE::Component::Pluggable::Constants qw( :ALL );

# Our constructor
sub new {
    ...
}

# Required entry point for pluggable plugins
sub plugin_register {
    my($self, $pluggable) = @_;

    # Register events we are interested in
    $pluggable->plugin_register($self, 'SERVER', qw(something whatever));

    # Return success
    return 1;
}

# Required exit point for pluggable
sub plugin_unregister {
    my($self, $pluggable) = @_;

    # Pluggable will automatically unregister events for the plugin

    # Do some cleanup...

    # Return success
    return 1;
}

sub _default {
    my($self, $pluggable, $event) = splice @_, 0, 3;

    print "Default called for $event\n";

    # Return an exit code
    return PLUGIN_EAT_NONE;
}

As shown in the example above, a plugin's _default subroutine (if present) is called if the plugin receives an event for which it has no handler.

The special exit code CONSTANTS are documented in POE::Component::Pluggable::Constants. You could provide your own as long as the values match up, though.

TODO

Better documentation >:]

AUTHOR

Chris 'BinGOs' Williams <chris@bingosnet.co.uk>

LICENSE

This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.

KUDOS

APOCAL for writing the original POE::Component::IRC plugin system.

japhy for writing POE::Component::IRC::Pipeline which improved on it.

All the happy chappies who have contributed to POE::Component::IRC over the years (yes, it has been years) refining and tweaking the plugin system.

The initial idea was heavily borrowed from X-Chat, BIG thanks go out to the genius that came up with the EAT_* system :)

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

PRIVATE METHODS

_pluggable_init

_pluggable_destroy

_pluggable_process

_pluggable_event

PUBLIC METHODS

pipeline

plugin_add

plugin_del

plugin_get

plugin_list

plugin_order

plugin_register

plugin_unregister