Object::Pluggable(3pm)

1Object::Pluggable(3)  User Contributed Perl Documentation Object::Pluggable(3)
2
3
4

NAME

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

SYNOPSIS

9        # A simple POE Component that sends ping events to registered sessions
10        # and plugins every second.
11
12        {
13            package SimplePoCo;
14
15            use strict;
16            use warnings;
17            use base qw(Object::Pluggable);
18            use POE;
19            use Object::Pluggable::Constants qw(:ALL);
20
21            sub spawn {
22                my ($package, %opts) = @_;
23                my $self = bless \%opts, $package;
24
25                $self->_pluggable_init(
26                    prefix => 'simplepoco_',
27                    types  => [qw(EXAMPLE)],
28                    debug  => 1,
29                );
30
31                POE::Session->create(
32                    object_states => [
33                        $self => { shutdown => '_shutdown' },
34                        $self => [qw(_send_ping _start register unregister __send_event)],
35                    ],
36                );
37
38                return $self;
39            }
40
41            sub shutdown {
42                my ($self) = @_;
43                $poe_kernel->post($self->{session_id}, 'shutdown');
44            }
45
46            sub _pluggable_event {
47                my ($self) = @_;
48                $poe_kernel->post($self->{session_id}, '__send_event', @_);
49            }
50
51            sub _start {
52                my ($kernel, $self) = @_[KERNEL, OBJECT];
53                $self->{session_id} = $_[SESSION]->ID();
54
55                if ($self->{alias}) {
56                    $kernel->alias_set($self->{alias});
57                }
58                else {
59                    $kernel->refcount_increment($self->{session_id}, __PACKAGE__);
60                }
61
62                $kernel->delay(_send_ping => $self->{time} || 300);
63                return;
64            }
65
66            sub _shutdown {
67                 my ($kernel, $self) = @_[KERNEL, OBJECT];
68
69                 $self->_pluggable_destroy();
70                 $kernel->alarm_remove_all();
71                 $kernel->alias_remove($_) for $kernel->alias_list();
72                 $kernel->refcount_decrement($self->{session_id}, __PACKAGE__) if !$self->{alias};
73                 $kernel->refcount_decrement($_, __PACKAGE__) for keys %{ $self->{sessions} };
74
75                 return;
76            }
77
78            sub register {
79                my ($kernel, $sender, $self) = @_[KERNEL, SENDER, OBJECT];
80                my $sender_id = $sender->ID();
81                $self->{sessions}->{$sender_id}++;
82
83                if ($self->{sessions}->{$sender_id} == 1) {
84                    $kernel->refcount_increment($sender_id, __PACKAGE__);
85                    $kernel->yield(__send_event => 'simplepoco_registered', $sender_id);
86                }
87
88                return;
89            }
90
91            sub unregister {
92                my ($kernel, $sender, $self) = @_[KERNEL, SENDER, OBJECT];
93                my $sender_id = $sender->ID();
94                my $record = delete $self->{sessions}->{$sender_id};
95
96                if ($record) {
97                    $kernel->refcount_decrement($sender_id, __PACKAGE__);
98                    $kernel->yield(__send_event => 'simplepoco_unregistered', $sender_id);
99                }
100
101                return;
102            }
103
104            sub __send_event {
105                my ($kernel, $self, $event, @args) = @_[KERNEL, OBJECT, ARG0..$#_];
106
107                return 1 if $self->_pluggable_process(EXAMPLE => $event, \@args) == PLUGIN_EAT_ALL;
108                $kernel->post($_, $event, @args) for keys %{ $self->{sessions} };
109            }
110
111            sub _send_ping {
112                my ($kernel, $self) = @_[KERNEL, OBJECT];
113
114                $kernel->yield(__send_event => 'simplepoco_ping', 'Wake up sleepy');
115                $kernel->delay(_send_ping => $self->{time} || 1);
116                return;
117            }
118        }
119
120        {
121            package SimplePoCo::Plugin;
122            use strict;
123            use warnings;
124            use Object::Pluggable::Constants qw(:ALL);
125
126            sub new {
127                my $package = shift;
128                return bless { @_ }, $package;
129            }
130
131            sub plugin_register {
132                my ($self, $pluggable) = splice @_, 0, 2;
133                print "Plugin added\n";
134                $pluggable->plugin_register($self, 'EXAMPLE', 'all');
135                return 1;
136            }
137
138            sub plugin_unregister {
139                print "Plugin removed\n";
140                return 1;
141            }
142
143            sub EXAMPLE_ping {
144                my ($self, $pluggable) = splice @_, 0, 2;
145                my $text = ${ $_[0] };
146                print "Plugin got '$text'\n";
147                return PLUGIN_EAT_NONE;
148            }
149        }
150
151        use strict;
152        use warnings;
153        use POE;
154
155        my $pluggable = SimplePoCo->spawn(
156            alias => 'pluggable',
157            time  => 1,
158        );
159
160        POE::Session->create(
161            package_states => [
162                main => [qw(_start simplepoco_registered simplepoco_ping)],
163            ],
164        );
165
166        $poe_kernel->run();
167
168        sub _start {
169            my $kernel = $_[KERNEL];
170            $kernel->post(pluggable => 'register');
171            return;
172        }
173
174        sub simplepoco_registered {
175            print "Main program registered for events\n";
176            my $plugin = SimplePoCo::Plugin->new();
177            $pluggable->plugin_add('TestPlugin', $plugin);
178            return;
179        }
180
181        sub simplepoco_ping {
182            my ($heap, $text) = @_[HEAP, ARG0];
183            print "Main program got '$text'\n";
184            $heap->{got_ping}++;
185            $pluggable->shutdown() if $heap->{got_ping} == 3;
186            return;
187        }
188

DESCRIPTION

190       Object::Pluggable is a base class for creating plugin enabled objects.
191       It is a generic port of POE::Component::IRC's plugin system.
192
193       If your object dispatches events to listeners, then Object::Pluggable
194       may be a good fit for you.
195
196       Basic use would involve subclassing Object::Pluggable, then overriding
197       "_pluggable_event()" and inserting "_pluggable_process()" wherever you
198       dispatch events from.
199
200       Users of your object can then load plugins using the plugin methods
201       provided to handle events generated by the object.
202
203       You may also use plugin style handlers within your object as
204       "_pluggable_process()" will attempt to process any events with local
205       method calls first. The return value of these handlers has the same
206       significance as the return value of 'normal' plugin handlers.
207

PRIVATE METHODS

209       Subclassing Object::Pluggable gives your object the following 'private'
210       methods:
211
212   "_pluggable_init"
213       This should be called on your object after initialisation, but before
214       you want to start processing plugins. It accepts a number of
215       argument/value pairs:
216
217        'types', an arrayref of the types of events that your poco will support,
218                 OR a hashref with the event types as keys and their abbrevations
219                 (used as plugin event method prefixes) as values. This argument is
220                 mandatory.
221
222        'prefix', the prefix for your events (default: 'pluggable_');
223        'reg_prefix', the prefix for the register()/unregister() plugin methods
224                      (default: 'plugin_');
225        'debug', a boolean, if true, will cause a warning to be printed every time a
226                 plugin call fails.
227
228       Notes: 'prefix' should probably end with a '_'. The types specify the
229       prefixes for plugin handlers. You can specify as many different types
230       as you require.
231
232   "_pluggable_destroy"
233       This should be called from any shutdown handler that your poco has. The
234       method unloads any loaded plugins.
235
236   "_pluggable_process"
237       This should be called before events are dispatched to interested
238       sessions.  This gives pluggable a chance to discard events if requested
239       to by a plugin.
240
241       The first argument is a type, as specified to "_pluggable_init()".
242
243        sub _dispatch {
244            my ($self, $event, $type, @args) = @_;
245
246            # stuff
247
248            my $type = ...
249
250            return 1 if $self->_pluggable_process($type, $event, \@args)) == PLUGIN_EAT_ALL;
251
252            # dispatch event to interested sessions.
253        }
254
255       A reference to the argument array is passed. This allows the plugin
256       system to mangle the arguments or even add new ones.
257
258   "_pluggable_event"
259       This method should be overridden in your class so that pipeline can
260       dispatch events through your event dispatcher. Pipeline sends a
261       prefixed 'plugin_add' and 'plugin_del' event whenever plugins are added
262       or removed, respectively.  A prefixed 'plugin_error' event will be sent
263       if a plugin a) raises an exception, b) fails to return a true value
264       from its register/unregister methods, or c) fails to return a valid EAT
265       constant from a handler.
266
267        sub _pluggable_event {
268            my $self = shift;
269            $poe_kernel->post($self->{session_id}, '__send_event', @_);
270        }
271
272       There is an example of this in the SYNOPSIS.
273

