blib/lib/POE/Session.pm

filter: Statementstmt 84.5% 213 / 252 Branchbran 62.5% 85 / 136 Conditioncond 41.6% 5 / 12 MC/DCmcdc 12.5% 1 / 8 Subroutinesub 87.1% 27 / 31 Podpod 100% 8 / 8 totaltotal 75.8% 339 / 447 CC 77 SCAR 29.9
CC
77
Cov
76%
_register_state
55.8
create
33.1
_invoke_state
9.1
CRAP 19.8
« blib/lib/POE/Loop/IO_Poll.pm ↑ Summary blib/lib/POE/Resource/FileHandles.pm »
1 package POE::Session;
2  
3 194 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 194 ▶use vars qw($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 194 $VERSION = '1.370'; # NOTE - Should be #.### (three decimal places)
7  
8 194 ▶use Carp qw(carp croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 194 ▶use Errno;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 sub SE_NAMESPACE () { 0 }
12 sub SE_OPTIONS () { 1 }
13 sub SE_STATES () { 2 }
14 sub SE_ID () { 3 }
15  
16 sub CREATE_ARGS () { 'args' }
17 sub CREATE_OPTIONS () { 'options' }
18 sub CREATE_INLINES () { 'inline_states' }
19 sub CREATE_PACKAGES () { 'package_states' }
20 sub CREATE_OBJECTS () { 'object_states' }
21 sub CREATE_HEAP () { 'heap' }
22  
23 sub OPT_TRACE () { 'trace' }
24 sub OPT_DEBUG () { 'debug' }
25 sub OPT_DEFAULT () { 'default' }
26  
27 sub EN_START () { '_start' }
28 sub EN_DEFAULT () { '_default' }
29 sub EN_SIGNAL () { '_signal' }
30  
31 #------------------------------------------------------------------------------
32 # Debugging flags for subsystems. They're done as double evals here
33 # so that someone may define them before using POE::Session (or POE),
34 # and the pre-defined value will take precedence over the defaults
35 # here.
36  
37 # Shorthand for defining an assert constant.
38  
39 194 ▶sub _define_assert {
Subroutine _define_assert: called CC=6 SCAR=20.5
40 194 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
41 194 foreach my $name (@_) {
42  
43 194 local $^W = 0;
44  
45 194 ▶ next if defined *{"ASSERT_$name"}{CODE};
Branch: 1 branch
BranchTrueFalseTotal
if defined *{"ASSERT_$name";}{"CODE"} 0 194 194
46 194 ▶ if (defined *{"POE::Kernel::ASSERT_$name"}{CODE}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined *{"POE::Kernel::ASSERT_$name";}{'CODE'}) { } 0 194 194
47 eval(
48 "sub ASSERT_$name () { " .
49 0 *{"POE::Kernel::ASSERT_$name"}{CODE}->() .
50 "}"
51 );
52 0 ▶ die if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
53 }
54 else {
55 194 eval "sub ASSERT_$name () { ASSERT_DEFAULT }";
56 194 ▶ die if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 194 194
57 }
58 }
59 }
60  
61 # Shorthand for defining a trace constant.
62 194 ▶sub _define_trace {
Subroutine _define_trace: called CC=6 SCAR=20.5
63 194 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 194 local $^W = 0;
66  
67 194 foreach my $name (@_) {
68 194 ▶ next if defined *{"TRACE_$name"}{CODE};
Branch: 1 branch
BranchTrueFalseTotal
if defined *{"TRACE_$name";}{"CODE"} 0 194 194
69 194 ▶ if (defined *{"POE::Kernel::TRACE_$name"}{CODE}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined *{"POE::Kernel::TRACE_$name";}{'CODE'}) { } 0 194 194
70 eval(
71 "sub TRACE_$name () { " .
72 0 *{"POE::Kernel::TRACE_$name"}{CODE}->() .
73 "}"
74 );
75 0 ▶ die if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
76 }
77 else {
78 194 eval "sub TRACE_$name () { TRACE_DEFAULT }";
79 194 ▶ die if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 194 194
80 }
81 }
82 }
83  
84 194 ▶BEGIN {
Subroutine BEGIN: called CC=5 SCAR=17.8
85  
86 # ASSERT_DEFAULT changes the default value for other ASSERT_*
87 # constants. It inherits POE::Kernel's ASSERT_DEFAULT value, if
88 # it's present.
89  
90 194 ▶ unless (defined &ASSERT_DEFAULT) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined &POE::Session::ASSERT_DEFAULT) 194 0 194
91 194 ▶ if (defined &POE::Kernel::ASSERT_DEFAULT) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined &POE::Kernel::ASSERT_DEFAULT) { } 194 0 194
92 194 eval( "sub ASSERT_DEFAULT () { " . &POE::Kernel::ASSERT_DEFAULT . " }" );
93 }
94 else {
95 0 eval 'sub ASSERT_DEFAULT () { 0 }';
96 }
97 };
98  
99 # TRACE_DEFAULT changes the default value for other TRACE_*
100 # constants. It inherits POE::Kernel's TRACE_DEFAULT value, if
101 # it's present.
102  
103 194 ▶ unless (defined &TRACE_DEFAULT) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined &POE::Session::TRACE_DEFAULT) 194 0 194
104 194 ▶ if (defined &POE::Kernel::TRACE_DEFAULT) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined &POE::Kernel::TRACE_DEFAULT) { } 194 0 194
105 194 eval( "sub TRACE_DEFAULT () { " . &POE::Kernel::TRACE_DEFAULT . " }" );
106 }
107 else {
108 0 eval 'sub TRACE_DEFAULT () { 0 }';
109 }
110 };
111  
112 194 _define_assert("STATES");
113 194 _define_trace("DESTROY");
114 }
115  
116 #------------------------------------------------------------------------------
117 # Export constants into calling packages. This is evil; perhaps
118 # EXPORT_OK instead? The parameters NFA has in common with SESSION
119 # (and other sessions) must be kept at the same offsets as each-other.
120  
121 sub OBJECT () { 0 } # TODO - deprecate and replace with SELF
122 sub SESSION () { 1 }
123 sub KERNEL () { 2 }
124 sub HEAP () { 3 }
125 sub STATE () { 4 } # TODO - deprecate and replace with EVENT
126 sub SENDER () { 5 }
127 # NFA keeps its state in 6. unused in session so that args match up.
128 sub CALLER_FILE () { 7 }
129 sub CALLER_LINE () { 8 }
130 sub CALLER_STATE () { 9 } # TODO - deprecate and replace with CALLER_EVENT
131 sub ARG0 () { 10 }
132 sub ARG1 () { 11 }
133 sub ARG2 () { 12 }
134 sub ARG3 () { 13 }
135 sub ARG4 () { 14 }
136 sub ARG5 () { 15 }
137 sub ARG6 () { 16 }
138 sub ARG7 () { 17 }
139 sub ARG8 () { 18 }
140 sub ARG9 () { 19 }
141  
142 411 ▶sub import {
Subroutine import: called CC=1 SCAR=0.0
143 411 my $package = caller();
144 194 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
145 411 *{ $package . '::OBJECT' } = \&OBJECT;
146 411 *{ $package . '::SESSION' } = \&SESSION;
147 411 *{ $package . '::KERNEL' } = \&KERNEL;
148 411 *{ $package . '::HEAP' } = \&HEAP;
149 411 *{ $package . '::STATE' } = \&STATE;
150 411 *{ $package . '::SENDER' } = \&SENDER;
151 411 *{ $package . '::ARG0' } = \&ARG0;
152 411 *{ $package . '::ARG1' } = \&ARG1;
153 411 *{ $package . '::ARG2' } = \&ARG2;
154 411 *{ $package . '::ARG3' } = \&ARG3;
155 411 *{ $package . '::ARG4' } = \&ARG4;
156 411 *{ $package . '::ARG5' } = \&ARG5;
157 411 *{ $package . '::ARG6' } = \&ARG6;
158 411 *{ $package . '::ARG7' } = \&ARG7;
159 411 *{ $package . '::ARG8' } = \&ARG8;
160 411 *{ $package . '::ARG9' } = \&ARG9;
161 411 *{ $package . '::CALLER_FILE' } = \&CALLER_FILE;
162 411 *{ $package . '::CALLER_LINE' } = \&CALLER_LINE;
163 411 *{ $package . '::CALLER_STATE' } = \&CALLER_STATE;
164 }
165  
166 828 ▶sub instantiate {
Subroutine instantiate: called CC=2 SCAR=7.0
Pod documented
167 828 my $type = shift;
168  
169 828 ▶ croak "$type requires a working Kernel"
Branch: 1 branch
BranchTrueFalseTotal
unless defined $POE::Kernel::poe_kernel 0 828 828
170 unless defined $POE::Kernel::poe_kernel;
171  
172 828 my $self =
173 bless [ { }, # SE_NAMESPACE
174 { }, # SE_OPTIONS
175 { }, # SE_STATES
176 ], $type;
177  
178 828 if (ASSERT_STATES) {
179 $self->[SE_OPTIONS]->{+OPT_DEFAULT} = 1;
180 }
181  
182 828 return $self;
183 }
184  
185 828 ▶sub try_alloc {
Subroutine try_alloc: called CC=2 SCAR=7.9
Pod documented
186 1492 my ($self, @args) = @_;
187 # Verify that the session has a special start state, otherwise how
188 # do we know what to do? Don't even bother registering the session
189 # if the start state doesn't exist.
190  
191 828 ▶ if (exists $self->[SE_STATES]->{+EN_START}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->[2]{'_start'}) { } 828 0 828
192 828 $POE::Kernel::poe_kernel->session_alloc($self, @args);
193 }
194 else {
195 0 carp( "discarding session ",
196 $POE::Kernel::poe_kernel->ID_session_to_id($self),
197 " - no '_start' state"
198 );
199 0 $self = undef;
200 }
201  
202 763 $self;
203 }
204  
205 #------------------------------------------------------------------------------
206 # New style constructor. This uses less DWIM and more DWIS, and it's
207 # more comfortable for some folks; especially the ones who don't quite
208 # know WTM.
209  
210 830 ▶sub create {
Subroutine create: called CC=29 SCAR=35.0
Pod documented
211 830 my ($type, @params) = @_;
212 830 my @args;
213  
214 # We treat the parameter list strictly as a hash. Rather than dying
215 # here with a Perl error, we'll catch it and blame it on the user.
216  
217 830 ▶ if (@params & 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (@params & 1) 2 828 830
218 2 croak "odd number of events/handlers (missing one or the other?)";
219 }
220 828 my %params = @params;
221  
222 828 my $self = $type->instantiate(\%params);
223  
224 # Process _start arguments. We try to do the right things with what
225 # we're given. If the arguments are a list reference, map its items
226 # to ARG0..ARGn; otherwise make whatever the heck it is be ARG0.
227  
228 828 ▶ if (exists $params{+CREATE_ARGS}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $params{"args"}) 370 458 828
229 370 ▶ if (ref($params{+CREATE_ARGS}) eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $params{'args'} eq 'ARRAY') { } 370 0 370
230 370 push @args, @{$params{+CREATE_ARGS}};
231 }
232 else {
233 0 push @args, $params{+CREATE_ARGS};
234 }
235 370 delete $params{+CREATE_ARGS};
236 }
237  
238 # Process session options here. Several options may be set.
239  
240 828 ▶ if (exists $params{+CREATE_OPTIONS}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $params{"options"}) 4 824 828
241 4 ▶ if (ref($params{+CREATE_OPTIONS}) eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $params{'options'} eq 'HASH') { } 4 0 4
242 4 $self->[SE_OPTIONS] = $params{+CREATE_OPTIONS};
243 }
244 else {
245 0 croak "options for $type constructor is expected to be a HASH reference";
246 }
247 4 delete $params{+CREATE_OPTIONS};
248 }
249  
250 # Get down to the business of defining states.
251  
252 828 ▶ while (my ($param_name, $param_value) = each %params) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %params) 1228 828 2056
253  
254 # Inline states are expected to be state-name/coderef pairs.
255  
256 1228 ▶ if ($param_name eq CREATE_INLINES) {
Branch: 4 branches
BranchTrueFalseTotal
if ($param_name eq 'inline_states') { } 721 507 1228
elsif ($param_name eq 'package_states') { } 200 307 507
elsif ($param_name eq 'object_states') { } 104 203 307
elsif ($param_name eq 'heap') { } 203 0 203
257 721 ▶ croak "$param_name does not refer to a hash"
Branch: 1 branch
BranchTrueFalseTotal
unless ref $param_value eq "HASH" 0 721 721
258 unless (ref($param_value) eq 'HASH');
259  
260 721 ▶ while (my ($state, $handler) = each(%$param_value)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$param_value) 5061 721 5782
261 5061 ▶ croak "inline state for '$state' needs a CODE reference"
Branch: 1 branch
BranchTrueFalseTotal
unless ref $handler eq "CODE" 0 5061 5061
262 unless (ref($handler) eq 'CODE');
263 5061 $self->_register_state($state, $handler);
264 }
265 }
266  
267 # Package states are expected to be package-name/list-or-hashref
268 # pairs. If the second part of the pair is a arrayref, then the
269 # package methods are expected to be named after the states
270 # they'll handle. If it's a hashref, then the keys are state
271 # names and the values are package methods that implement them.
272  
273 elsif ($param_name eq CREATE_PACKAGES) {
274 200 ▶ croak "$param_name does not refer to an array"
Branch: 1 branch
BranchTrueFalseTotal
unless ref $param_value eq "ARRAY" 0 200 200
275 unless (ref($param_value) eq 'ARRAY');
276 200 ▶ croak "the array for $param_name has an odd number of elements"
Branch: 1 branch
BranchTrueFalseTotal
if @$param_value & 1 0 200 200
277 if (@$param_value & 1);
278  
279 # Copy the parameters so they aren't destroyed.
280 200 my @param_value = @$param_value;
281 200 ▶ while (my ($package, $handlers) = splice(@param_value, 0, 2)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@param_value, 0, 2)) 103 200 303
282  
283 # TODO What do we do if the package name has some sort of
284 # blessing? Do we use the blessed thingy's package, or do we
285 # maybe complain because the user might have wanted to make
286 # object states instead?
287  
288 # An array of handlers. The array's items are passed through
289 # as both state names and package method names.
290  
291 103 ▶ if (ref($handlers) eq 'ARRAY') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $handlers eq 'ARRAY') { } 100 3 103
elsif (ref $handlers eq 'HASH') { } 3 0 3
292 100 foreach my $method (@$handlers) {
293 863 $self->_register_state($method, $package, $method);
294 }
295 }
296  
297 # A hash of handlers. Hash keys are state names; values are
298 # package methods to implement them.
299  
300 elsif (ref($handlers) eq 'HASH') {
301 3 ▶ while (my ($state, $method) = each %$handlers) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$handlers) 7 3 10
302 7 $self->_register_state($state, $package, $method);
303 }
304 }
305  
306 else {
307 0 croak( "states for package '$package' " .
308 "need to be a hash or array ref"
309 );
310 }
311 }
312 }
313  
314 # Object states are expected to be object-reference/
315 # list-or-hashref pairs. They must be passed to &create in a list
316 # reference instead of a hash reference because making object
317 # references into hash keys loses their blessings.
318  
319 elsif ($param_name eq CREATE_OBJECTS) {
320 104 ▶ croak "$param_name does not refer to an array"
Branch: 1 branch
BranchTrueFalseTotal
unless ref $param_value eq "ARRAY" 0 104 104
321 unless (ref($param_value) eq 'ARRAY');
322 104 ▶ croak "the array for $param_name has an odd number of elements"
Branch: 1 branch
BranchTrueFalseTotal
if @$param_value & 1 0 104 104
323 if (@$param_value & 1);
324  
325 # Copy the parameters so they aren't destroyed.
326 104 my @param_value = @$param_value;
327 104 ▶ while (@param_value) {
Branch: 1 branch
BranchTrueFalseTotal
if (@param_value) 7 104 111
328 7 my ($object, $handlers) = splice(@param_value, 0, 2);
329  
330 # Verify that the object is an object. This may catch simple
331 # mistakes; or it may be overkill since it already checks that
332 # $param_value is a arrayref.
333  
334 7 ▶ carp "'$object' is not an object" unless ref($object);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $object 0 7 7
335  
336 # An array of handlers. The array's items are passed through
337 # as both state names and object method names.
338  
339 7 ▶ if (ref($handlers) eq 'ARRAY') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $handlers eq 'ARRAY') { } 4 3 7
elsif (ref $handlers eq 'HASH') { } 3 0 3
340 4 foreach my $method (@$handlers) {
341 13 $self->_register_state($method, $object, $method);
342 }
343 }
344  
345 # A hash of handlers. Hash keys are state names; values are
346 # package methods to implement them.
347  
348 elsif (ref($handlers) eq 'HASH') {
349 3 ▶ while (my ($state, $method) = each %$handlers) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$handlers) 7 3 10
350 7 $self->_register_state($state, $object, $method);
351 }
352 }
353  
354 else {
355 0 croak "states for object '$object' need to be a hash or array ref";
356 }
357  
358 }
359 }
360  
361 # Import an external heap. This is a convenience, since it
362 # eliminates the need to connect _start options to heap values.
363  
364 elsif ($param_name eq CREATE_HEAP) {
365 203 $self->[SE_NAMESPACE] = $param_value;
366 }
367  
368 else {
369 0 croak "unknown $type parameter: $param_name";
370 }
371 }
372  
373 828 return $self->try_alloc(@args);
374 }
375  
376 #------------------------------------------------------------------------------
377  
378 570 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
379 570 my $self = shift;
380  
381 # Session's data structures are destroyed through Perl's usual
382 # garbage collection. TRACE_DESTROY here just shows what's in the
383 # session before the destruction finishes.
384  
385 570 TRACE_DESTROY and do {
386 require Data::Dumper;
387 POE::Kernel::_warn(
388 "----- Session $self Leak Check -----\n",
389 "-- Namespace (HEAP):\n",
390 Data::Dumper::Dumper($self->[SE_NAMESPACE]),
391 "-- Options:\n",
392 );
393 foreach (sort keys (%{$self->[SE_OPTIONS]})) {
394 POE::Kernel::_warn(" $_ = ", $self->[SE_OPTIONS]->{$_}, "\n");
395 }
396 POE::Kernel::_warn("-- States:\n");
397 foreach (sort keys (%{$self->[SE_STATES]})) {
398 POE::Kernel::_warn(" $_ = ", $self->[SE_STATES]->{$_}, "\n");
399 }
400 };
401 }
402  
403 #------------------------------------------------------------------------------
404  
405 8681 ▶sub _invoke_state {
Subroutine _invoke_state: called CC=9 SCAR=22.1
406 8947 my ($self, $source_session, $state, $etc, $file, $line, $fromstate) = @_;
407  
408 # Trace the state invocation if tracing is enabled.
409  
410 8947 ▶ if ($self->[SE_OPTIONS]->{+OPT_TRACE}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->[1]{"trace"}) 8 8673 8681
411 274 POE::Kernel::_warn(
412 $POE::Kernel::poe_kernel->ID_session_to_id($self),
413 " -> $state (from $file at $line)\n"
414 );
415 }
416  
417 # The desired destination state doesn't exist in this session.
418 # Attempt to redirect the state transition to _default.
419  
420 8947 ▶ unless (exists $self->[SE_STATES]->{$state}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->[2]{$state}) 329 8352 8681
421  
422 # There's no _default either; redirection's not happening today.
423 # Drop the state transition event on the floor, and optionally
424 # make some noise about it.
425  
426 593 ▶ unless (exists $self->[SE_STATES]->{+EN_DEFAULT}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->[2]{"_default"}) 207 122 329
427 473 ▶ $! = exists &Errno::ENOSYS ? &Errno::ENOSYS : &Errno::EIO;
Branch: 1 branch
BranchTrueFalseTotal
exists &Errno::ENOSYS ? : 207 0 207
428 473 ▶ if ($self->[SE_OPTIONS]->{+OPT_DEFAULT} and $state ne EN_SIGNAL) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->[1]{"default"} and $state ne "_signal") 1 206 207
Condition66%2/3
$self->[1]{"default"} and $state ne "_signal"
!ll&&!rl&&r
20601
MC/DC50%1/2
$self->[1]{"default"} and $state ne "_signal"
$self->[1]{"default"} $state ne "_signal"
Truth table66%2/3
A and B
A= $self->[1]{"default"}B= $state ne "_signal"
ABresult
0X0
100
111
429 267 my $loggable_self =
430 $POE::Kernel::poe_kernel->_data_alias_loggable($self->ID);
431 1755 POE::Kernel::_warn(
432 "a '$state' event was sent from $file at $line to $loggable_self ",
433 "but $loggable_self has neither a handler for it ",
434 "nor one for _default\n"
435 );
436 }
437 207 return undef;
438 }
439  
440 # If we get this far, then there's a _default state to redirect
441 # the transition to. Trace the redirection.
442  
443 122 ▶ if ($self->[SE_OPTIONS]->{+OPT_TRACE}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->[1]{"trace"}) 0 122 122
444 0 POE::Kernel::_warn(
445 $POE::Kernel::poe_kernel->ID_session_to_id($self),
446 " -> $state redirected to _default\n"
447 );
448 }
449  
450 # Transmogrify the original state transition into a corresponding
451 # _default invocation. ARG1 is copied from $etc so it can't be
452 # altered from a distance.
453  
454 122 $etc = [ $state, [@$etc] ];
455 122 $state = EN_DEFAULT;
456 }
457  
458 # If we get this far, then the state can be invoked. So invoke it
459 # already!
460  
461 # Inline states are invoked this way.
462  
463 8474 ▶ if (ref($self->[SE_STATES]->{$state}) eq 'CODE') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self->[2]{$state} eq "CODE") 6025 2449 8474
464 6025 return $self->[SE_STATES]->{$state}->
465 ( undef, # object
466 $self, # session
467 $POE::Kernel::poe_kernel, # kernel
468 $self->[SE_NAMESPACE], # heap
469 $state, # state
470 $source_session, # sender
471 undef, # unused #6
472 $file, # caller file name
473 $line, # caller file line
474 $fromstate, # caller state
475 @$etc # args
476 );
477 }
478  
479 # Package and object states are invoked this way.
480  
481 2449 my ($object, $method) = @{$self->[SE_STATES]->{$state}};
482 return
483 2449 $object->$method # package/object (implied)
484 ( $self, # session
485 $POE::Kernel::poe_kernel, # kernel
486 $self->[SE_NAMESPACE], # heap
487 $state, # state
488 $source_session, # sender
489 undef, # unused #6
490 $file, # caller file name
491 $line, # caller file line
492 $fromstate, # caller state
493 @$etc # args
494 );
495 }
496  
497 #------------------------------------------------------------------------------
498 # Add, remove or replace states in the session.
499  
500 8074 ▶sub _register_state {
Subroutine _register_state: called CC=15 SCAR=40.2
501 8074 my ($self, $name, $handler, $method) = @_;
502 8074 ▶ $method = $name unless defined $method;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $method 5061 3013 8074
503  
504 # Deprecate _signal.
505 # RC 2004-09-07 - Decided to leave this in because it blames
506 # problems with _signal on the user for using it. It should
507 # probably go away after a little while, but not during the other
508 # deprecations.
509  
510 8074 ▶ if ($name eq EN_SIGNAL) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "_signal") 0 8074 8074
511  
512 # Report the problem outside POE.
513 0 my $caller_level = 0;
514 0 local $Carp::CarpLevel = 1;
515 0 ▶ while ( (caller $caller_level)[0] =~ /^POE::/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ((caller $caller_level)[0] =~ /^POE::/) 0 0 0
516 0 $caller_level++;
517 0 $Carp::CarpLevel++;
518 }
519  
520 croak(
521 0 ",----- DEPRECATION ERROR -----\n",
522 "| The _signal event is deprecated. Please use sig() to register\n",
523 "| an explicit signal handler instead.\n",
524 "`-----------------------------\n",
525 );
526 }
527  
528 # There is a handler, so try to define the state. This replaces an
529 # existing state.
530  
531 8074 ▶ if ($handler) {
Branch: 1 branch
BranchTrueFalseTotal
if ($handler) { } 7116 958 8074
532  
533 # Coderef handlers are inline states.
534  
535 7116 ▶ if (ref($handler) eq 'CODE') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $handler eq 'CODE') { } 6226 890 7116
elsif ($handler->can($method)) { } 890 0 890
536 carp( "redefining handler for event($name) for session(",
537 $POE::Kernel::poe_kernel->ID_session_to_id($self), ")"
538 )
539 if ( $self->[SE_OPTIONS]->{+OPT_DEBUG} &&
540 6226 ▶ (exists $self->[SE_STATES]->{$name})
Branch: 1 branch
BranchTrueFalseTotal
if $self->[1]{"debug"} and exists $self->[2]{$name} 0 6226 6226
Condition66%2/3
$self->[1]{"debug"} and exists $self->[2]{$name}
!ll&&!rl&&r
621880
MC/DC0%0/2
$self->[1]{"debug"} and exists $self->[2]{$name}
$self->[1]{"debug"} exists $self->[2]{$name}
Truth table66%2/3
A and B
A= $self->[1]{"debug"}B= exists $self->[2]{$name}
ABresult
0X0
100
111
541 );
542 6226 $self->[SE_STATES]->{$name} = $handler;
543 }
544  
545 # Non-coderef handlers may be package or object states. See if
546 # the method belongs to the handler.
547  
548 elsif ($handler->can($method)) {
549 carp( "redefining handler for event($name) for session(",
550 $POE::Kernel::poe_kernel->ID_session_to_id($self), ")"
551 )
552 if ( $self->[SE_OPTIONS]->{+OPT_DEBUG} &&
553 890 ▶ (exists $self->[SE_STATES]->{$name})
Branch: 1 branch
BranchTrueFalseTotal
if $self->[1]{"debug"} and exists $self->[2]{$name} 0 890 890
Condition33%1/3
$self->[1]{"debug"} and exists $self->[2]{$name}
!ll&&!rl&&r
89000
MC/DC0%0/2
$self->[1]{"debug"} and exists $self->[2]{$name}
$self->[1]{"debug"} exists $self->[2]{$name}
Truth table33%1/3
A and B
A= $self->[1]{"debug"}B= exists $self->[2]{$name}
ABresult
0X0
100
111
554 );
555 890 $self->[SE_STATES]->{$name} = [ $handler, $method ];
556 }
557  
558 # Something's wrong. This code also seems wrong, since
559 # ref($handler) can't be 'CODE'.
560  
561 else {
562 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
563 $self->[SE_OPTIONS]->{+OPT_TRACE}
564 ) {
565 0 carp( $POE::Kernel::poe_kernel->ID_session_to_id($self),
566 " : handler for event($name) is not a proper ref - not registered"
567 )
568 }
569 else {
570 0 ▶ unless ($handler->can($method)) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($handler->can($method)) 0 0 0
571 0 ▶ if (length ref($handler)) {
Branch: 1 branch
BranchTrueFalseTotal
if (length ref $handler) { } 0 0 0
572 0 croak "object $handler does not have a '$method' method"
573 }
574 else {
575 0 croak "package $handler does not have a '$method' method";
576 }
577 }
578 }
579 }
580 }
581  
582 # No handler. Delete the state!
583  
584 else {
585 958 delete $self->[SE_STATES]->{$name};
586 }
587 }
588  
589 #------------------------------------------------------------------------------
590 # Return the session's ID. This is a thunk into POE::Kernel, where
591 # the session ID really lies.
592  
593 836 ▶sub _set_id {
Subroutine _set_id: called CC=1 SCAR=0.0
594 836 my ($self, $id) = @_;
595 836 $self->[SE_ID] = $id;
596 }
597  
598 833452 ▶sub ID {
Subroutine ID: called CC=1 SCAR=0.0
Pod documented
599 833452 return shift()->[SE_ID];
600 }
601  
602 #------------------------------------------------------------------------------
603 # Set or fetch session options.
604  
605 8 ▶sub option {
Subroutine option: called CC=8 SCAR=21.6
Pod documented
606 8 my $self = shift;
607 8 my %return_values;
608  
609 # Options are set in pairs.
610  
611 8 ▶ while (@_ >= 2) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ >= 2) 4 8 12
612 4 my ($flag, $value) = splice(@_, 0, 2);
613 4 $flag = lc($flag);
614  
615 # If the value is defined, then set the option.
616  
617 4 ▶ if (defined $value) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value) { } 4 0 4
618  
619 # Change some handy values into boolean representations. This
620 # clobbers the user's original values for the sake of DWIM-ism.
621  
622 4 ▶ ($value = 1) if ($value =~ /^(on|yes|true)$/i);
Branch: 1 branch
BranchTrueFalseTotal
if $value =~ /^(on|yes|true)$/i 0 4 4
623 4 ▶ ($value = 0) if ($value =~ /^(no|off|false)$/i);
Branch: 1 branch
BranchTrueFalseTotal
if $value =~ /^(no|off|false)$/i 0 4 4
624  
625 4 $return_values{$flag} = $self->[SE_OPTIONS]->{$flag};
626 4 $self->[SE_OPTIONS]->{$flag} = $value;
627 }
628  
629 # Remove the option if the value is undefined.
630  
631 else {
632 0 $return_values{$flag} = delete $self->[SE_OPTIONS]->{$flag};
633 }
634 }
635  
636 # If only one option is left, then there's no value to set, so we
637 # fetch its value.
638  
639 8 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 4 4 8
640 4 my $flag = lc(shift);
641 $return_values{$flag} =
642 ( exists($self->[SE_OPTIONS]->{$flag})
643 4 ▶ ? $self->[SE_OPTIONS]->{$flag}
Branch: 1 branch
BranchTrueFalseTotal
exists $self->[1]{$flag} ? : 4 0 4
644 : undef
645 );
646 }
647  
648 # If only one option was set or fetched, then return it as a scalar.
649 # Otherwise return it as a hash of option names and values.
650  
651 8 my @return_keys = keys(%return_values);
652 8 ▶ if (@return_keys == 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (@return_keys == 1) { } 8 0 8
653 8 return $return_values{$return_keys[0]};
654 }
655 else {
656 0 return \%return_values;
657 }
658 }
659  
660 # Fetch the session's heap. In rare cases, libraries may need to
661 # break encapsulation this way, probably also using
662 # $kernel->get_current_session as an accessory to the crime.
663  
664 2 ▶sub get_heap {
Subroutine get_heap: called CC=1 SCAR=0.0
Pod documented
665 2 my $self = shift;
666 2 return $self->[SE_NAMESPACE];
667 }
668  
669 #------------------------------------------------------------------------------
670 # Create an anonymous sub that, when called, posts an event back to a
671 # session. This maps postback references (stringified; blessing, and
672 # thus refcount, removed) to parent session IDs. Members are set when
673 # postbacks are created, and postbacks' DESTROY methods use it to
674 # perform the necessary cleanup when they go away. Thanks to njt for
675 # steering me right on this one.
676  
677 194 my %anonevent_parent_id;
678 my %anonevent_weakened;
679  
680 # I assume that when the postback owner loses all reference to it,
681 # they are done posting things back to us. That's when the postback's
682 # DESTROY is triggered, and referential integrity is maintained.
683  
684 15 ▶sub POE::Session::AnonEvent::DESTROY {
Subroutine DESTROY: called CC=2 SCAR=7.0
685 15 my $self = shift;
686 15 my $parent_id = delete $anonevent_parent_id{$self};
687 15 ▶ unless (delete $anonevent_weakened{$self}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (delete $anonevent_weakened{$self}) 15 0 15
688 15 $POE::Kernel::poe_kernel->refcount_decrement( $parent_id, 'anon_event' );
689 }
690 }
691  
692 0 ▶sub POE::Session::AnonEvent::weaken {
Subroutine weaken: not called CC=2 SCAR=17.9
693 0 my $self = shift;
694 0 ▶ unless ($anonevent_weakened{$self}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($anonevent_weakened{$self}) 0 0 0
695 0 my $parent_id = $anonevent_parent_id{$self};
696 0 $POE::Kernel::poe_kernel->refcount_decrement( $parent_id, 'anon_event' );
697 0 $anonevent_weakened{$self} = 1;
698 }
699 0 return $self;
700 }
701  
702 # Tune postbacks depending on variations in toolkit behavior.
703  
704 194 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=8.1
705 # Tk blesses its callbacks internally, so we need to wrap our
706 # blessed callbacks in unblessed ones. Otherwise our postback's
707 # DESTROY method probably won't be called.
708 194 ▶ if (exists $INC{'Tk.pm'}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $INC{'Tk.pm'}) { } 0 194 194
709 0 eval 'sub USING_TK () { 1 }';
710 }
711 else {
712 194 ▶ eval 'sub USING_TK () { 0 }';
Subroutine BEGIN: not called CC=1 SCAR=0.0
713 }
714 };
715  
716 # Create a postback closure, maintaining referential integrity in the
717 # process. The next step is to give it to something that expects to
718 # be handed a callback.
719  
720 7 ▶sub postback {
Subroutine postback: called CC=1 SCAR=0.0
Pod documented
721 7 my ($self, $event, @etc) = @_;
722 7 my $id = $POE::Kernel::poe_kernel->ID_session_to_id($self);
723  
724 7 ▶ my $postback = bless sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
725 7 $POE::Kernel::poe_kernel->post( $id, $event, [ @etc ], [ @_ ] );
726 7 return 0;
727 7 }, 'POE::Session::AnonEvent';
728  
729 7 $anonevent_parent_id{$postback} = $id;
730 7 $POE::Kernel::poe_kernel->refcount_increment( $id, 'anon_event' );
731  
732 # Tk blesses its callbacks, so we must present one that isn't
733 # blessed. Otherwise Tk's blessing would divert our DESTROY call to
734 # its own, and that's not right.
735  
736 0 ▶ return sub { $postback->(@_) } if USING_TK;
Subroutine __ANON__: not called CC=1 SCAR=1.2
737 7 return $postback;
738 }
739  
740 # Create a synchronous callback closure. The return value will be
741 # passed to whatever is handed the callback.
742  
743 8 ▶sub callback {
Subroutine callback: called CC=1 SCAR=0.0
Pod documented
744 8 my ($self, $event, @etc) = @_;
745 8 my $id = $POE::Kernel::poe_kernel->ID_session_to_id($self);
746  
747 8 ▶ my $callback = bless sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
748 8 $POE::Kernel::poe_kernel->call( $id, $event, [ @etc ], [ @_ ] );
749 8 }, 'POE::Session::AnonEvent';
750  
751 8 $anonevent_parent_id{$callback} = $id;
752 8 $POE::Kernel::poe_kernel->refcount_increment( $id, 'anon_event' );
753  
754 # Tk blesses its callbacks, so we must present one that isn't
755 # blessed. Otherwise Tk's blessing would divert our DESTROY call to
756 # its own, and that's not right.
757  
758 0 ▶ return sub { $callback->(@_) } if USING_TK;
Subroutine __ANON__: not called CC=1 SCAR=1.2
759 8 return $callback;
760 }
761  
762 194 1;
763  
764 __END__
« blib/lib/POE/Loop/IO_Poll.pm ↑ Summary blib/lib/POE/Resource/FileHandles.pm »