NAME¶

Object::Pluggable - A base class for creating plugin-enabled objects

SYNOPSIS¶

 # A simple POE Component that sends ping events to registered sessions
 # and plugins every second.
 {
     package SimplePoCo;
     use strict;
     use warnings;
     use base qw(Object::Pluggable);
     use POE;
     use Object::Pluggable::Constants qw(:ALL);
     sub spawn {
         my ($package, %opts) = @_;
         my $self = bless \%opts, $package;
         $self->_pluggable_init(
             prefix => 'simplepoco_',
             types  => [qw(EXAMPLE)],
             debug  => 1,
         );
         POE::Session->create(
             object_states => [
                 $self => { shutdown => '_shutdown' },
                 $self => [qw(_send_ping _start register unregister __send_event)],
             ],
         );
         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();
          $kernel->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 => 'simplepoco_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 => 'simplepoco_unregistered', $sender_id);
         }
         return;
     }
  
     sub __send_event {
         my ($kernel, $self, $event, @args) = @_[KERNEL, OBJECT, ARG0..$#_];
         return 1 if $self->_pluggable_process(EXAMPLE => $event, \@args) == PLUGIN_EAT_ALL;
         $kernel->post($_, $event, @args) for keys %{ $self->{sessions} };
     }
     sub _send_ping {
         my ($kernel, $self) = @_[KERNEL, OBJECT];
         $kernel->yield(__send_event => 'simplepoco_ping', 'Wake up sleepy');
         $kernel->delay(_send_ping => $self->{time} || 1);
         return;
     }
 }
 {
     package SimplePoCo::Plugin;
     use strict;
     use warnings;
     use Object::Pluggable::Constants qw(:ALL);
     sub new {
         my $package = shift;
         return bless { @_ }, $package;
     }
     sub plugin_register {
         my ($self, $pluggable) = splice @_, 0, 2;
         print "Plugin added\n";
         $pluggable->plugin_register($self, 'EXAMPLE', 'all');
         return 1;
     }
     sub plugin_unregister {
         print "Plugin removed\n";
         return 1;
     }
     sub EXAMPLE_ping {
         my ($self, $pluggable) = splice @_, 0, 2;
         my $text = ${ $_[0] };
         print "Plugin got '$text'\n";
         return PLUGIN_EAT_NONE;
     }
 }
 use strict;
 use warnings;
 use POE;
 my $pluggable = SimplePoCo->spawn(
     alias => 'pluggable',
     time  => 1,
 );
 POE::Session->create(
     package_states => [
         main => [qw(_start simplepoco_registered simplepoco_ping)],
     ],
 );
 $poe_kernel->run();
 sub _start {
     my $kernel = $_[KERNEL];
     $kernel->post(pluggable => 'register');
     return;
 }
 sub simplepoco_registered {
     print "Main program registered for events\n";
     my $plugin = SimplePoCo::Plugin->new();
     $pluggable->plugin_add('TestPlugin', $plugin);
     return;
 }
 sub simplepoco_ping {
     my ($heap, $text) = @_[HEAP, ARG0];
     print "Main program got '$text'\n";
     $heap->{got_ping}++;
     $pluggable->shutdown() if $heap->{got_ping} == 3;
     return;
 }

DESCRIPTION¶

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

If your object dispatches events to listeners, then Object::Pluggable may be a good fit for you.

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

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

You may also use plugin style handlers within your object 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 Object::Pluggable gives your object the following 'private' methods:

 '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. This argument is
          mandatory.
 'prefix', the prefix for your events (default: 'pluggable_');
 'reg_prefix', the prefix for the register()/unregister() plugin methods 
               (default: 'plugin_');
 'debug', a boolean, if true, will cause a warning to be printed every time a
          plugin call fails.

 sub _dispatch {
     my ($self, $event, $type, @args) = @_;
     # stuff
     my $type = ...
     return 1 if $self->_pluggable_process($type, $event, \@args)) == PLUGIN_EAT_ALL;
     # dispatch event to interested sessions.
 }

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

PUBLIC METHODS¶

Subclassing Object::Pluggable gives your object the following public methods:

 The alias for the plugin
 The actual plugin object
 Any number of extra arguments

 The alias for the plugin or the plugin object itself
 Any number of extra arguments

 The alias for the plugin

 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 plugin object
 The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
 The event name[s] to unwatch

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 Object::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 Object::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¶

Copyright "(c)" Chris Williams, Apocalypse, Hinrik Örn Sigurðsson and Jeff Pinyan

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

SEE ALSO¶

POE::Component::IRC

Object::Pluggable::Pipeline

Both POE::Component::Client::NNTP and POE::Component::Server::NNTP use this module as a base, examination of their source may yield further understanding.