PUBLIC METHODS

275       Subclassing Object::Pluggable gives your object the following public
276       methods:
277
278   "pipeline"
279       Returns the Object::Pluggable::Pipeline object.
280
281   "plugin_add"
282       Accepts two arguments:
283
284        The alias for the plugin
285        The actual plugin object
286        Any number of extra arguments
287
288       The alias is there for the user to refer to it, as it is possible to
289       have multiple plugins of the same kind active in one Object::Pluggable
290       object.
291
292       This method goes through the pipeline's "push()" method, which will
293       call "$plugin->plugin_register($pluggable, @args)".
294
295       Returns the number of plugins now in the pipeline if plugin was
296       initialized, "undef"/an empty list if not.
297
298   "plugin_del"
299       Accepts the following arguments:
300
301        The alias for the plugin or the plugin object itself
302        Any number of extra arguments
303
304       This method goes through the pipeline's "remove()" method, which will
305       call "$plugin->plugin_unregister($pluggable, @args)".
306
307       Returns the plugin object if the plugin was removed, "undef"/an empty
308       list if not.
309
310   "plugin_get"
311       Accepts the following arguments:
312
313        The alias for the plugin
314
315       This method goes through the pipeline's "get()" method.
316
317       Returns the plugin object if it was found, "undef"/an empty list if
318       not.
319
320   "plugin_list"
321       Takes no arguments.
322
323       Returns a hashref of plugin objects, keyed on alias, or an empty list
324       if there are no plugins loaded.
325
326   "plugin_order"
327       Takes no arguments.
328
329       Returns an arrayref of plugin objects, in the order which they are
330       encountered in the pipeline.
331
332   "plugin_register"
333       Accepts the following arguments:
334
335        The plugin object
336        The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
337        The event name[s] to watch
338
339       The event names can be as many as possible, or an arrayref. They
340       correspond to the prefixed events and naturally, arbitrary events too.
341
342       You do not need to supply events with the prefix in front of them, just
343       the names.
344
345       It is possible to register for all events by specifying 'all' as an
346       event.
347
348       Returns 1 if everything checked out fine, "undef"/an empty list if
349       something is seriously wrong.
350
351   "plugin_unregister"
352       Accepts the following arguments:
353
354        The plugin object
355        The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
356        The event name[s] to unwatch
357
358       The event names can be as many as possible, or an arrayref. They
359       correspond to the prefixed events and naturally, arbitrary events too.
360
361       You do not need to supply events with the prefix in front of them, just
362       the names.
363
364       It is possible to register for all events by specifying 'all' as an
365       event.
366
367       Returns 1 if all the event name[s] was unregistered, undef if some was
368       not found.
369

