NAME
   MooX::Role::Pluggable - Add a plugin pipeline to your cows

SYNOPSIS
     # A simple pluggable dispatcher:
     package MyDispatcher;
     use Moo;
     use MooX::Role::Pluggable::Constants;
     with 'MooX::Role::Pluggable';

     sub BUILD {
       my ($self) = @_;

       # (optionally) Configure our plugin pipeline
       $self->_pluggable_init(
         reg_prefix => 'Plug_',
         ev_prefix  => 'Event_',
         types      => {
           NOTIFY  => 'N',
           PROCESS => 'P',
         },
       );
     }

     around '_pluggable_event' => sub {
       # This override redirects internal events (errors, etc) to ->process()
       my ($orig, $self) = splice @_, 0, 2;
       $self->process( @_ )
     };

     sub process {
       my ($self, $event, @args) = @_;

       # Dispatch to 'P_' prefixed "PROCESS" type handlers.
       #
       # _pluggable_process will automatically strip a leading 'ev_prefix'
       # (see the call to _pluggable_init above); that lets us easily
       # dispatch errors to our P_plugin_error handler below without worrying
       # about our ev_prefix ourselves:
       my $retval = $self->_pluggable_process( PROCESS =>
         $event,
         \@args
       );

       unless ($retval == EAT_ALL) {
         # The pipeline allowed the event to continue.
         # A dispatcher might re-dispatch elsewhere, etc.
       }
     }

     sub shutdown {
       my ($self) = @_;
       # Unregister all of our plugins.
       $self->_pluggable_destroy;
     }

     sub P_plugin_error {
       # Since we re-dispatched errors in our _pluggable_event handler,
       # we could handle exceptions here and then eat them, perhaps:
       my ($self, undef) = splice @_, 0, 2;

       # Arguments are references:
       my $plug_err  = ${ $_[0] };
       my $plug_obj  = ${ $_[1] };
       my $error_src = ${ $_[2] };

       # ...

       EAT_ALL
     }


     # A Plugin object.
     package MyPlugin;

     use MooX::Role::Pluggable::Constants;

     sub new { bless {}, shift }

     sub Plug_register {
       my ($self, $core) = @_;

       # Subscribe to events:
       $core->subscribe( $self, 'PROCESS',
         'my_event',
         'another_event'
       );

       # Log that we're here, do some initialization, etc ...

       return EAT_NONE
     }

     sub Plug_unregister {
       my ($self, $core) = @_;
       # Called when this plugin is unregistered
       # ... do some cleanup, etc ...
       return EAT_NONE
     }

     sub P_my_event {
       # Handle a dispatched "PROCESS"-type event:
       my ($self, $core) = splice @_, 0, 2;

       # Arguments are references and can be modified:
       my $arg = ${ $_[0] };

       # ... do some work ...

       # Return an EAT constant to control event lifetime
       # EAT_NONE allows this event to continue through the pipeline
       return EAT_NONE
     }

     # An external package that interacts with our dispatcher;
     # this is just a quick and dirty example to show external
     # plugin manipulation:

     package MyController;
     use Moo;

     has 'dispatcher' => (
       is      => 'rw',
       default => sub {  MyDispatcher->new()  },
     );

     sub BUILD {
       my ($self) = @_;
       $self->dispatcher->plugin_add( 'MyPlugin',
         MyPlugin->new()
       );
     }

     sub do_stuff {
       my $self = shift;
       $self->dispatcher->process( 'my_event', @_ )
     }

