blib/lib/POE/Session/MultiDispatch.pm

filter: Statementstmt 15.4% 23 / 149 Branchbran 2.8% 2 / 70 Conditioncond 10.5% 2 / 19 MC/DCmcdc 8.3% 1 / 12 Subroutinesub 31.2% 5 / 16 Podpod 80.0% 8 / 10 totaltotal 14.8% 41 / 276 CC 45 SCAR 43.5
CC
45
Cov
11%
register_state
240.0
up
42.0
down
42.0
CRAP 77.7
↑ Summary
1 =head1 NAME
2  
3 POE::Session::MultiDispatch - Callback dispatch for session events.
4  
5 =head1 SYNOPSIS
6  
7 use POE qw[Session::MultiDispatch];
8
9 my $session = POE::Session::MultiDispatch->create(
10 inline_states => { _start => \&_start },
11 package_states => [ ... ],
12 object_states => [ ... ],
13 );
14  
15 sub _start {
16 # Execute Foo::Bar's _start state first.
17 $_[SESSION]->first( _start => 'Foo::Bar' );
18 $_[SESSION]->stop;
19 }
20  
21 # run Foo::Bar's done state last.
22 $session->last( done => 'Foo::Bar' );
23  
24 $poe_kernel->run;
25 exit 0;
26  
27 =head1 DESCRIPTION
28  
29 POE::Session::MultiDispatch is a drop in replacement for
30 L<POE::Session|POE::Session> that adds callback dispatch functionality
31 to POE sessions. Each event may have multiple handlers associated with
32 it. Fine control over the order of execution is available using helper
33 methods that extend the interface of a POE::Session.
34  
35 POE::Session::MultiDispatch uses POE::Session as a base class. When
36 multiple callbacks are registered for an event, only the last callback
37 survives, all the others are clobbered. POE::Session::MultiDispatch is
38 much nicer to your registered callbacks, it keeps them all in the order
39 they were defined. When an event is triggered, all the callbacks are
40 then executed in that same order (unless you muck around with said order).
41  
42 Just what is the order? Last I checked it is C<inline_states>,
43 C<package_states>, and C<object_states>. As you can probably tell, that
44 order is by no means documented (here or anywhere else) as something that
45 is stead fast and solid. You should be careful and know what you're doing
46 if you intend to care too much about the order. Having said that, my
47 guess is that it won't change. But don't take my word for it.
48  
49 All the real heavy lifting is still done in POE::Session. The interface
50 is exactly the same with the exception of the following additions.
51 Please read the POE::Session documentation for details on working with
52 POE sessions.
53  
54 =cut
55  
56 package POE::Session::MultiDispatch;
57 #
58 # $Revision: 1.3 $
59 # $Id: MultiDispatch.pm,v 1.3 2003/02/01 21:53:45 cwest Exp $
60 #
61 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
62 1 $^W = 1; # At least for development.
63  
64 1 ▶use vars qw($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
65 1 $VERSION = (qw$Revision: 1.3 $)[1];
66  
67 1 ▶use Carp qw(carp croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
68 1 ▶use base qw[POE::Session];
Subroutine BEGIN: called CC=1 SCAR=0.0
69  
70  
71 =head2 Methods
72  
73 These methods have been added to POE::Sessions's interface. They
74 can be accessed from an event by using the session object stored
75 in C<$_[SESSION]>. Alternativley, you can use the object returned
76 when calling C<create()> to call these methods.
77  
78 =over 4
79  
80 =item stop
81  
82 C<stop()> tells the session dispatcher to stop processing callbacks
83 for this event, after the current one is finished processing.
84  
85 =cut
86  
87 0 ▶sub stop {
Subroutine stop: not called CC=1 SCAR=6.9
Pod documented
88 0 my ($self) = @_;
89
90 0 $self->[POE::Session::SE_OPTIONS]->{stop} = 1;
91 }
92  
93 =pod
94  
95 =item go
96  
97 C<go()> tells the session dispatcher to continue processing callbacks
98 for this event.
99  
100 =cut
101  
102 0 ▶sub go {
Subroutine go: not called CC=1 SCAR=6.9
Pod documented
103 0 my ($self) = @_;
104  
105 0 $self->[POE::Session::SE_OPTIONS]->{stop} = 0;
106 }
107  
108 =pod
109  
110 =item status
111  
112 C<status()> returns the current status of the event. It returns true
113 if the callback stack is set to be stopped, false if we're still going
114 through.
115  
116 =cut
117  
118 0 ▶sub status {
Subroutine status: not called CC=2 SCAR=17.9
Pod documented
119 0 my ($self) = @_;
120  
121 0 ▶ $self->[POE::Session::SE_OPTIONS]->{stop} || 0;
Branch: 1 branch
BranchTrueFalseTotal
$self->[1]{"stop"} or 0 0 0 0
122 }
123  
124 =pod
125  
126 =item up EVENT, STATE, DIFFERENCE
127  
128 C<up()> moves a state up in the calling order for an event. The
129 difference is how far up to move it, the default is 1. A state is
130 given by name.
131  
132 Inline states don't usually have a name, so one is assigned. Names
133 follow the convention 'inline_state_N' where 'N' is a number, zero
134 indexed. Package states are named using the package name. Object
135 states are named using the object name.
136  
137 =cut
138  
139 0 ▶sub up {
Subroutine up: not called CC=6 SCAR=37.4
Pod documented
140 0 my ($self, $event, $state, $difference) = @_;
141 0 ▶ croak "No event name passed to up()" unless $event;
Branch: 1 branch
BranchTrueFalseTotal
unless $event 0 0 0
142 0 ▶ croak "No state name passed to up()" unless $state;
Branch: 1 branch
BranchTrueFalseTotal
unless $state 0 0 0
143 0 ▶ $difference ||= 1;
Condition0%0/2
$difference ||= 1
l!l
00
MC/DC0%0/1
$difference ||= 1
$difference
Truth table0%0/2
A
A= $difference
Aresult
11
00
144 0 ▶ $state = 'inline_state_0' if $state eq 'inline_state';
Branch: 1 branch
BranchTrueFalseTotal
if $state eq "inline_state" 0 0 0
145 0 my $location = $self->_get_event_location( $event );
146  
147 0 my $handlers = $location->{$event};
148  
149 0 my $pos = $self->state_location( $state, $handlers );
150 0 my $newpos = $pos - $difference;
151 0 ▶ $newpos = 0 if $newpos < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $newpos < 0 0 0 0
152
153 0 @{$handlers}[$pos, $newpos] = @{$handlers}[$newpos,$pos];
154
155 0 $location->{$event} = $handlers;
156
157 0 return 1;
158 }
159  
160 =pod
161  
162 =item down EVENT, STATE, DIFFERENCE
163  
164 C<down()> moves a state down in the calling order for an event. The
165 difference is how far down to move it, the default is 1. A state is
166 given by name.
167  
168 =cut
169  
170 0 ▶sub down {
Subroutine down: not called CC=6 SCAR=37.4
Pod documented
171 0 my ($self, $event, $state, $difference) = @_;
172 0 ▶ croak "No event name passed to down()" unless $event;
Branch: 1 branch
BranchTrueFalseTotal
unless $event 0 0 0
173 0 ▶ croak "No state name passed to down()" unless $state;
Branch: 1 branch
BranchTrueFalseTotal
unless $state 0 0 0
174 0 ▶ $difference ||= 1;
Condition0%0/2
$difference ||= 1
l!l
00
MC/DC0%0/1
$difference ||= 1
$difference
Truth table0%0/2
A
A= $difference
Aresult
11
00
175 0 ▶ $state = 'inline_state_0' if $state eq 'inline_state';
Branch: 1 branch
BranchTrueFalseTotal
if $state eq "inline_state" 0 0 0
176 0 my $location = $self->_get_event_location( $event );
177  
178 0 my $handlers = $location->{$event};
179  
180 0 my $pos = $self->state_location( $state, $handlers );
181 0 my $newpos = $pos + $difference;
182 0 ▶ $newpos = $#{$handlers} if $newpos > $#{$handlers};
Branch: 1 branch
BranchTrueFalseTotal
if $newpos > $#{$handlers;} 0 0 0
183
184 0 @{$handlers}[$pos, $newpos] = @{$handlers}[$newpos,$pos];
185
186 0 $location->{$event} = $handlers;
187
188 0 return 1;
189 }
190  
191 =pod
192  
193 =item first EVENT, STATE
194  
195 C<first()> moves a state to the beginning of the callback stack.
196  
197 =cut
198  
199 0 ▶sub first {
Subroutine first: not called CC=4 SCAR=30.0
Pod documented
200 0 my ($self, $event, $state) = @_;
201 0 ▶ croak "No event name passed to up()" unless $event;
Branch: 1 branch
BranchTrueFalseTotal
unless $event 0 0 0
202 0 ▶ croak "No state name passed to up()" unless $state;
Branch: 1 branch
BranchTrueFalseTotal
unless $state 0 0 0
203  
204 0 ▶ $state = 'inline_state_0' if $state eq 'inline_state';
Branch: 1 branch
BranchTrueFalseTotal
if $state eq "inline_state" 0 0 0
205 0 my $location = $self->_get_event_location( $event );
206  
207 0 my $handlers = $location->{$event};
208  
209 0 my $pos = $self->state_location( $state, $handlers );
210
211 0 @{$handlers}[$pos, 0] = @{$handlers}[0,$pos];
212
213 0 $location->{$event} = $handlers;
214
215 0 return 1;
216 }
217  
218 =item last EVENT, STATE
219  
220 C<last()> moves a state to the end of the callback stack.
221  
222 =cut
223  
224 0 ▶sub last {
Subroutine last: not called CC=4 SCAR=30.0
Pod documented
225 0 my ($self, $event, $state) = @_;
226 0 ▶ croak "No event name passed to up()" unless $event;
Branch: 1 branch
BranchTrueFalseTotal
unless $event 0 0 0
227 0 ▶ croak "No state name passed to up()" unless $state;
Branch: 1 branch
BranchTrueFalseTotal
unless $state 0 0 0
228  
229 0 ▶ $state = 'inline_state_0' if $state eq 'inline_state';
Branch: 1 branch
BranchTrueFalseTotal
if $state eq "inline_state" 0 0 0
230 0 my $location = $self->_get_event_location( $event );
231  
232 0 my $handlers = $location->{$event};
233  
234 0 my $pos = $self->state_location( $state, $handlers );
235
236 0 @{$handlers}[$pos, $#{$handlers}] = @{$handlers}[$#{$handlers}, $pos];
237
238 0 $location->{$event} = $handlers;
239
240 0 return 1;
241 }
242  
243 =item swap EVENT, STATE1, STATE2
244  
245 C<swap()> well... swaps the position of two states.
246  
247 =cut
248  
249 0 ▶sub swap {
Subroutine swap: not called CC=4 SCAR=30.0
Pod documented
250 0 my ($self, $event, $state1, $state2) = @_;
251 0 ▶ croak "No event name passed to down()" unless $event;
Branch: 1 branch
BranchTrueFalseTotal
unless $event 0 0 0
252 0 ▶ croak "Not enough states passed to down()" unless $state1 && $state2;
Branch: 1 branch
BranchTrueFalseTotal
unless $state1 and $state2 0 0 0
Condition0%0/3
$state1 and $state2
!ll&&!rl&&r
000
MC/DC0%0/2
$state1 and $state2
$state1 $state2
Truth table0%0/3
A and B
A= $state1B= $state2
ABresult
0X0
100
111
253  
254 0 my $location = $self->_get_event_location( $event );
255  
256 0 my $handlers = $location->{$event};
257  
258 0 my $pos1 = $self->state_location( $state1, $handlers );
259 0 my $pos2 = $self->state_location( $state2, $handlers );
260  
261 0 @{$handlers}[$pos1, $pos2] = @{$handlers}[$pos2,$pos1];
262
263 0 $location->{$event} = $handlers;
264
265 0 return 1;
266 }
267  
268 =pod
269  
270 =back
271  
272 =cut
273  
274 # internal stuff
275 0 ▶sub _get_event_location {
Subroutine _get_event_location: not called CC=2 SCAR=17.9
276 0 my ($self, $event) = @_;
277  
278 return
279 exists $self->[POE::Session::SE_OPTIONS]->{+__PACKAGE__}->{$event} ?
280 0 ▶ $self->[POE::Session::SE_OPTIONS]->{+__PACKAGE__} :
Branch: 1 branch
BranchTrueFalseTotal
exists $self->[1]{'POE::Session::MultiDispatch'}{$event} ? : 0 0 0
281 $self->[POE::Session::SE_STATES];
282 }
283  
284 0 ▶sub state_location {
Subroutine state_location: not called CC=6 SCAR=37.4
Pod undocumented
285 0 my ($self, $state, $handlers) = @_;
286 0 my $pos = undef;
287 0 my $inline = 0;
288 0 my $count = 0;
289 0 foreach (@$handlers) {
290 0 ▶ if ( ref($_) eq 'CODE' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_ eq 'CODE') { } 0 0 0
291 0 my $name = "inline_state_$inline";
292 0 ▶ if ( $name eq $state ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq $state) { } 0 0 0
293 0 $pos = $count;
294 0 last;
295 } else {
296 0 $inline++;
297 }
298 } else {
299 0 my ($name, $code) = @$_;
300 0 ▶ if ( $name eq $state || $name->isa( $state ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq $state or $name->isa($state)) 0 0 0
Condition0%0/3
$name eq $state or $name->isa($state)
l!l&&r!l&&!r
000
MC/DC0%0/2
$name eq $state or $name->isa($state)
$name eq $state $name->isa($state)
Truth table0%0/3
A or B
A= $name eq $stateB= $name->isa($state)
ABresult
1X1
011
000
301 0 $pos = $count;
302 0 last;
303 }
304 }
305 0 $count++;
306 }
307 0 return $pos;
308 }
309  
310 2 ▶sub _invoke_state {
Subroutine _invoke_state: called CC=5 SCAR=18.9
311 2 my ($self, $source_session, $state, $etc, $file, $line) = @_;
312  
313 my $handlers = $self->[POE::Session::SE_STATES]->{$state}
314 2 ▶ || $self->[POE::Session::SE_STATES]->{POE::Session::EN_DEFAULT};
Condition66%2/3
$self->[2]{$state} || $self->[2]{'_default'}
l!l&&r!l&&!r
101
MC/DC50%1/2
$self->[2]{$state} || $self->[2]{'_default'}
$self->[2]{$state} $self->[2]{'_default'}
Truth table66%2/3
A || B
A= $self->[2]{$state}B= $self->[2]{'_default'}
ABresult
1X1
011
000
315 2 $self->[POE::Session::SE_OPTIONS]->{+__PACKAGE__}->{$state} = $handlers;
316  
317 2 ▶ if ( $handlers ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($handlers) { } 1 1 2
318 1 foreach (@$handlers) {
319 0 ▶ if ( $self->status == 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->status == 1) 0 0 0
320 0 $self->go;
321 0 last;
322 }
323 0 $self->[POE::Session::SE_STATES]->{$state} = $_;
324 0 $self->SUPER::_invoke_state(@_[1..$#_]);
325 }
326 } else {
327 1 $self->SUPER::_invoke_state(@_[1..$#_]);
328 }
329  
330 $self->[POE::Session::SE_STATES]->{$state}
331 1 = delete $self->[POE::Session::SE_OPTIONS]->{+__PACKAGE__}->{$state};
332
333 1 return undef;
334 }
335  
336 0 ▶sub register_state {
Subroutine register_state: not called CC=15 SCAR=54.8
Pod undocumented
337 0 my ($self, $name, $handler, $method) = @_;
338 0 ▶ $method = $name unless defined $method;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $method 0 0 0
339  
340 0 ▶ if ($name eq POE::Session::EN_SIGNAL) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "_signal") 0 0 0
341  
342 # Report the problem outside POE.
343 0 my $caller_level = 0;
344 0 local $Carp::CarpLevel = 1;
345 0 ▶ while ( (caller $caller_level)[0] =~ /^POE::/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ((caller $caller_level)[0] =~ /^POE::/) 0 0 0
346 0 $caller_level++;
347 0 $Carp::CarpLevel++;
348 }
349  
350 0 carp( "The _signal event is deprecated. ",
351 "Please use sig() to register a signal handler"
352 );
353 }
354  
355 # There is a handler, so add the state to the event.
356  
357 0 ▶ if ($handler) {
Branch: 1 branch
BranchTrueFalseTotal
if ($handler) { } 0 0 0
358  
359 # Coderef handlers are inline states.
360  
361 0 ▶ if (ref($handler) eq 'CODE') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $handler eq 'CODE') { } 0 0 0
elsif ($handler->can($method)) { } 0 0 0
362 carp( "adding state($name) for session(",
363 $POE::Kernel::poe_kernel->ID_session_to_id($self), ")"
364 )
365 0 ▶ if ( $self->[POE::Session::SE_OPTIONS]->{+POE::Session::OPT_DEBUG} );
Branch: 1 branch
BranchTrueFalseTotal
if $self->[1]{"debug"} 0 0 0
366 0 ▶ if ( ref($self->[POE::Session::SE_STATES]->{$name}) eq 'ARRAY' || ! $self->[POE::Session::SE_STATES]->{$name} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self->[2]{$name} eq 'ARRAY' or not $self->[2]{$name}) { } 0 0 0
Condition0%0/3
ref $self->[2]{$name} eq "ARRAY" or not $self->[2]{$name}
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $self->[2]{$name} eq "ARRAY" or not $self->[2]{$name}
ref $self->[2]{$name} eq "ARRAY" not $self->[2]{$name}
Truth table0%0/3
A or not(B)
A= ref $self->[2]{$name} eq "ARRAY"B= not $self->[2]{$name}
ABresult
1X1
011
000
367 0 push @{ $self->[POE::Session::SE_STATES]->{$name} }, $handler;
368 } else {
369 # ReadWrite wheel seems to be determined to do this, plus,
370 # it does make sense.
371 0 $self->[POE::Session::SE_STATES]->{$name} = $handler;
372 }
373 }
374  
375 # Non-coderef handlers may be package or object states. See if
376 # the method belongs to the handler.
377  
378 elsif ($handler->can($method)) {
379 carp( "adding state($name) for session(",
380 $POE::Kernel::poe_kernel->ID_session_to_id($self), ")"
381 )
382 0 ▶ if ( $self->[POE::Session::SE_OPTIONS]->{+POE::Session::OPT_DEBUG} );
Branch: 1 branch
BranchTrueFalseTotal
if $self->[1]{"debug"} 0 0 0
383 0 push @{ $self->[POE::Session::SE_STATES]->{$name} }, [ $handler, $method ];
384 }
385  
386 # Something's wrong. This code also seems wrong, since
387 # ref($handler) can't be 'CODE'.
388  
389 else {
390 0 ▶ if ( (ref($handler) eq 'CODE') and
Branch: 1 branch
BranchTrueFalseTotal
if (ref $handler eq 'CODE' and $self->[1]{'trace'}) { } 0 0 0
Condition0%0/3
ref $handler eq "CODE" and $self->[1]{"trace"}
!ll&&!rl&&r
000
MC/DC0%0/2
ref $handler eq "CODE" and $self->[1]{"trace"}
ref $handler eq "CODE" $self->[1]{"trace"}
Truth table0%0/3
A and B
A= ref $handler eq "CODE"B= $self->[1]{"trace"}
ABresult
0X0
100
111
391 $self->[POE::Session::SE_OPTIONS]->{+POE::Session::OPT_TRACE}
392 ) {
393 0 carp( $POE::Kernel::poe_kernel->ID_session_to_id($self),
394 " : state($name) is not a proper ref - not registered"
395 )
396 }
397 else {
398 0 ▶ unless ($handler->can($method)) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($handler->can($method)) 0 0 0
399 0 ▶ if (length ref($handler)) {
Branch: 1 branch
BranchTrueFalseTotal
if (length ref $handler) { } 0 0 0
400 0 croak "object $handler does not have a '$method' method"
401 }
402 else {
403 0 croak "package $handler does not have a '$method' method";
404 }
405 }
406 }
407 }
408 }
409  
410 # No handler. Delete the state!
411  
412 else {
413 0 delete $self->[POE::Session::SE_STATES]->{$name};
414 }
415 }
416  
417 1 1;
418  
419 __END__
↑ Summary