PLUGINS

371       The basic anatomy of a pluggable plugin is:
372
373        # Import the constants, of course you could provide your own
374        # constants as long as they map correctly.
375        use Object::Pluggable::Constants qw( :ALL );
376
377        # Our constructor
378        sub new {
379            ...
380        }
381
382        # Required entry point for pluggable plugins
383        sub plugin_register {
384            my($self, $pluggable) = @_;
385
386            # Register events we are interested in
387            $pluggable->plugin_register($self, 'SERVER', qw(something whatever));
388
389            # Return success
390            return 1;
391        }
392
393        # Required exit point for pluggable
394        sub plugin_unregister {
395            my($self, $pluggable) = @_;
396
397            # Pluggable will automatically unregister events for the plugin
398
399            # Do some cleanup...
400
401            # Return success
402            return 1;
403        }
404
405        sub _default {
406            my($self, $pluggable, $event) = splice @_, 0, 3;
407
408            print "Default called for $event\n";
409
410            # Return an exit code
411            return PLUGIN_EAT_NONE;
412        }
413
414       As shown in the example above, a plugin's "_default" subroutine (if
415       present) is called if the plugin receives an event for which it has no
416       handler.
417
418       The special exit code CONSTANTS are documented in
419       Object::Pluggable::Constants. You could provide your own as long as the
420       values match up, though.
421

TODO

423       Better documentation >:]
424

AUTHOR

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

LICENSE

429       Copyright "(c)" Chris Williams, Apocalypse, Hinrik Örn Sigurðsson and
430       Jeff Pinyan
431
432       This module may be used, modified, and distributed under the same terms
433       as Perl itself. Please see the license that came with your Perl
434       distribution for details.
435

KUDOS

437       APOCAL for writing the original POE::Component::IRC plugin system.
438
439       japhy for writing POE::Component::IRC::Pipeline which improved on it.
440
441       All the happy chappies who have contributed to POE::Component::IRC over
442       the years (yes, it has been years) refining and tweaking the plugin
443       system.
444
445       The initial idea was heavily borrowed from X-Chat, BIG thanks go out to
446       the genius that came up with the EAT_* system :)
447