DESCRIPTION
   A Moo::Role for turning instances of your class into pluggable objects.
   Consumers of this role gain a plugin pipeline and methods to manipulate
   it, as well as a flexible dispatch system (see "_pluggable_process").

   The logic and behavior is based almost entirely on Object::Pluggable
   (see "AUTHOR"). Some methods are the same; implementation & interface
   differ and you will still want to read thoroughly if coming from
   Object::Pluggable. Dispatch is significantly faster -- see
   "Performance".

   It may be worth noting that this is nothing at all like the Moose
   counterpart MooseX::Role::Pluggable. If the names confuse ... well, I
   lacked for better ideas. ;-)

   If you're using POE, also see MooX::Role::POE::Emitter, which consumes
   this role.

 Initialization
  _pluggable_init
     $self->_pluggable_init(
       # Prefix for registration events.
       # Defaults to 'plugin_' ('plugin_register' / 'plugin_unregister')
       reg_prefix   => 'plugin_',

       # Prefix for dispatched internal events
       #  (add, del, error, register, unregister ...)
       # Defaults to 'plugin_ev_'
       event_prefix => 'plugin_ev_',

       # Map type names to prefixes.
       # Event types are arbitrary.
       # Prefix is prepended when dispathing events of a particular type.
       # Defaults to: { NOTIFY => 'N', PROCESS => 'P' }
       types => {
         NOTIFY  => 'N',
         PROCESS => 'P',
       },
     );

   A consumer can call _pluggable_init to set up pipeline-related options
   appropriately; this should be done prior to loading plugins or
   dispatching to "_pluggable_process". If it is not called, the defaults
   (as shown above) are used.

   types => can be either an ARRAY of event types (which will be used as
   prefixes):

     types => [ qw/ IncomingEvent OutgoingEvent / ],

   ... or a HASH mapping an event type to a prefix:

     types => {
       Incoming => 'I',
       Outgoing => 'O',
     },

   A '_' is automatically appended to event type prefixes when events are
   dispatched via "_pluggable_process"; thus, an event destined for our
   'Incoming' type shown above will be dispatched to appropriate "I_"
   handlers:

     # Dispatched to 'I_foo' method in plugins registered for Incoming 'foo':
     $self->_pluggable_process( Incoming => 'foo', 'bar', 'baz' );

   "reg_prefix"/"event_prefix" are not automatically munged in any way.

   An empty string "reg_prefix"/"event_prefix" is valid.

  _pluggable_destroy
     $self->_pluggable_destroy;

   Shuts down the plugin pipeline, unregistering/unloading all known
   plugins.

  _pluggable_event
     # In our consumer
     sub _pluggable_event {
       my ($self, $event, @args) = @_;
       # Dispatch out, perhaps.
     }

   "_pluggable_event" is called for internal notifications, such as plugin
   load/unload and error reporting (see "Internal events").

   It should be overriden in your consuming class to do something useful
   with the dispatched event (and any other arguments passed in).

   The $event passed will be prefixed with the configured event_prefix.

   Also see "Internal events".

 Registration
   A plugin is any blessed object that is registered with your Pluggable
   object via "plugin_add"; during registration, plugins usually subscribe
   to some events via "subscribe".

   See "plugin_add" regarding loading plugins.

  subscribe
   Subscribe a plugin to some pluggable events.

     $self->subscribe( $plugin_obj, $type, @events );

   Registers a plugin object to receive @events of type $type.

   This is frequently called from within the plugin's registration handler
   (see "plugin_register"):

     # In a plugin:
     sub plugin_register {
       my ($self, $core) = @_;

       $core->subscribe( $self, PROCESS =>
         qw/
           my_event
           another_event
         /
       );

       $core->subscribe( $self, NOTIFY =>
         'all'
       );

       EAT_NONE
     }

   Subscribe to all to receive all events. (It may be worth noting that
   subscribing a lot of plugins to 'all' events will cause a performance
   hit in "_pluggable_process" dispatch versus subscribing to specific
   events.)

  unsubscribe
   Unsubscribe a plugin from subscribed events.

   The unregister counterpart to "subscribe"; stops delivering specified
   events to a plugin.

   The plugin is still loaded and registered until "plugin_del" is called.

   Carries the same arguments as "subscribe".

  plugin_register
   Defined in your plugin(s) and called at load time.

   (Note that 'plugin_' is just a default register method prefix; it can be
   changed prior to loading plugins. See "_pluggable_init" for details.)

   The "plugin_register" method is called on a loaded plugin when it is
   added to the pipeline; it is passed the plugin object ($self), the
   Pluggable object, and any arguments given to "plugin_add" (or similar
   registration methods).

   Normally one might call a "subscribe" from here to start receiving
   events after load-time:

     sub plugin_register {
       my ($self, $core, @args) = @_;
       $core->subscribe( $self, 'NOTIFY', @events );
       EAT_NONE
     }

  plugin_unregister
   Defined in your plugin(s) and called at load time.

   (Note that 'plugin_' is just a default register method prefix; it can be
   changed prior to loading plugins. See "_pluggable_init" for details.)

   The unregister counterpart to "plugin_register", called when the object
   is removed from the pipeline (via "plugin_del" or "_pluggable_destroy").

     sub plugin_unregister {
       my ($self, $core) = @_;
       EAT_NONE
     }

   Carries the same arguments.

 Dispatch
  _pluggable_process
     my $eat = $self->_pluggable_process( $type, $event, \@args );
     return 1 if $eat == EAT_ALL;

   The "_pluggable_process" method handles dispatching.

   If $event is prefixed with our event prefix (see "_pluggable_init"), the
   prefix is stripped prior to dispatch (to be replaced with a type prefix
   matching the specified $type).

   Arguments should be passed in as an ARRAY. During dispatch, references
   to the arguments are passed to subs following automatically-prepended
   objects belonging to the plugin and the pluggable caller, respectively:

     my @args = qw/baz bar/;
     $self->_pluggable_process( 'NOTIFY', 'foo', \@args );

     # In a plugin:
     sub N_foo {
       my ($self, $core) = splice @_, 0, 2;
       # Dereferenced expected scalars:
       my $baz = ${ $_[0] };
       my $bar = ${ $_[1] };
     }

   This allows for argument modification as an event is passed along the
   pipeline.

   Dispatch process for $event 'foo' of $type 'NOTIFY':

     - Prepend the known prefix for the specified type, and '_'
       'foo' -> 'N_foo'
     - Attempt to dispatch to $self->N_foo()
     - If no such method, attempt to dispatch to $self->_default()
       (The method we were attempting to call is prepended to arguments)
     - If the event was not eaten (see below), dispatch to plugins

   "Eaten" means a handler returned a EAT_* constant from
   MooX::Role::Pluggable::Constants indicating that the event's lifetime
   should terminate.

   Specifically:

   If our consuming class provides a method or '_default' that returns:

       EAT_ALL:    skip plugin pipeline, return EAT_ALL
       EAT_CLIENT: continue to plugin pipeline
                   return EAT_ALL if plugin returns EAT_PLUGIN later
       EAT_PLUGIN: skip plugin pipeline entirely
                   return EAT_NONE unless EAT_CLIENT was seen previously
       EAT_NONE:   continue to plugin pipeline

   If one of our plugins in the pipeline returns:

       EAT_ALL:    skip further plugins, return EAT_ALL
       EAT_CLIENT: continue to next plugin, set pending EAT_ALL
                   (EAT_ALL will be returned when plugin processing finishes)
       EAT_PLUGIN: return EAT_ALL if previous sub returned EAT_CLIENT
                   else return EAT_NONE
       EAT_NONE:   continue to next plugin

   This functionality (derived from Object::Pluggable) provides
   fine-grained control over event lifetime.

   Higher layers can check for an "EAT_ALL" return value from
   _pluggable_process to determine whether to continue operating on a
   particular event (re-dispatch elsewhere, for example). Plugins can use
   'EAT_CLIENT' to indicate that an event should be eaten after plugin
   processing is complete, 'EAT_PLUGIN' to stop plugin processing, and
   'EAT_ALL' to indicate that the event should not be dispatched further.

 Plugin Management Methods
   Plugin pipeline manipulation methods will set $@, "carp()", and return
   empty list on error (unless otherwise noted). See "plugin_error"
   regarding errors raised during plugin registration and dispatch.

  plugin_add
     $self->plugin_add( $alias, $plugin_obj, @args );

   Add a plugin object to the pipeline. Returns the same values as
   "plugin_pipe_push".

  plugin_del
     $self->plugin_del( $alias_or_plugin_obj, @args );

   Remove a plugin from the pipeline.

   Takes either a plugin alias or object. Returns the removed plugin
   object.

  plugin_get
     my $plug_obj = $self->plugin_get( $alias );
           my ($plug_obj, $plug_alias) = $self->plugin_get( $alias_or_plugin_obj );

   In scalar context, returns the plugin object belonging to the specified
   alias.

   In list context, returns the object and alias, respectively.

  plugin_alias_list
     my @loaded = $self->plugin_alias_list;

   Returns a list of loaded plugin aliases.

  plugin_replace
     $self->plugin_replace(
       old    => $alias_or_plugin_obj,
       alias  => $new_alias,
       plugin => $new_plugin_obj,
       # Optional:
       register_args   => [ ],
       unregister_args => [ ],
     );

   Replace an existing plugin object with a new one.

   Returns the old (removed) plugin object.

 Pipeline methods
  plugin_pipe_push
     $self->plugin_pipe_push( $alias, $plugin_obj, @args );

   Add a plugin to the end of the pipeline. (Typically one would use
   "plugin_add" rather than calling this method directly.)

  plugin_pipe_pop
     my $plug = $self->plugin_pipe_pop( @unregister_args );

   Pop the last plugin off the pipeline, passing any specified arguments to
   "plugin_unregister".

   In scalar context, returns the plugin object that was removed.

   In list context, returns the plugin object and alias, respectively.

  plugin_pipe_unshift
     $self->plugin_pipe_unshift( $alias, $plugin_obj, @args );

   Add a plugin to the beginning of the pipeline.

   Returns the total number of loaded plugins (or an empty list on
   failure).

  plugin_pipe_shift
     $self->plugin_pipe_shift( @unregister_args );

   Shift the first plugin off the pipeline, passing any specified args to
   "plugin_unregister".

   In scalar context, returns the plugin object that was removed.

   In list context, returns the plugin object and alias, respectively.

  plugin_pipe_get_index
     my $idx = $self->plugin_pipe_get_index( $alias_or_plugin_obj );
     if ($idx < 0) {
       # Plugin doesn't exist
     }

   Returns the position of the specified plugin in the pipeline.

   Returns -1 if the plugin does not exist.

  plugin_pipe_insert_after
     $self->plugin_pipe_insert_after(
       after  => $alias_or_plugin_obj,
       alias  => $new_alias,
       plugin => $new_plugin_obj,
       # Optional:
       register_args => [ ],
     );

   Add a plugin to the pipeline after the specified previously-existing
   alias or plugin object. Returns boolean true on success.

  plugin_pipe_insert_before
     $self->plugin_pipe_insert_before(
       before => $alias_or_plugin_obj,
       alias  => $new_alias,
       plugin => $new_plugin_obj,
       # Optional:
       register_args => [ ],
     );

   Similar to "plugin_pipe_insert_after", but insert before the specified
   previously-existing plugin, not after.

  plugin_pipe_bump_up
     $self->plugin_pipe_bump_up( $alias_or_plugin_obj, $count );

   Move the specified plugin 'up' $count positions in the pipeline.

   Returns -1 if the plugin cannot be bumped up any farther.

  plugin_pipe_bump_down
     $self->plugin_pipe_bump_down( $alias_or_plugin_obj, $count );

   Move the specified plugin 'down' $count positions in the pipeline.

   Returns -1 if the plugin cannot be bumped down any farther.

 Internal events
   These events are dispatched to "_pluggable_event" prefixed with our
   pluggable event prefix; see "_pluggable_init".

  plugin_error
   Issued via "_pluggable_event" when an error occurs.

   The arguments are, respectively: the error string, the offending object,
   and a string describing the offending object ('self' or 'plugin' with
   name appended).

  plugin_added
   Issued via "_pluggable_event" when a new plugin is registered.

   Arguments are the new plugin alias and object, respectively.

  plugin_removed
   Issued via "_pluggable_event" when a plugin is unregistered.

   Arguments are the old plugin alias and object, respectively.

 Performance
   My motivation for writing this role was two-fold; I wanted
   Object::Pluggable behavior but without screwing up my class inheritance,
   and I needed a little bit more juice out of the pipeline dispatch
   process for a fast-paced daemon.

   Dispatcher performance has been profiled and micro-optimized, but I'm
   most certainly open to further ideas ;-)

   Some Benchmark runs. 30000 "_pluggable_process" calls with 20 loaded
   plugins dispatching one argument to one handler that does nothing except
   return EAT_NONE:

                         Rate    object-pluggable moox-role-pluggable
     object-pluggable    6173/s                  --                -38%
     moox-role-pluggable 9967/s                 61%

                          Rate    object-pluggable moox-role-pluggable
     object-pluggable     6224/s                  --                -38%
     moox-role-pluggable 10000/s                 61%                  --

                         Rate    object-pluggable moox-role-pluggable
     object-pluggable    6383/s                  --                -35%
     moox-role-pluggable 9868/s                 55%

   (Benchmark script is available in the "bench/" directory of the upstream
   repository; see <https://github.com/avenj/moox-role-pluggable>)

AUTHOR
   Jon Portnoy <[email protected]>

   Written from the ground up, but conceptually based entirely on
   Object::Pluggable by BINGOS, HINRIK, APOCAL, japhy et al.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.