Pluggable.pm

filter: Statementstmt 74.1% 246 / 332 Branchbran 53.6% 88 / 164 Conditioncond 53.1% 17 / 32 MC/DCmcdc 12.5% 2 / 16 Subroutinesub 86.0% 37 / 43 Podpod 100% 16 / 16 totaltotal 67.3% 406 / 603 CC 113 SCAR 29.2
CC
113
Cov
66%
unsubscribe
132.0
_pluggable_process
22.3
plugin_pipe_insert_after
15.9
CRAP 18.5
↑ Summary Pluggable/Constants.pm »
1 package MooX::Role::Pluggable;
2 2 $MooX::Role::Pluggable::VERSION = '1.002002';
3 2 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 2 ▶use Scalar::Util 'blessed';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 2 ▶use Try::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 2 ▶use Types::Standard -all;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 2 ▶use MooX::Role::Pluggable::Constants;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13  
14 2 ▶use Moo::Role;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16  
17 has __pluggable_opts => (
18 lazy => 1,
19 is => 'ro',
20 isa => Dict[
21 reg_prefix => Str,
22 ev_prefix => Str,
23 types => HashRef,
24 ],
25 2 ▶ builder => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
26 +{
27 2 reg_prefix => 'plugin_',
28 ev_prefix => 'plugin_ev_',
29 types => +{ PROCESS => 'P', NOTIFY => 'N' },
30 },
31 },
32 2 );
33  
34 has __pluggable_loaded => (
35 lazy => 1,
36 is => 'ro',
37 isa => Dict[
38 ALIAS => HashRef,
39 OBJ => HashRef,
40 HANDLE => HashRef,
41 ],
42 2 ▶ builder => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
43 +{
44 2 ALIAS => +{}, # Objs keyed by aliases
45 OBJ => +{}, # Aliases keyed by obj
46 HANDLE => +{}, # Type/event map hashes keyed by obj
47 },
48 },
49 2 );
50  
51 has __pluggable_pipeline => (
52 lazy => 1,
53 is => 'ro',
54 isa => ArrayRef,
55 1 ▶ builder => sub { [] },
Subroutine _build___pluggable_pipeline: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
56 2 );
57  
58  
59 2 ▶sub _pluggable_destroy {
Subroutine _pluggable_destroy: called CC=2 SCAR=6.9
60 2 my ($self) = @_;
61 2 $self->plugin_del($_) for $self->plugin_alias_list;
62 }
63  
64 0 ▶sub _pluggable_event {
Subroutine _pluggable_event: not called CC=1 SCAR=0.0
65 # This should be overriden to handle Pluggable events
66 # ( plugin_{added, removed, error} )
67 }
68  
69 2 ▶sub _pluggable_init {
Subroutine _pluggable_init: called CC=9 SCAR=23.8
70 2 my ($self, %params) = @_;
71 2 $params{lc $_} = delete $params{$_} for keys %params;
72  
73 my $reg_prefix = defined $params{register_prefix} ?
74 2 ▶ $params{register_prefix} : $params{reg_prefix};
Branch: 1 branch
BranchTrueFalseTotal
defined $params{'register_prefix'} ? : 0 2 2
75 2 ▶ $self->__pluggable_opts->{reg_prefix} = $reg_prefix
Branch: 1 branch
BranchTrueFalseTotal
if defined $reg_prefix 1 1 2
76 if defined $reg_prefix;
77  
78 my $ev_prefix = defined $params{event_prefix} ?
79 2 ▶ $params{event_prefix} : $params{ev_prefix};
Branch: 1 branch
BranchTrueFalseTotal
defined $params{'event_prefix'} ? : 0 2 2
80 2 ▶ $self->__pluggable_opts->{ev_prefix} = $ev_prefix
Branch: 1 branch
BranchTrueFalseTotal
if defined $ev_prefix 0 2 2
81 if defined $ev_prefix;
82  
83 2 ▶ if (defined $params{types}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $params{"types"}) 2 0 2
84 $self->__pluggable_opts->{types} =
85 ref $params{types} eq 'ARRAY' ?
86 0 ▶ +{ map {; $_ => $_ } @{ $params{types} } }
Branch: 1 branch
BranchTrueFalseTotal
ref $params{'types'} eq 'HASH' ? : 1 1 2
87 : ref $params{types} eq 'HASH' ?
88 $params{types}
89 2 ▶ : confess 'Expected ARRAY or HASH but got '.$params{types};
Branch: 1 branch
BranchTrueFalseTotal
ref $params{'types'} eq 'ARRAY' ? : 0 2 2
90 }
91  
92 $self
93 1 }
94  
95 24 ▶sub _pluggable_process {
Subroutine _pluggable_process: called CC=20 SCAR=31.1
96 24 my ($self, $type, $event, $args) = @_;
97  
98 # This is essentially the same logic as Object::Pluggable.
99 # Profiled, rewritten, and tightened up a bit;
100 #
101 # - Error handling is much faster as a normal sub
102 # Still need $self to dispatch _pluggable_event, but skipping method
103 # resolution and passing $self on the arg stack added a few hundred
104 # extra calls/sec, and override seems like an acceptable sacrifice
105 # Additionally our error handler is optimized
106 #
107 # - Do not invoke the regex engine at all, saving a fair bit of
108 # time; checking index() and applying substr() as needed to strip
109 # event prefixes is significantly quicker.
110 #
111 # - Conditionals have been optimized a bit.
112 #
113 # I'm open to other ideas . . .
114 24 ▶ confess 'Expected a type, event, and (possibly empty) args ARRAY'
Branch: 1 branch
BranchTrueFalseTotal
unless ref $args 1 23 24
115 unless ref $args;
116  
117 23 my $prefix = $self->__pluggable_opts->{ev_prefix};
118 23 ▶ substr($event, 0, length($prefix), '') if index($event, $prefix) == 0;
Branch: 1 branch
BranchTrueFalseTotal
if index($event, $prefix) == 0 16 7 23
119  
120 23 my $meth = $self->__pluggable_opts->{types}->{$type} .'_'. $event;
121  
122 23 my ($retval, $self_ret, @extra) = EAT_NONE;
123 23 local $@;
124 23 ▶ if ( $self->can($meth) ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($self->can($meth)) { } 17 6 23
elsif ($self->can('_default')) { } 2 4 6
125 # Dispatch to ourself
126 17 eval {; $self_ret = $self->$meth($self, \(@$args), \@extra) };
127 17 __plugin_process_chk($self, $self, $meth, $self_ret);
128 } elsif ( $self->can('_default') ) {
129 # Dispatch to _default
130 2 eval {; $self_ret = $self->_default($self, $meth, \(@$args), \@extra) };
131 2 __plugin_process_chk($self, $self, '_default', $self_ret);
132 }
133  
134 23 ▶ if (! defined $self_ret) {
Branch: 4 branches
BranchTrueFalseTotal
if (not defined $self_ret) { } 5 18 23
elsif ($self_ret == 3) { } 0 18 18
elsif ($self_ret == 2) { } 0 18 18
elsif ($self_ret == 4) { } 15 3 18
135 # No-op.
136 } elsif ( $self_ret == EAT_PLUGIN ) {
137 # Don't plugin-process, just return EAT_NONE.
138 # (Higher levels like Emitter can still pick this up.)
139 0 return $retval
140 } elsif ( $self_ret == EAT_CLIENT ) {
141 # Plugin process, but return EAT_ALL after.
142 0 $retval = EAT_ALL
143 } elsif ( $self_ret == EAT_ALL ) {
144 15 return EAT_ALL
145 }
146  
147 8 ▶ push @$args, splice @extra, 0, scalar(@extra) if @extra;
Branch: 1 branch
BranchTrueFalseTotal
if @extra 0 8 8
148  
149 8 my $handle_ref = $self->__pluggable_loaded->{HANDLE};
150 8 my $plug_ret;
151 8 PLUG: for my $thisplug (
152 grep {;
153 exists $handle_ref->{$_}->{$type}->{$event}
154 || exists $handle_ref->{$_}->{$type}->{all}
155 8 ▶ && $self != $_
Condition83%5/6
exists $handle_ref->{$_}{$type}{$event} || exists $handle_ref->{$_}{$type}{'all'} && $self != $_
l!l&&r!l&&!r
251
exists $handle_ref->{$_}{$type}{"all"} and $self != $_
!ll&&!rl&&r
105
MC/DC66%2/3
exists $handle_ref->{$_}{$type}{$event} || exists $handle_ref->{$_}{$type}{'all'} && $self != $_
exists $handle_ref->{$_}{$type}{$event} exists $handle_ref->{$_}{$type}{"all"} $self != $_
Truth table75%3/4
A || B and C
A= exists $handle_ref->{$_}{$type}{$event}B= exists $handle_ref->{$_}{$type}{"all"}C= $self != $_
ABCresult
1XX1
0111
00X0
0100
156 8 } @{ $self->__pluggable_pipeline } ) {
157 6 undef $plug_ret;
158 # Using by_ref is nicer, but the method call is too much overhead.
159 6 my $this_alias = $self->__pluggable_loaded->{OBJ}->{$thisplug};
160  
161 6 ▶ if ( $thisplug->can($meth) ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($thisplug->can($meth)) { } 5 1 6
elsif ($thisplug->can('_default')) { } 1 0 1
162 5 eval {;
163 5 $plug_ret = $thisplug->$meth($self, \(@$args), \@extra)
164 };
165 5 __plugin_process_chk($self, $thisplug, $meth, $plug_ret, $this_alias);
166 } elsif ( $thisplug->can('_default') ) {
167 1 eval {;
168 1 $plug_ret = $thisplug->_default($self, $meth, \(@$args), \@extra)
169 };
170 1 __plugin_process_chk($self, $thisplug, '_default', $plug_ret, $this_alias);
171 }
172  
173 6 ▶ if (! defined $plug_ret) {
Branch: 4 branches
BranchTrueFalseTotal
if (not defined $plug_ret) { } 0 6 6
elsif ($plug_ret == 3) { } 1 5 6
elsif ($plug_ret == 2) { } 0 5 5
elsif ($plug_ret == 4) { } 0 5 5
174 # No-op.
175 } elsif ($plug_ret == EAT_PLUGIN) {
176 # Stop plugin-processing.
177 # Return EAT_ALL if we previously had a EAT_CLIENT
178 # Return EAT_NONE otherwise
179 1 return $retval
180 } elsif ($plug_ret == EAT_CLIENT) {
181 # Set a pending EAT_ALL.
182 # If another plugin in the pipeline returns EAT_PLUGIN,
183 # we'll tell higher layers like Emitter to EAT_ALL
184 0 $retval = EAT_ALL
185 } elsif ($plug_ret == EAT_ALL) {
186 0 return EAT_ALL
187 }
188  
189 5 ▶ if (@extra) {
Branch: 1 branch
BranchTrueFalseTotal
if (@extra) 0 5 5
190 0 push @$args, splice @extra, 0, scalar(@extra);
191 }
192  
193 } # PLUG
194  
195 $retval
196 7 }
197  
198 25 ▶sub __plugin_process_chk {
Subroutine __plugin_process_chk: called CC=9 SCAR=26.8
199 # Ugly as sin, but fast if there are no errors, which matters here.
200  
201 25 ▶ if ($@) {
Branch: 2 branches
BranchTrueFalseTotal
if ($@) { } 1 24 25
elsif (not defined $_[3] or $_[3] != 1 and $_[3] != 4 and $_[3] != 2 and $_[3] != 3) { } 0 47 47
202 1 chomp $@;
203 1 my ($self, $obj, $meth, undef, $src) = @_;
204  
205 1 ▶ my $e_src = defined $src ? "plugin '$src'" : 'self' ;
Branch: 1 branch
BranchTrueFalseTotal
defined $src ? : 0 1 1
206 1 my $err = "$meth call on $e_src failed: $@";
207  
208 1 warn "$err\n";
209  
210 $self->_pluggable_event(
211 1 $self->__pluggable_opts->{ev_prefix} . "plugin_error",
212 $err,
213 $obj,
214 $e_src
215 );
216  
217 return
218 1 ▶ } elsif (! defined $_[3] ||
Condition66%8/12
not defined $_[3] or $_[3] != 1 and $_[3] != 4 and $_[3] != 2 and $_[3] != 3
l!l&&r!l&&!r
0024
$_[3] != 1 and $_[3] != 4 and $_[3] != 2 and $_[3] != 3
!ll&&!rl&&r
2310
$_[3] != 1 and $_[3] != 4 and $_[3] != 2
!ll&&!rl&&r
2301
$_[3] != 1 and $_[3] != 4
!ll&&!rl&&r
8151
MC/DC0%0/5
not defined $_[3] or $_[3] != 1 and $_[3] != 4 and $_[3] != 2 and $_[3] != 3
not defined $_[3] $_[3] != 1 $_[3] != 4 $_[3] != 2 $_[3] != 3
Truth table50%3/6
not(A) or B and C and D and E
A= not defined $_[3]B= $_[3] != 1C= $_[3] != 4D= $_[3] != 2E= $_[3] != 3
ABCDEresult
1XXXX1
011111
00XXX0
010XX0
0110X0
011100
219 ( $_[3] != EAT_NONE && $_[3] != EAT_ALL &&
220 $_[3] != EAT_CLIENT && $_[3] != EAT_PLUGIN ) ) {
221  
222 0 my ($self, $obj, $meth, undef, $src) = @_;
223  
224 0 ▶ my $e_src = defined $src ? "plugin '$src'" : 'self' ;
Branch: 1 branch
BranchTrueFalseTotal
defined $src ? : 0 0 0
225 0 my $err = "$meth call on $e_src did not return a valid EAT_ constant";
226  
227 0 warn "$err\n";
228  
229 $self->_pluggable_event(
230 0 $self->__pluggable_opts->{ev_prefix} . "plugin_error",
231 $err,
232 $obj,
233 $e_src
234 );
235  
236 return
237 0 }
238 }
239  
240  
241 ## Basic plugin manipulation (add/del/get/replace ...)
242  
243 4 ▶sub plugin_add {
Subroutine plugin_add: called CC=3 SCAR=12.5
Pod documented
244 4 my ($self, $alias, $plugin, @args) = @_;
245  
246 4 ▶ confess "Expected a plugin alias and object"
Branch: 1 branch
BranchTrueFalseTotal
unless defined $alias and builtin::blessed($plugin) 0 4 4
Condition33%1/3
defined $alias and builtin::blessed($plugin)
!ll&&!rl&&r
004
MC/DC0%0/2
defined $alias and builtin::blessed($plugin)
defined $alias builtin::blessed($plugin)
Truth table33%1/3
A and B
A= defined $aliasB= builtin::blessed($plugin)
ABresult
0X0
100
111
247 unless defined $alias and blessed $plugin;
248  
249 4 $self->plugin_pipe_push($alias, $plugin, @args)
250 }
251  
252 3 ▶sub plugin_alias_list {
Subroutine plugin_alias_list: called CC=1 SCAR=0.0
Pod documented
253 3 my ($self) = @_;
254 7 map {; $self->__pluggable_loaded->{OBJ}->{$_} }
255 3 @{ $self->__pluggable_pipeline }
256 }
257  
258 5 ▶sub plugin_del {
Subroutine plugin_del: called CC=2 SCAR=7.1
Pod documented
259 5 my ($self, $alias_or_plug, @args) = @_;
260  
261 5 ▶ confess "Expected a plugin alias"
Branch: 1 branch
BranchTrueFalseTotal
unless defined $alias_or_plug 0 5 5
262 unless defined $alias_or_plug;
263  
264 5 scalar( $self->__plugin_pipe_remove($alias_or_plug, @args) )
265 }
266  
267 2 ▶sub plugin_get {
Subroutine plugin_get: called CC=3 SCAR=11.8
Pod documented
268 2 my ($self, $item) = @_;
269  
270 2 my ($item_alias, $item_plug) = $self->__plugin_get_plug_any($item);
271  
272 2 ▶ unless (defined $item_plug) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $item_plug) 0 2 2
273 0 carp ($@ = "No such plugin: $item_alias");
274 return
275 0 }
276  
277 2 ▶ wantarray ? ($item_plug, $item_alias) : $item_plug
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 1 1 2
278 }
279  
280 1 ▶sub plugin_replace {
Subroutine plugin_replace: called CC=10 SCAR=26.2
Pod documented
281 1 my ($self, %params) = @_;
282 1 $params{lc $_} = delete $params{$_} for keys %params;
283  
284 # ->plugin_replace(
285 # old => $obj || $alias,
286 # alias => $newalias,
287 # plugin => $newplug,
288 # # optional:
289 # unregister_args => ARRAY
290 # register_args => ARRAY
291 # )
292  
293 1 for (qw/old alias plugin/) {
294 confess "Missing required param $_"
295 3 ▶ unless defined $params{$_}
Branch: 1 branch
BranchTrueFalseTotal
unless defined $params{$_} 0 3 3
296 }
297  
298 my ($old_alias, $old_plug)
299 1 = $self->__plugin_get_plug_any( $params{old} );
300  
301 1 ▶ unless (defined $old_plug) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $old_plug) 0 1 1
302 0 $@ = "No such plugin: $old_alias";
303 0 carp $@;
304 return
305 0 }
306  
307 my @unreg_args = ref $params{unregister_args} eq 'ARRAY' ?
308 0 ▶ @{ $params{unregister_args} } : () ;
Branch: 1 branch
BranchTrueFalseTotal
ref $params{'unregister_args'} eq 'ARRAY' ? : 0 1 1
309  
310 1 $self->__plug_pipe_unregister( $old_alias, $old_plug, @unreg_args );
311  
312 1 my ($new_alias, $new_plug) = @params{'alias','plugin'};
313  
314 return unless $self->__plug_pipe_register( $new_alias, $new_plug,
315 (
316 ref $params{register_args} eq 'ARRAY' ?
317 0 ▶ @{ $params{register_args} } : ()
Branch: 2 branches
BranchTrueFalseTotal
unless $self->__plug_pipe_register($new_alias, $new_plug, ref $params{"register_args"} eq "ARRAY" ? @{$params{"register_args"};} : ()) 0 1 1
ref $params{'register_args'} eq 'ARRAY' ? : 0 1 1
318 ),
319 );
320  
321 1 for my $thisplug (@{ $self->__pluggable_pipeline }) {
322 1 ▶ if ($thisplug == $old_plug) {
Branch: 1 branch
BranchTrueFalseTotal
if ($thisplug == $old_plug) 1 0 1
323 1 $thisplug = $params{plugin};
324 last
325 1 }
326 }
327  
328 $old_plug
329 1 }
330  
331  
332 ## Event registration.
333  
334 5 ▶sub subscribe {
Subroutine subscribe: called CC=8 SCAR=23.4
Pod documented
335 5 my ($self, $plugin, $type, @events) = @_;
336  
337 confess "Cannot subscribe; event type $type not supported"
338 5 ▶ unless exists $self->__pluggable_opts->{types}->{$type};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->__pluggable_opts->{"types"}{$type} 0 5 5
339  
340 5 ▶ confess "Expected a plugin object, a type, and a list of events"
Branch: 1 branch
BranchTrueFalseTotal
unless @events 0 5 5
341 unless @events;
342  
343 5 ▶ confess "Expected a blessed plugin object" unless blessed $plugin;
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($plugin) 0 5 5
344  
345 my $handles
346 5 ▶ = $self->__pluggable_loaded->{HANDLE}->{$plugin}->{$type}
Condition50%1/2
$self->__pluggable_loaded->{"HANDLE"}{$plugin}{$type} ||= {}
l!l
05
MC/DC0%0/1
$self->__pluggable_loaded->{"HANDLE"}{$plugin}{$type} ||= {}
$self->__pluggable_loaded->{"HANDLE"}{$plugin}{$type}
Truth table50%1/2
A
A= $self->__pluggable_loaded->{"HANDLE"}{$plugin}{$type}
Aresult
11
00
347 ||= +{};
348  
349 5 for my $ev (@events) {
350 6 ▶ if (ref $ev eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $ev eq "ARRAY") 0 6 6
351 0 $handles->{$_} = 1 for @$ev;
352 next
353 0 }
354 6 $handles->{$ev} = 1
355 }
356  
357 1
358 5 }
359  
360 0 ▶sub unsubscribe {
Subroutine unsubscribe: not called CC=11 SCAR=48.8
Pod documented
361 0 my ($self, $plugin, $type, @events) = @_;
362  
363 confess "Cannot unsubscribe; event type $type not supported"
364 0 ▶ unless exists $self->__pluggable_opts->{types}->{$type};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->__pluggable_opts->{"types"}{$type} 0 0 0
365  
366 0 ▶ confess "Expected a blessed plugin obj, event type, and events to unsubscribe"
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($plugin) and defined $type 0 0 0
Condition0%0/3
builtin::blessed($plugin) and defined $type
!ll&&!rl&&r
000
MC/DC0%0/2
builtin::blessed($plugin) and defined $type
builtin::blessed($plugin) defined $type
Truth table0%0/3
A and B
A= builtin::blessed($plugin)B= defined $type
ABresult
0X0
100
111
367 unless blessed $plugin and defined $type;
368  
369 0 ▶ confess "No events specified; did you mean to plugin_del instead?"
Branch: 1 branch
BranchTrueFalseTotal
unless @events 0 0 0
370 unless @events;
371  
372 my $handles =
373 0 ▶ $self->__pluggable_loaded->{HANDLE}->{$plugin}->{$type} || +{};
Condition0%0/2
$self->__pluggable_loaded->{'HANDLE'}{$plugin}{$type} || {}
l!l
00
MC/DC0%0/1
$self->__pluggable_loaded->{'HANDLE'}{$plugin}{$type} || {}
$self->__pluggable_loaded->{'HANDLE'}{$plugin}{$type}
Truth table0%0/2
A
A= $self->__pluggable_loaded->{'HANDLE'}{$plugin}{$type}
Aresult
11
00
374  
375 0 for my $ev (@events) {
376 0 ▶ if (ref $ev eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $ev eq 'ARRAY') { } 0 0 0
377 0 for my $this_ev (@$ev) {
378 0 ▶ unless (delete $handles->{$this_ev}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (delete $handles->{$this_ev}) 0 0 0
379 0 carp "Nonexistant event $this_ev cannot be unsubscribed from";
380 }
381 }
382 } else {
383 0 ▶ unless (delete $handles->{$ev}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (delete $handles->{$ev}) 0 0 0
384 0 carp "Nonexistant event $ev cannot be unsubscribed from";
385 }
386 }
387  
388 }
389  
390 1
391 0 }
392  
393  
394 ## Pipeline methods.
395  
396 4 ▶sub plugin_pipe_push {
Subroutine plugin_pipe_push: called CC=3 SCAR=12.3
Pod documented
397 4 my ($self, $alias, $plug, @args) = @_;
398  
399 4 ▶ if (my $existing = $self->__plugin_by_alias($alias) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $existing = $self->__plugin_by_alias($alias)) 0 4 4
400 0 $@ = "Already have plugin $alias : $existing";
401 0 carp $@;
402 return
403 0 }
404  
405 4 ▶ return unless $self->__plug_pipe_register($alias, $plug, @args);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->__plug_pipe_register($alias, $plug, @args) 0 4 4
406  
407 4 push @{ $self->__pluggable_pipeline }, $plug;
408  
409 4 scalar @{ $self->__pluggable_pipeline }
410 }
411  
412 0 ▶sub plugin_pipe_pop {
Subroutine plugin_pipe_pop: not called CC=3 SCAR=24.8
Pod documented
413 0 my ($self, @args) = @_;
414  
415 0 ▶ return unless @{ $self->__pluggable_pipeline };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->__pluggable_pipeline;} 0 0 0
416  
417 0 my $plug = pop @{ $self->__pluggable_pipeline };
418 0 my $alias = $self->__plugin_by_ref($plug);
419  
420 0 $self->__plug_pipe_unregister($alias, $plug, @args);
421  
422 0 ▶ wantarray ? ($plug, $alias) : $plug
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
423 }
424  
425 1 ▶sub plugin_pipe_unshift {
Subroutine plugin_pipe_unshift: called CC=3 SCAR=12.3
Pod documented
426 1 my ($self, $alias, $plug, @args) = @_;
427  
428 1 ▶ if (my $existing = $self->__plugin_by_alias($alias) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $existing = $self->__plugin_by_alias($alias)) 0 1 1
429 0 $@ = "Already have plugin $alias : $existing";
430 0 carp $@;
431 return
432 0 }
433  
434 1 ▶ return unless $self->__plug_pipe_register($alias, $plug, @args);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->__plug_pipe_register($alias, $plug, @args) 0 1 1
435  
436 1 unshift @{ $self->__pluggable_pipeline }, $plug;
437  
438 1 scalar @{ $self->__pluggable_pipeline }
439 }
440  
441 1 ▶sub plugin_pipe_shift {
Subroutine plugin_pipe_shift: called CC=3 SCAR=11.1
Pod documented
442 1 my ($self, @args) = @_;
443  
444 1 ▶ return unless @{ $self->__pluggable_pipeline };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->__pluggable_pipeline;} 0 1 1
445  
446 1 my $plug = shift @{ $self->__pluggable_pipeline };
447 1 my $alias = $self->__plugin_by_ref($plug);
448  
449 1 $self->__plug_pipe_unregister($alias, $plug, @args);
450  
451 1 ▶ wantarray ? ($plug, $alias) : $plug
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
452 }
453  
454 5 ▶sub __plugin_pipe_remove {
Subroutine __plugin_pipe_remove: called CC=5 SCAR=17.6
455 5 my ($self, $old, @unreg_args) = @_;
456  
457 5 my ($old_alias, $old_plug) = $self->__plugin_get_plug_any($old);
458  
459 5 ▶ unless (defined $old_plug) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $old_plug) 0 5 5
460 0 $@ = "No such plugin: $old_alias";
461 0 carp $@;
462 return
463 0 }
464  
465 5 my $idx = 0;
466 5 for my $thisplug (@{ $self->__pluggable_pipeline }) {
467 5 ▶ if ($thisplug == $old_plug) {
Branch: 1 branch
BranchTrueFalseTotal
if ($thisplug == $old_plug) 5 0 5
468 5 splice @{ $self->__pluggable_pipeline }, $idx, 1;
469 last
470 5 }
471 0 ++$idx;
472 }
473  
474 5 $self->__plug_pipe_unregister( $old_alias, $old_plug, @unreg_args );
475  
476 5 ▶ wantarray ? ($old_plug, $old_alias) : $old_plug
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 5 5
477 }
478  
479 9 ▶sub plugin_pipe_get_index {
Subroutine plugin_pipe_get_index: called CC=4 SCAR=15.0
Pod documented
480 9 my ($self, $item) = @_;
481  
482 9 my ($item_alias, $item_plug) = $self->__plugin_get_plug_any($item);
483  
484 9 ▶ unless (defined $item_plug) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $item_plug) 0 9 9
485 0 $@ = "No such plugin: $item_alias";
486 0 carp $@;
487 0 return -1
488 }
489  
490 9 my $idx = 0;
491 9 for my $thisplug (@{ $self->__pluggable_pipeline }) {
492 13 ▶ return $idx if $thisplug == $item_plug;
Branch: 1 branch
BranchTrueFalseTotal
if $thisplug == $item_plug 9 4 13
493 4 $idx++;
494 }
495  
496 0 return -1
497 }
498  
499 1 ▶sub plugin_pipe_insert_before {
Subroutine plugin_pipe_insert_before: called CC=10 SCAR=26.2
Pod documented
500 1 my ($self, %params) = @_;
501 1 $params{lc $_} = delete $params{$_} for keys %params;
502 # ->insert_before(
503 # before =>
504 # alias =>
505 # plugin =>
506 # register_args =>
507 # );
508  
509 1 for (qw/before alias plugin/) {
510 confess "Missing required param $_"
511 3 ▶ unless defined $params{$_}
Branch: 1 branch
BranchTrueFalseTotal
unless defined $params{$_} 0 3 3
512 }
513  
514 my ($prev_alias, $prev_plug)
515 1 = $self->__plugin_get_plug_any( $params{before} );
516  
517 1 ▶ unless (defined $prev_plug) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $prev_plug) 0 1 1
518 0 $@ = "No such plugin: $prev_alias";
519 0 carp $@;
520 return
521 0 }
522  
523 1 ▶ if ( my $existing = $self->__plugin_by_alias($params{alias}) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $existing = $self->__plugin_by_alias($params{"alias"})) 0 1 1
524 0 $@ = "Already have plugin $params{alias} : $existing";
525 0 carp $@;
526 return
527 0 }
528  
529 return unless $self->__plug_pipe_register(
530 $params{alias}, $params{plugin},
531 (
532 ref $params{register_args} eq 'ARRAY' ?
533 0 ▶ @{ $params{register_args} } : ()
Branch: 2 branches
BranchTrueFalseTotal
unless $self->__plug_pipe_register($params{"alias"}, $params{"plugin"}, ref $params{"register_args"} eq "ARRAY" ? @{$params{"register_args"};} : ()) 0 1 1
ref $params{'register_args'} eq 'ARRAY' ? : 0 1 1
534 )
535 );
536  
537 1 my $idx = 0;
538 1 for my $thisplug (@{ $self->__pluggable_pipeline }) {
539 2 ▶ if ($thisplug == $prev_plug) {
Branch: 1 branch
BranchTrueFalseTotal
if ($thisplug == $prev_plug) 1 1 2
540 1 splice @{ $self->__pluggable_pipeline }, $idx, 0, $params{plugin};
541 last
542 1 }
543 1 $idx++;
544 }
545  
546 1
547 1 }
548  
549 1 ▶sub plugin_pipe_insert_after {
Subroutine plugin_pipe_insert_after: called CC=10 SCAR=27.7
Pod documented
550 1 my ($self, %params) = @_;
551 1 $params{lc $_} = delete $params{$_} for keys %params;
552  
553 1 for (qw/after alias plugin/) {
554 confess "Missing required param $_"
555 3 ▶ unless defined $params{$_}
Branch: 1 branch
BranchTrueFalseTotal
unless defined $params{$_} 0 3 3
556 }
557  
558 my ($next_alias, $next_plug)
559 1 = $self->__plugin_get_plug_any( $params{after} );
560  
561 1 ▶ unless (defined $next_plug) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $next_plug) 0 1 1
562 0 $@ = "No such plugin: $next_alias";
563 0 carp $@;
564 return
565 0 }
566  
567 1 ▶ if ( my $existing = $self->__plugin_by_alias($params{alias}) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $existing = $self->__plugin_by_alias($params{"alias"})) 0 1 1
568 0 $@ = "Already have plugin $params{alias} : $existing";
569 0 carp $@;
570 return
571 0 }
572  
573 return unless $self->__plug_pipe_register(
574 $params{alias}, $params{plugin},
575 (
576 ref $params{register_args} eq 'ARRAY' ?
577 0 ▶ @{ $params{register_args} } : ()
Branch: 2 branches
BranchTrueFalseTotal
unless $self->__plug_pipe_register($params{"alias"}, $params{"plugin"}, ref $params{"register_args"} eq "ARRAY" ? @{$params{"register_args"};} : ()) 0 1 1
ref $params{'register_args'} eq 'ARRAY' ? : 0 1 1
578 ),
579 );
580  
581 1 my $idx = 0;
582 1 for my $thisplug (@{ $self->__pluggable_pipeline }) {
583 1 ▶ if ($thisplug == $next_plug) {
Branch: 1 branch
BranchTrueFalseTotal
if ($thisplug == $next_plug) 1 0 1
584 1 splice @{ $self->__pluggable_pipeline }, $idx+1, 0, $params{plugin};
585 last
586 1 }
587 0 $idx++;
588 }
589  
590 1
591 1 }
592  
593 1 ▶sub plugin_pipe_bump_up {
Subroutine plugin_pipe_bump_up: called CC=4 SCAR=14.5
Pod documented
594 1 my ($self, $item, $delta) = @_;
595  
596 1 my $idx = $self->plugin_pipe_get_index($item);
597 1 ▶ return -1 unless $idx >= 0;
Branch: 1 branch
BranchTrueFalseTotal
unless $idx >= 0 0 1 1
598  
599 1 ▶ my $pos = $idx - ($delta || 1);
Condition50%1/2
$delta || 1
l!l
10
MC/DC0%0/1
$delta || 1
$delta
Truth table50%1/2
A
A= $delta
Aresult
11
00
600  
601 1 ▶ unless ($pos >= 0) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($pos >= 0) 0 1 1
602 0 carp "Negative position ($idx - $delta is $pos), bumping to head"
603 }
604  
605 1 splice @{ $self->__pluggable_pipeline }, $pos, 0,
606 1 splice @{ $self->__pluggable_pipeline }, $idx, 1;
607  
608 1 $pos
609 }
610  
611 1 ▶sub plugin_pipe_bump_down {
Subroutine plugin_pipe_bump_down: called CC=4 SCAR=14.4
Pod documented
612 1 my ($self, $item, $delta) = @_;
613  
614 1 my $idx = $self->plugin_pipe_get_index($item);
615 1 ▶ return -1 unless $idx >= 0;
Branch: 1 branch
BranchTrueFalseTotal
unless $idx >= 0 0 1 1
616  
617 1 ▶ my $pos = $idx + ($delta || 1);
Condition50%1/2
$delta || 1
l!l
10
MC/DC0%0/1
$delta || 1
$delta
Truth table50%1/2
A
A= $delta
Aresult
11
00
618  
619 1 ▶ if ($pos >= @{ $self->__pluggable_pipeline }) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pos >= @{$self->__pluggable_pipeline;}) 0 1 1
620 0 carp "Cannot bump below end of pipeline, pushing to tail"
621 }
622  
623 1 splice @{ $self->__pluggable_pipeline }, $pos, 0,
624 1 splice @{ $self->__pluggable_pipeline }, $idx, 1;
625  
626 1 $pos
627 }
628  
629 8 ▶sub __plug_pipe_register {
Subroutine __plug_pipe_register: called CC=3 SCAR=12.2
630 8 my ($self, $new_alias, $new_plug, @args) = @_;
631  
632 # Register this as a known plugin.
633 # Try to call $reg_prefix . "register"
634  
635 8 my ($retval, $err);
636 8 my $meth = $self->__pluggable_opts->{reg_prefix} . "register" ;
637  
638 8 ▶ try {
Subroutine __ANON__: called CC=1 SCAR=0.0
639 8 $retval = $new_plug->$meth( $self, @args )
640 0 ▶ } catch {
Subroutine __ANON__: not called CC=1 SCAR=6.9
641 0 chomp;
642 0 $err = "$meth call on '$new_alias' failed: $_";
643 8 };
644  
645 8 ▶ unless ($retval) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($retval) 0 8 8
646 0 $err = "$meth call on '$new_alias' returned false";
647 }
648  
649 8 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 0 8 8
650 0 $self->__plug_pipe_handle_err( $err, $new_plug, $new_alias );
651 return
652 0 }
653  
654 8 $self->__pluggable_loaded->{ALIAS}->{$new_alias} = $new_plug;
655 8 $self->__pluggable_loaded->{OBJ}->{$new_plug} = $new_alias;
656  
657 $self->_pluggable_event(
658 8 $self->__pluggable_opts->{ev_prefix} . "plugin_added",
659 $new_alias,
660 $new_plug
661 );
662  
663 8 $retval
664 }
665  
666 7 ▶sub __plug_pipe_unregister {
Subroutine __plug_pipe_unregister: called CC=4 SCAR=15.0
667 7 my ($self, $old_alias, $old_plug, @args) = @_;
668  
669 7 my ($retval, $err);
670 7 my $meth = $self->__pluggable_opts->{reg_prefix} . "unregister" ;
671  
672 7 ▶ try {
Subroutine __ANON__: called CC=1 SCAR=0.0
673 7 $retval = $old_plug->$meth( $self, @args )
674 0 ▶ } catch {
Subroutine __ANON__: not called CC=1 SCAR=6.9
675 0 chomp;
676 0 $err = "$meth call on '$old_alias' failed: $_";
677 7 };
678  
679 7 ▶ unless ($retval) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($retval) 0 7 7
680 0 $err = "$meth called on '$old_alias' returned false";
681 }
682  
683 7 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 0 7 7
684 0 $self->__plug_pipe_handle_err( $err, $old_plug, $old_alias );
685 }
686  
687 7 delete $self->__pluggable_loaded->{ALIAS}->{$old_alias};
688 delete $self->__pluggable_loaded->{$_}->{$old_plug}
689 7 for qw/ OBJ HANDLE /;
690  
691 $self->_pluggable_event(
692 7 $self->__pluggable_opts->{ev_prefix} . "plugin_removed",
693 $old_alias,
694 $old_plug
695 );
696  
697 7 $retval
698 }
699  
700 0 ▶sub __plug_pipe_handle_err {
Subroutine __plug_pipe_handle_err: not called CC=1 SCAR=6.9
701 0 my ($self, $err, $plugin, $alias) = @_;
702  
703 0 warn "$err\n";
704  
705 $self->_pluggable_event(
706 0 $self->__pluggable_opts->{ev_prefix} . "plugin_error",
707 $err,
708 $plugin,
709 $alias
710 );
711 }
712  
713 7 ▶sub __plugin_by_alias {
Subroutine __plugin_by_alias: called CC=1 SCAR=0.0
714 7 my ($self, $item) = @_;
715  
716 7 $self->__pluggable_loaded->{ALIAS}->{$item}
717 }
718  
719 1 ▶sub __plugin_by_ref {
Subroutine __plugin_by_ref: called CC=1 SCAR=0.0
720 1 my ($self, $item) = @_;
721  
722 1 $self->__pluggable_loaded->{OBJ}->{$item}
723 }
724  
725 19 ▶sub __plugin_get_plug_any {
Subroutine __plugin_get_plug_any: called CC=2 SCAR=6.9
726 19 my ($self, $item) = @_;
727  
728 blessed $item ?
729 ( $self->__pluggable_loaded->{OBJ}->{$item}, $item )
730 19 ▶ : ( $item, $self->__pluggable_loaded->{ALIAS}->{$item} );
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($item) ? : 1 18 19
731 }
732  
733  
734 2 ▶print
Branch: 1 branch
BranchTrueFalseTotal
unless caller 0 2 2
735 qq[<F2> How can I run two separate process at the same time simultaneously?\n],
736 qq[<dngor> I'd use an operating system, and have it run them for me.\n]
737 unless caller;
738  
739 2 1;
740  
741 =pod
742  
743 =head1 NAME
744  
745 MooX::Role::Pluggable - A plugin pipeline for your Moo-based class
746  
747 =head1 SYNOPSIS
748  
749 # A simple pluggable dispatcher:
750 package MyDispatcher;
751 use MooX::Role::Pluggable::Constants;
752 use Moo;
753 with 'MooX::Role::Pluggable';
754  
755 sub BUILD {
756 my ($self) = @_;
757  
758 # (optionally) Configure our plugin pipeline
759 $self->_pluggable_init(
760 reg_prefix => 'Plug_',
761 ev_prefix => 'Event_',
762 types => {
763 NOTIFY => 'N',
764 PROCESS => 'P',
765 },
766 );
767 }
768  
769 around '_pluggable_event' => sub {
770 # This override redirects internal events (errors, etc) to ->process()
771 my ($orig, $self) = splice @_, 0, 2;
772 $self->process( @_ )
773 };
774  
775 sub process {
776 my ($self, $event, @args) = @_;
777  
778 # Dispatch to 'P_' prefixed "PROCESS" type handlers.
779 #
780 # _pluggable_process will automatically strip a leading 'ev_prefix'
781 # (see the call to _pluggable_init above); that lets us easily
782 # dispatch errors to our P_plugin_error handler below without worrying
783 # about our ev_prefix ourselves:
784 my $retval = $self->_pluggable_process( PROCESS =>
785 $event,
786 \@args
787 );
788  
789 unless ($retval == EAT_ALL) {
790 # The pipeline allowed the event to continue.
791 # A dispatcher might re-dispatch elsewhere, etc.
792 }
793 }
794  
795 sub shutdown {
796 my ($self) = @_;
797 # Unregister all of our plugins.
798 $self->_pluggable_destroy;
799 }
800  
801 sub P_plugin_error {
802 # Since we re-dispatched errors in our _pluggable_event handler,
803 # we could handle exceptions here and then eat them, perhaps:
804 my ($self, undef) = splice @_, 0, 2;
805  
806 # Arguments are references:
807 my $plug_err = ${ $_[0] };
808 my $plug_obj = ${ $_[1] };
809 my $error_src = ${ $_[2] };
810  
811 # ...
812  
813 EAT_ALL
814 }
815  
816  
817 # A Plugin object.
818 package MyPlugin;
819  
820 use MooX::Role::Pluggable::Constants;
821  
822 sub new { bless {}, shift }
823  
824 sub Plug_register {
825 my ($self, $core) = @_;
826  
827 # Subscribe to events:
828 $core->subscribe( $self, 'PROCESS',
829 'my_event',
830 'another_event'
831 );
832  
833 # Log that we're here, do some initialization, etc ...
834  
835 return EAT_NONE
836 }
837  
838 sub Plug_unregister {
839 my ($self, $core) = @_;
840 # Called when this plugin is unregistered
841 # ... do some cleanup, etc ...
842 return EAT_NONE
843 }
844  
845 sub P_my_event {
846 # Handle a dispatched "PROCESS"-type event:
847 my ($self, $core) = splice @_, 0, 2;
848  
849 # Arguments are references and can be modified:
850 my $arg = ${ $_[0] };
851  
852 # ... do some work ...
853  
854 # Return an EAT constant to control event lifetime
855 # EAT_NONE allows this event to continue through the pipeline
856 return EAT_NONE
857 }
858  
859 # An external package that interacts with our dispatcher;
860 # this is just a quick and dirty example to show external
861 # plugin manipulation:
862  
863 package MyController;
864 use Moo;
865  
866 has dispatcher => (
867 is => 'rw',
868 default => sub { MyDispatcher->new() },
869 );
870  
871 sub BUILD {
872 my ($self) = @_;
873 $self->dispatcher->plugin_add( 'MyPlugin', MyPlugin->new );
874 }
875  
876 sub do_stuff {
877 my $self = shift;
878 $self->dispatcher->process( 'my_event', @_ )
879 }
880  
881 =head1 DESCRIPTION
882  
883 A L<Moo::Role> for turning instances of your class into pluggable objects.
884 Consumers of this role gain a plugin pipeline and methods to manipulate it,
885 as well as a flexible dispatch system (see L</_pluggable_process>).
886  
887 The logic and behavior is based almost entirely on L<Object::Pluggable> (see
888 L</AUTHOR>). Some methods are the same; implementation & some interface
889 differ. Dispatch is significantly faster -- see L</Performance>.
890  
891 If you're using L<POE>, also see L<MooX::Role::POE::Emitter>, which consumes
892 this role.
893  
894 =head2 Initialization
895  
896 =head3 _pluggable_init
897  
898 $self->_pluggable_init(
899 # Prefix for registration events.
900 # Defaults to 'plugin_' ('plugin_register' / 'plugin_unregister')
901 reg_prefix => 'plugin_',
902  
903 # Prefix for dispatched internal events
904 # (add, del, error, register, unregister ...)
905 # Defaults to 'plugin_ev_'
906 event_prefix => 'plugin_ev_',
907  
908 # Map type names to prefixes;
909 # Event types can be named arbitrarily. Their respective prefix is
910 # prepended when dispatching events of that type.
911 # Here are the defaults:
912 types => {
913 NOTIFY => 'N',
914 PROCESS => 'P',
915 },
916 );
917  
918 A consumer can call B<_pluggable_init> to set up pipeline-related options
919 appropriately; this should be done prior to loading plugins or dispatching to
920 L</_pluggable_process>. If it is not called, the defaults (as shown above) are
921 used.
922  
923 B<< types => >> can be either an ARRAY of event types (which will be used as
924 prefixes):
925  
926 types => [ qw/ IncomingEvent OutgoingEvent / ],
927  
928 ... or a HASH mapping an event type to a prefix:
929  
930 types => {
931 Incoming => 'I',
932 Outgoing => 'O',
933 },
934  
935 A trailing C<_> is automatically appended to event type prefixes when events
936 are dispatched via L</_pluggable_process>; thus, an event destined for our
937 'Incoming' type shown above will be dispatched to appropriate C<I_> handlers:
938  
939 # Dispatched to 'I_foo' method in plugins registered for Incoming 'foo':
940 $self->_pluggable_process( Incoming => 'foo', 'bar', 'baz' );
941  
942 C<reg_prefix>/C<event_prefix> are not automatically munged in any way.
943  
944 An empty string is a valid value for C<reg_prefix>/C<event_prefix>.
945  
946 =head3 _pluggable_destroy
947  
948 $self->_pluggable_destroy;
949  
950 Shuts down the plugin pipeline, unregistering/unloading all known plugins.
951  
952 =head3 _pluggable_event
953  
954 # In our consumer:
955 sub _pluggable_event {
956 my ($self, $event, @args) = @_;
957 # Dispatch out, perhaps.
958 }
959  
960 C<_pluggable_event> is called for internal notifications, such as plugin
961 load/unload and error reporting (see L</Internal Events>) -- it can be
962 overriden in your consuming class to do something useful with the dispatched
963 event and any arguments passed.
964  
965 The C<$event> given will be prefixed with the configured B<event_prefix>.
966  
967 (It's not strictly necessary to implement a C<_pluggable_event> handler; errors
968 will also C<warn>.)
969  
970 =head2 Registration
971  
972 A plugin is any blessed object that is registered with your Pluggable object
973 via L</plugin_add>; during registration, plugins usually subscribe to some
974 events via L</subscribe>.
975  
976 See L</plugin_add> regarding loading plugins.
977  
978 =head3 subscribe
979  
980 B<Subscribe a plugin to some pluggable events.>
981  
982 $self->subscribe( $plugin_obj, $type, @events );
983  
984 Registers a plugin object to receive C<@events> of type C<$type>.
985  
986 This is typically called from within the plugin's registration handler (see
987 L</plugin_register>):
988  
989 # In a plugin:
990 sub plugin_register {
991 my ($self, $core) = @_;
992  
993 $core->subscribe( $self, PROCESS =>
994 qw/
995 my_event
996 another_event
997 /
998 );
999  
1000 $core->subscribe( $self, NOTIFY => 'all' );
1001  
1002 EAT_NONE
1003 }
1004  
1005 Subscribe to B<all> to receive all events -- but note that subscribing many
1006 plugins to 'all' events is less performant during calls to
1007 L</_pluggable_process> than many subscriptions to specific events.
1008  
1009 =head3 unsubscribe
1010  
1011 B<Unsubscribe a plugin from subscribed events.>
1012  
1013 Carries the same arguments as L</subscribe>.
1014  
1015 The plugin is still loaded and registered until L</plugin_del> is called, even
1016 if there are no current event subscriptions.
1017  
1018 =head3 plugin_register
1019  
1020 B<Defined in your plugin(s) and called at load time.>
1021  
1022 (Note that 'plugin_' is just a default register method prefix; it can be
1023 changed prior to loading plugins. See L</_pluggable_init> for details.)
1024  
1025 The C<plugin_register> method is called on a loaded plugin when it is added to
1026 the pipeline; it is passed the plugin object (C<$self>), the Pluggable object,
1027 and any arguments given to L</plugin_add> (or similar registration methods).
1028  
1029 Normally one might call a L</subscribe> from here to start receiving events
1030 after load-time:
1031  
1032 # In a plugin:
1033 sub plugin_register {
1034 my ($self, $core, @args) = @_;
1035 $core->subscribe( $self, 'NOTIFY', @events );
1036 EAT_NONE
1037 }
1038  
1039 =head3 plugin_unregister
1040  
1041 B<Defined in your plugin(s) and called at load time.>
1042  
1043 (Note that 'plugin_' is just a default register method prefix; it can be
1044 changed prior to loading plugins. See L</_pluggable_init> for details.)
1045  
1046 The unregister counterpart to L</plugin_register>, called when the plugin
1047 object is removed from the pipeline (via L</plugin_del> or
1048 L</_pluggable_destroy>).
1049  
1050 # In a plugin:
1051 sub plugin_unregister {
1052 my ($self, $core) = @_;
1053 EAT_NONE
1054 }
1055  
1056 Carries the same arguments as L</plugin_register>.
1057  
1058 =head2 Dispatch
1059  
1060 =head3 _pluggable_process
1061  
1062 # In your consumer's dispatch method:
1063 my $eat = $self->_pluggable_process( $type, $event, \@args );
1064 return 1 if $eat == EAT_ALL;
1065  
1066 The C<_pluggable_process> method handles dispatching.
1067  
1068 If C<$event> is prefixed with our event prefix (see L</_pluggable_init>),
1069 the prefix is stripped prior to dispatch (to be replaced with a type
1070 prefix matching the specified C<$type>).
1071  
1072 Arguments should be passed as a reference to an array. During dispatch,
1073 references to the provided arguments are passed to relevant plugin subroutines
1074 following the automatically-prepended plugin and Pluggable consumer objects
1075 (respectively); this allows for argument modification as an event is passed
1076 along the plugin pipeline:
1077  
1078 my @args = qw/baz bar/;
1079 $self->_pluggable_process( NOTIFY => foo => \@args );
1080  
1081 # In a plugin:
1082 sub N_foo {
1083 # Remove automatically-provided plugin and consumer objects from @_
1084 my ($self, $core) = splice @_, 0, 2;
1085  
1086 # Dereference expected scalars
1087 my $bar = ${ $_[0] };
1088 my $num = ${ $_[1] };
1089  
1090 # Increment actual second argument before pipeline dispatch continues
1091 ++${ $_[1] };
1092  
1093 EAT_NONE
1094 }
1095  
1096 =head4 Dispatch Process
1097  
1098 Your Pluggable consuming class typically provides syntax sugar to
1099 dispatch different types or "classes" of events:
1100  
1101 sub process {
1102 # Dispatch to 'PROCESS'-type events
1103 my ($self, $event, @args) = @_;
1104 my $eat = $self->_pluggable_process( PROCESS => $event, \@args );
1105 # ... possibly take further action based on $eat return value, see below
1106 }
1107  
1108 sub notify {
1109 # Dispatch to 'NOTIFY'-type events
1110 my ($self, $event, @args) = @_;
1111 my $eat = $self->_pluggable_process( NOTIFY => $event, \@args );
1112 # ...
1113 }
1114  
1115 Event types and matching prefixes can be arbitrarily named to provide event
1116 dispatch flexibility. For example, the dispatch process for C<$event> 'foo' of
1117 C<$type> 'NOTIFY' performs the following actions:
1118  
1119 $self->_pluggable_process( NOTIFY => foo => \@args );
1120  
1121 # - Prepend the known prefix for the specified type and '_'
1122 # 'foo' -> 'N_foo'
1123 #
1124 # - Attempt to dispatch to $self->N_foo()
1125 #
1126 # - If no such method, attempt to dispatch to $self->_default()
1127 # (When using _default, the method we were attempting to call is prepended
1128 # to arguments.)
1129 #
1130 # - If the event was not eaten by the Pluggable consumer (see below), call
1131 # $plugin->N_foo() for subscribed plugins sequentially until event is eaten
1132 # or no relevant plugins remain.
1133  
1134 "Eaten" means a handler returned an EAT_* constant from
1135 L<MooX::Role::Pluggable::Constants> indicating that the event's lifetime
1136 should terminate.
1137  
1138 B<If our consuming class provides a method or '_default' that returns:>
1139  
1140 EAT_ALL: skip plugin pipeline, return EAT_ALL
1141 EAT_CLIENT: continue to plugin pipeline
1142 return EAT_ALL if plugin returns EAT_PLUGIN later
1143 EAT_PLUGIN: skip plugin pipeline entirely
1144 return EAT_NONE unless EAT_CLIENT was seen previously
1145 EAT_NONE: continue to plugin pipeline
1146  
1147 B<If one of our plugins in the pipeline returns:>
1148  
1149 EAT_ALL: skip further plugins, return EAT_ALL
1150 EAT_CLIENT: continue to next plugin, set pending EAT_ALL
1151 (EAT_ALL will be returned when plugin processing finishes)
1152 EAT_PLUGIN: return EAT_ALL if previous sub returned EAT_CLIENT
1153 else return EAT_NONE
1154 EAT_NONE: continue to next plugin
1155  
1156 This functionality (derived from L<Object::Pluggable>) provides
1157 fine-grained control over event lifetime.
1158  
1159 Higher-level layers (see L<MooX::Role::POE::Emitter> for an example) can check
1160 for an C<EAT_ALL> return value from L</_pluggable_process> to determine
1161 whether to continue operating on a particular event (re-dispatch elsewhere,
1162 for example).
1163  
1164 Plugins can use C<EAT_CLIENT> to indicate that an event should
1165 be eaten after plugin processing is complete, C<EAT_PLUGIN> to stop plugin
1166 processing, and C<EAT_ALL> to indicate that the event should not be dispatched
1167 further.
1168  
1169 =head2 Plugin Management Methods
1170  
1171 These plugin pipeline management methods will set C<$@>, warn via L<Carp>, and
1172 return an empty list on error (unless otherwise noted). See L</plugin_error>
1173 regarding errors raised during plugin registration and dispatch.
1174  
1175 =head3 plugin_add
1176  
1177 $self->plugin_add( $alias, $plugin_obj, @args );
1178  
1179 Add a plugin object to the pipeline.
1180  
1181 Returns the same values as L</plugin_pipe_push>.
1182  
1183 =head3 plugin_del
1184  
1185 $self->plugin_del( $alias_or_plugin_obj, @args );
1186  
1187 Remove a plugin from the pipeline.
1188  
1189 Takes either a plugin alias or object. Returns the removed plugin object.
1190  
1191 =head3 plugin_get
1192  
1193 my $plug_obj = $self->plugin_get( $alias );
1194 my ($plug_obj, $plug_alias) = $self->plugin_get( $alias_or_plugin_obj );
1195  
1196 In scalar context, returns the plugin object belonging to the specified
1197 alias.
1198  
1199 In list context, returns the object and alias, respectively.
1200  
1201 =head3 plugin_alias_list
1202  
1203 my @loaded = $self->plugin_alias_list;
1204  
1205 Returns the list of loaded plugin aliases.
1206  
1207 As of version C<1.002>, the list is ordered to match actual plugin dispatch
1208 order. In prior versions, the list is unordered.
1209  
1210 =head3 plugin_replace
1211  
1212 $self->plugin_replace(
1213 old => $alias_or_plugin_obj,
1214 alias => $new_alias,
1215 plugin => $new_plugin_obj,
1216 # Optional:
1217 register_args => [ ],
1218 unregister_args => [ ],
1219 );
1220  
1221 Replace an existing plugin object with a new one.
1222  
1223 Returns the old (removed) plugin object.
1224  
1225 =head2 Pipeline Methods
1226  
1227 =head3 plugin_pipe_push
1228  
1229 $self->plugin_pipe_push( $alias, $plugin_obj, @args );
1230  
1231 Add a plugin to the end of the pipeline; typically one would call
1232 L</plugin_add> rather than using this method directly.
1233  
1234 =head3 plugin_pipe_pop
1235  
1236 my $plug = $self->plugin_pipe_pop( @unregister_args );
1237  
1238 Pop the last plugin off the pipeline, passing any specified arguments to
1239 L</plugin_unregister>.
1240  
1241 In scalar context, returns the plugin object that was removed.
1242  
1243 In list context, returns the plugin object and alias, respectively.
1244  
1245 =head3 plugin_pipe_unshift
1246  
1247 $self->plugin_pipe_unshift( $alias, $plugin_obj, @args );
1248  
1249 Add a plugin to the beginning of the pipeline.
1250  
1251 Returns the total number of loaded plugins (or an empty list on failure).
1252  
1253 =head3 plugin_pipe_shift
1254  
1255 $self->plugin_pipe_shift( @unregister_args );
1256  
1257 Shift the first plugin off the pipeline, passing any specified args to
1258 L</plugin_unregister>.
1259  
1260 In scalar context, returns the plugin object that was removed.
1261  
1262 In list context, returns the plugin object and alias, respectively.
1263  
1264 =head3 plugin_pipe_get_index
1265  
1266 my $idx = $self->plugin_pipe_get_index( $alias_or_plugin_obj );
1267 if ($idx < 0) {
1268 # Plugin doesn't exist
1269 }
1270  
1271 Returns the position of the specified plugin in the pipeline.
1272  
1273 Returns -1 if the plugin does not exist.
1274  
1275 =head3 plugin_pipe_insert_after
1276  
1277 $self->plugin_pipe_insert_after(
1278 after => $alias_or_plugin_obj,
1279 alias => $new_alias,
1280 plugin => $new_plugin_obj,
1281 # Optional:
1282 register_args => [ ],
1283 );
1284  
1285 Add a plugin to the pipeline after the specified previously-existing alias
1286 or plugin object. Returns boolean true on success.
1287  
1288 =head3 plugin_pipe_insert_before
1289  
1290 $self->plugin_pipe_insert_before(
1291 before => $alias_or_plugin_obj,
1292 alias => $new_alias,
1293 plugin => $new_plugin_obj,
1294 # Optional:
1295 register_args => [ ],
1296 );
1297  
1298 Similar to L</plugin_pipe_insert_after>, but insert before the specified
1299 previously-existing plugin, not after.
1300  
1301 =head3 plugin_pipe_bump_up
1302  
1303 $self->plugin_pipe_bump_up( $alias_or_plugin_obj, $count );
1304  
1305 Move the specified plugin 'up' C<$count> positions in the pipeline.
1306  
1307 Returns -1 if the plugin cannot be bumped up any farther.
1308  
1309 =head3 plugin_pipe_bump_down
1310  
1311 $self->plugin_pipe_bump_down( $alias_or_plugin_obj, $count );
1312  
1313 Move the specified plugin 'down' C<$count> positions in the pipeline.
1314  
1315 Returns -1 if the plugin cannot be bumped down any farther.
1316  
1317 =head2 Internal Events
1318  
1319 These events are dispatched to L</_pluggable_event> prefixed with our
1320 pluggable event prefix; see L</_pluggable_init>.
1321  
1322 =head3 plugin_error
1323  
1324 Issued via L</_pluggable_event> when an error occurs.
1325  
1326 The arguments are, respectively: the error string, the offending object,
1327 and a string describing the offending object ('self' or 'plugin' with name
1328 appended).
1329  
1330 =head3 plugin_added
1331  
1332 Issued via L</_pluggable_event> when a new plugin is registered.
1333  
1334 Arguments are the new plugin alias and object, respectively.
1335  
1336 =head3 plugin_removed
1337  
1338 Issued via L</_pluggable_event> when a plugin is unregistered.
1339  
1340 Arguments are the old plugin alias and object, respectively.
1341  
1342 =head2 Performance
1343  
1344 My motivation for writing this role was two-fold; I wanted
1345 L<Object::Pluggable> behavior but without screwing up my class inheritance,
1346 and I needed a little bit more juice out of the pipeline dispatch process for
1347 a fast-paced daemon.
1348  
1349 Dispatcher performance has been profiled and micro-optimized, but I'm most
1350 certainly open to further ideas ;-)
1351  
1352 Some L<Benchmark> runs. 30000 L</_pluggable_process> calls with 20 loaded
1353 plugins dispatching one argument to one handler that does nothing except
1354 return EAT_NONE:
1355  
1356 Rate object-pluggable moox-role-pluggable
1357 object-pluggable 6173/s -- -38%
1358 moox-role-pluggable 9967/s 61%
1359  
1360 Rate object-pluggable moox-role-pluggable
1361 object-pluggable 6224/s -- -38%
1362 moox-role-pluggable 10000/s 61% --
1363  
1364 Rate object-pluggable moox-role-pluggable
1365 object-pluggable 6383/s -- -35%
1366 moox-role-pluggable 9868/s 55%
1367  
1368 (Benchmark script is available in the C<bench/> directory of the upstream
1369 repository; see L<https://github.com/avenj/moox-role-pluggable>)
1370  
1371 =head1 AUTHOR
1372  
1373 Jon Portnoy <avenj@cobaltirc.org>
1374  
1375 Written from the ground up, but conceptually derived entirely from
1376 L<Object::Pluggable> (c) Chris Williams, Apocalypse, Hinrik Orn Sigurosson and
1377 Jeff Pinyan.
1378  
1379 Licensed under the same terms as Perl 5; please see the license that came with
1380 your Perl distribution for details.
1381  
1382 =cut
↑ Summary Pluggable/Constants.pm »