Added experimental code to allow postbacks and callbacks to be
[poe:poe-loop-tk.git] / poe / lib / POE / Session.pm
1 # $Id$
2
3 package POE::Session;
4
5 use strict;
6
7 use vars qw($VERSION);
8 $VERSION = do {my($r)=(q$Revision$=~/(\d+)/);sprintf"1.%04d",$r};
9
10 use Carp qw(carp croak);
11 use Errno;
12
13 sub SE_NAMESPACE    () { 0 }
14 sub SE_OPTIONS      () { 1 }
15 sub SE_STATES       () { 2 }
16
17 sub CREATE_ARGS     () { 'args' }
18 sub CREATE_OPTIONS  () { 'options' }
19 sub CREATE_INLINES  () { 'inline_states' }
20 sub CREATE_PACKAGES () { 'package_states' }
21 sub CREATE_OBJECTS  () { 'object_states' }
22 sub CREATE_HEAP     () { 'heap' }
23
24 sub OPT_TRACE       () { 'trace' }
25 sub OPT_DEBUG       () { 'debug' }
26 sub OPT_DEFAULT     () { 'default' }
27
28 sub EN_START        () { '_start' }
29 sub EN_DEFAULT      () { '_default' }
30 sub EN_SIGNAL       () { '_signal' }
31
32 #------------------------------------------------------------------------------
33 # Debugging flags for subsystems.  They're done as double evals here
34 # so that someone may define them before using POE::Session (or POE),
35 # and the pre-defined value will take precedence over the defaults
36 # here.
37
38 # Shorthand for defining an assert constant.
39
40 sub _define_assert {
41   no strict 'refs';
42   foreach my $name (@_) {
43
44     local $^W = 0;
45
46     next if defined *{"ASSERT_$name"}{CODE};
47     if (defined *{"POE::Kernel::ASSERT_$name"}{CODE}) {
48       eval(
49         "sub ASSERT_$name () { " .
50         *{"POE::Kernel::ASSERT_$name"}{CODE}->() .
51         "}"
52       );
53       die if $@;
54     }
55     else {
56       eval "sub ASSERT_$name () { ASSERT_DEFAULT }";
57       die if $@;
58     }
59   }
60 }
61
62 # Shorthand for defining a trace constant.
63 sub _define_trace {
64   no strict 'refs';
65
66   local $^W = 0;
67
68   foreach my $name (@_) {
69     next if defined *{"TRACE_$name"}{CODE};
70     if (defined *{"POE::Kernel::TRACE_$name"}{CODE}) {
71       eval(
72         "sub TRACE_$name () { " .
73         *{"POE::Kernel::TRACE_$name"}{CODE}->() .
74         "}"
75       );
76       die if $@;
77     }
78     else {
79       eval "sub TRACE_$name () { TRACE_DEFAULT }";
80       die if $@;
81     }
82   }
83 }
84
85 BEGIN {
86
87   # ASSERT_DEFAULT changes the default value for other ASSERT_*
88   # constants.  It inherits POE::Kernel's ASSERT_DEFAULT value, if
89   # it's present.
90
91   unless (defined &ASSERT_DEFAULT) {
92     if (defined &POE::Kernel::ASSERT_DEFAULT) {
93       eval( "sub ASSERT_DEFAULT () { " . &POE::Kernel::ASSERT_DEFAULT . " }" );
94     }
95     else {
96       eval 'sub ASSERT_DEFAULT () { 0 }';
97     }
98   };
99
100   # TRACE_DEFAULT changes the default value for other TRACE_*
101   # constants.  It inherits POE::Kernel's TRACE_DEFAULT value, if
102   # it's present.
103
104   unless (defined &TRACE_DEFAULT) {
105     if (defined &POE::Kernel::TRACE_DEFAULT) {
106       eval( "sub TRACE_DEFAULT () { " . &POE::Kernel::TRACE_DEFAULT . " }" );
107     }
108     else {
109       eval 'sub TRACE_DEFAULT () { 0 }';
110     }
111   };
112
113   _define_assert("STATES");
114   _define_trace("DESTROY");
115 }
116
117 #------------------------------------------------------------------------------
118 # Export constants into calling packages.  This is evil; perhaps
119 # EXPORT_OK instead?  The parameters NFA has in common with SESSION
120 # (and other sessions) must be kept at the same offsets as each-other.
121
122 sub OBJECT  () {  0 } # TODO - deprecate and replace with SELF
123 sub SESSION () {  1 }
124 sub KERNEL  () {  2 }
125 sub HEAP    () {  3 }
126 sub STATE   () {  4 } # TODO - deprecate and replace with EVENT
127 sub SENDER  () {  5 }
128 # NFA keeps its state in 6.  unused in session so that args match up.
129 sub CALLER_FILE () { 7 }
130 sub CALLER_LINE () { 8 }
131 sub CALLER_STATE () { 9 } # TODO - deprecate and replace with CALLER_EVENT
132 sub ARG0    () { 10 }
133 sub ARG1    () { 11 }
134 sub ARG2    () { 12 }
135 sub ARG3    () { 13 }
136 sub ARG4    () { 14 }
137 sub ARG5    () { 15 }
138 sub ARG6    () { 16 }
139 sub ARG7    () { 17 }
140 sub ARG8    () { 18 }
141 sub ARG9    () { 19 }
142
143 sub import {
144   my $package = caller();
145   no strict 'refs';
146   *{ $package . '::OBJECT'  } = \&OBJECT;
147   *{ $package . '::SESSION' } = \&SESSION;
148   *{ $package . '::KERNEL'  } = \&KERNEL;
149   *{ $package . '::HEAP'    } = \&HEAP;
150   *{ $package . '::STATE'   } = \&STATE;
151   *{ $package . '::SENDER'  } = \&SENDER;
152   *{ $package . '::ARG0'    } = \&ARG0;
153   *{ $package . '::ARG1'    } = \&ARG1;
154   *{ $package . '::ARG2'    } = \&ARG2;
155   *{ $package . '::ARG3'    } = \&ARG3;
156   *{ $package . '::ARG4'    } = \&ARG4;
157   *{ $package . '::ARG5'    } = \&ARG5;
158   *{ $package . '::ARG6'    } = \&ARG6;
159   *{ $package . '::ARG7'    } = \&ARG7;
160   *{ $package . '::ARG8'    } = \&ARG8;
161   *{ $package . '::ARG9'    } = \&ARG9;
162   *{ $package . '::CALLER_FILE' } = \&CALLER_FILE;
163   *{ $package . '::CALLER_LINE' } = \&CALLER_LINE;
164   *{ $package . '::CALLER_STATE' } = \&CALLER_STATE;
165 }
166
167 sub instantiate {
168   my $type = shift;
169
170   croak "$type requires a working Kernel"
171     unless defined $POE::Kernel::poe_kernel;
172
173   my $self =
174     bless [ { }, # SE_NAMESPACE
175             { }, # SE_OPTIONS
176             { }, # SE_STATES
177           ], $type;
178
179   if (ASSERT_STATES) {
180     $self->[SE_OPTIONS]->{+OPT_DEFAULT} = 1;
181   }
182
183   return $self;
184 }
185
186 sub try_alloc {
187   my ($self, @args) = @_;
188   # Verify that the session has a special start state, otherwise how
189   # do we know what to do?  Don't even bother registering the session
190   # if the start state doesn't exist.
191
192   if (exists $self->[SE_STATES]->{+EN_START}) {
193     $POE::Kernel::poe_kernel->session_alloc($self, @args);
194   }
195   else {
196     carp( "discarding session ",
197           $POE::Kernel::poe_kernel->ID_session_to_id($self),
198           " - no '_start' state"
199         );
200     $self = undef;
201   }
202
203   $self;
204 }
205
206 #------------------------------------------------------------------------------
207 # New style constructor.  This uses less DWIM and more DWIS, and it's
208 # more comfortable for some folks; especially the ones who don't quite
209 # know WTM.
210
211 sub create {
212   my ($type, @params) = @_;
213   my @args;
214
215   # We treat the parameter list strictly as a hash.  Rather than dying
216   # here with a Perl error, we'll catch it and blame it on the user.
217
218   if (@params & 1) {
219     croak "odd number of events/handlers (missing one or the other?)";
220   }
221   my %params = @params;
222
223   my $self = $type->instantiate(\%params);
224
225   # Process _start arguments.  We try to do the right things with what
226   # we're given.  If the arguments are a list reference, map its items
227   # to ARG0..ARGn; otherwise make whatever the heck it is be ARG0.
228
229   if (exists $params{+CREATE_ARGS}) {
230     if (ref($params{+CREATE_ARGS}) eq 'ARRAY') {
231       push @args, @{$params{+CREATE_ARGS}};
232     }
233     else {
234       push @args, $params{+CREATE_ARGS};
235     }
236     delete $params{+CREATE_ARGS};
237   }
238
239   # Process session options here.  Several options may be set.
240
241   if (exists $params{+CREATE_OPTIONS}) {
242     if (ref($params{+CREATE_OPTIONS}) eq 'HASH') {
243       $self->[SE_OPTIONS] = $params{+CREATE_OPTIONS};
244     }
245     else {
246       croak "options for $type constructor is expected to be a HASH reference";
247     }
248     delete $params{+CREATE_OPTIONS};
249   }
250
251   # Get down to the business of defining states.
252
253   while (my ($param_name, $param_value) = each %params) {
254
255     # Inline states are expected to be state-name/coderef pairs.
256
257     if ($param_name eq CREATE_INLINES) {
258       croak "$param_name does not refer to a hash"
259         unless (ref($param_value) eq 'HASH');
260
261       while (my ($state, $handler) = each(%$param_value)) {
262         croak "inline state for '$state' needs a CODE reference"
263           unless (ref($handler) eq 'CODE');
264         $self->_register_state($state, $handler);
265       }
266     }
267
268     # Package states are expected to be package-name/list-or-hashref
269     # pairs.  If the second part of the pair is a arrayref, then the
270     # package methods are expected to be named after the states
271     # they'll handle.  If it's a hashref, then the keys are state
272     # names and the values are package methods that implement them.
273
274     elsif ($param_name eq CREATE_PACKAGES) {
275       croak "$param_name does not refer to an array"
276         unless (ref($param_value) eq 'ARRAY');
277       croak "the array for $param_name has an odd number of elements"
278         if (@$param_value & 1);
279
280       # Copy the parameters so they aren't destroyed.
281       my @param_value = @$param_value;
282       while (my ($package, $handlers) = splice(@param_value, 0, 2)) {
283
284         # TODO What do we do if the package name has some sort of
285         # blessing?  Do we use the blessed thingy's package, or do we
286         # maybe complain because the user might have wanted to make
287         # object states instead?
288
289         # An array of handlers.  The array's items are passed through
290         # as both state names and package method names.
291
292         if (ref($handlers) eq 'ARRAY') {
293           foreach my $method (@$handlers) {
294             $self->_register_state($method, $package, $method);
295           }
296         }
297
298         # A hash of handlers.  Hash keys are state names; values are
299         # package methods to implement them.
300
301         elsif (ref($handlers) eq 'HASH') {
302           while (my ($state, $method) = each %$handlers) {
303             $self->_register_state($state, $package, $method);
304           }
305         }
306
307         else {
308           croak( "states for package '$package' " .
309                  "need to be a hash or array ref"
310                );
311         }
312       }
313     }
314
315     # Object states are expected to be object-reference/
316     # list-or-hashref pairs.  They must be passed to &create in a list
317     # reference instead of a hash reference because making object
318     # references into hash keys loses their blessings.
319
320     elsif ($param_name eq CREATE_OBJECTS) {
321       croak "$param_name does not refer to an array"
322         unless (ref($param_value) eq 'ARRAY');
323       croak "the array for $param_name has an odd number of elements"
324         if (@$param_value & 1);
325
326       # Copy the parameters so they aren't destroyed.
327       my @param_value = @$param_value;
328       while (@param_value) {
329         my ($object, $handlers) = splice(@param_value, 0, 2);
330
331         # Verify that the object is an object.  This may catch simple
332         # mistakes; or it may be overkill since it already checks that
333         # $param_value is a arrayref.
334
335         carp "'$object' is not an object" unless ref($object);
336
337         # An array of handlers.  The array's items are passed through
338         # as both state names and object method names.
339
340         if (ref($handlers) eq 'ARRAY') {
341           foreach my $method (@$handlers) {
342             $self->_register_state($method, $object, $method);
343           }
344         }
345
346         # A hash of handlers.  Hash keys are state names; values are
347         # package methods to implement them.
348
349         elsif (ref($handlers) eq 'HASH') {
350           while (my ($state, $method) = each %$handlers) {
351             $self->_register_state($state, $object, $method);
352           }
353         }
354
355         else {
356           croak "states for object '$object' need to be a hash or array ref";
357         }
358
359       }
360     }
361
362     # Import an external heap.  This is a convenience, since it
363     # eliminates the need to connect _start options to heap values.
364
365     elsif ($param_name eq CREATE_HEAP) {
366       $self->[SE_NAMESPACE] = $param_value;
367     }
368
369     else {
370       croak "unknown $type parameter: $param_name";
371     }
372   }
373
374   return $self->try_alloc(@args);
375 }
376
377 #------------------------------------------------------------------------------
378
379 sub DESTROY {
380   my $self = shift;
381
382   # Session's data structures are destroyed through Perl's usual
383   # garbage collection.  TRACE_DESTROY here just shows what's in the
384   # session before the destruction finishes.
385
386   TRACE_DESTROY and do {
387     require Data::Dumper;
388     POE::Kernel::_warn(
389       "----- Session $self Leak Check -----\n",
390       "-- Namespace (HEAP):\n",
391       Data::Dumper::Dumper($self->[SE_NAMESPACE]),
392       "-- Options:\n",
393     );
394     foreach (sort keys (%{$self->[SE_OPTIONS]})) {
395       POE::Kernel::_warn("   $_ = ", $self->[SE_OPTIONS]->{$_}, "\n");
396     }
397     POE::Kernel::_warn("-- States:\n");
398     foreach (sort keys (%{$self->[SE_STATES]})) {
399       POE::Kernel::_warn("   $_ = ", $self->[SE_STATES]->{$_}, "\n");
400     }
401   };
402 }
403
404 #------------------------------------------------------------------------------
405
406 sub _invoke_state {
407   my ($self, $source_session, $state, $etc, $file, $line, $fromstate) = @_;
408
409   # Trace the state invocation if tracing is enabled.
410
411   if ($self->[SE_OPTIONS]->{+OPT_TRACE}) {
412     POE::Kernel::_warn(
413       $POE::Kernel::poe_kernel->ID_session_to_id($self),
414       " -> $state (from $file at $line)\n"
415     );
416   }
417
418   # The desired destination state doesn't exist in this session.
419   # Attempt to redirect the state transition to _default.
420
421   unless (exists $self->[SE_STATES]->{$state}) {
422
423     # There's no _default either; redirection's not happening today.
424     # Drop the state transition event on the floor, and optionally
425     # make some noise about it.
426
427     unless (exists $self->[SE_STATES]->{+EN_DEFAULT}) {
428       $! = exists &Errno::ENOSYS ? &Errno::ENOSYS : &Errno::EIO;
429       if ($self->[SE_OPTIONS]->{+OPT_DEFAULT} and $state ne EN_SIGNAL) {
430         my $loggable_self =
431           $POE::Kernel::poe_kernel->_data_alias_loggable($self);
432         POE::Kernel::_warn(
433           "a '$state' event was sent from $file at $line to $loggable_self ",
434           "but $loggable_self has neither a handler for it ",
435           "nor one for _default\n"
436         );
437       }
438       return undef;
439     }
440
441     # If we get this far, then there's a _default state to redirect
442     # the transition to.  Trace the redirection.
443
444     if ($self->[SE_OPTIONS]->{+OPT_TRACE}) {
445       POE::Kernel::_warn(
446         $POE::Kernel::poe_kernel->ID_session_to_id($self),
447         " -> $state redirected to _default\n"
448       );
449     }
450
451     # Transmogrify the original state transition into a corresponding
452     # _default invocation.  ARG1 is copied from $etc so it can't be
453     # altered from a distance.
454
455     $etc   = [ $state, [@$etc] ];
456     $state = EN_DEFAULT;
457   }
458
459   # If we get this far, then the state can be invoked.  So invoke it
460   # already!
461
462   # Inline states are invoked this way.
463
464   if (ref($self->[SE_STATES]->{$state}) eq 'CODE') {
465     return $self->[SE_STATES]->{$state}->
466       ( undef,                          # object
467         $self,                          # session
468         $POE::Kernel::poe_kernel,       # kernel
469         $self->[SE_NAMESPACE],          # heap
470         $state,                         # state
471         $source_session,                # sender
472         undef,                          # unused #6
473         $file,                          # caller file name
474         $line,                          # caller file line
475         $fromstate,                     # caller state
476         @$etc                           # args
477       );
478   }
479
480   # Package and object states are invoked this way.
481
482   my ($object, $method) = @{$self->[SE_STATES]->{$state}};
483   return
484     $object->$method                    # package/object (implied)
485       ( $self,                          # session
486         $POE::Kernel::poe_kernel,       # kernel
487         $self->[SE_NAMESPACE],          # heap
488         $state,                         # state
489         $source_session,                # sender
490         undef,                          # unused #6
491         $file,                          # caller file name
492         $line,                          # caller file line
493     $fromstate,            # caller state
494         @$etc                           # args
495       );
496 }
497
498 #------------------------------------------------------------------------------
499 # Add, remove or replace states in the session.
500
501 sub _register_state {
502   my ($self, $name, $handler, $method) = @_;
503   $method = $name unless defined $method;
504
505   # Deprecate _signal.
506   # RC 2004-09-07 - Decided to leave this in because it blames
507   # problems with _signal on the user for using it.  It should
508   # probably go away after a little while, but not during the other
509   # deprecations.
510
511   if ($name eq EN_SIGNAL) {
512
513     # Report the problem outside POE.
514     my $caller_level = 0;
515     local $Carp::CarpLevel = 1;
516     while ( (caller $caller_level)[0] =~ /^POE::/ ) {
517       $caller_level++;
518       $Carp::CarpLevel++;
519     }
520
521     croak(
522       ",----- DEPRECATION ERROR -----\n",
523       "| The _signal event is deprecated.  Please use sig() to register\n",
524       "| an explicit signal handler instead.\n",
525       "`-----------------------------\n",
526    );
527   }
528
529   # There is a handler, so try to define the state.  This replaces an
530   # existing state.
531
532   if ($handler) {
533
534     # Coderef handlers are inline states.
535
536     if (ref($handler) eq 'CODE') {
537       carp( "redefining handler for event($name) for session(",
538             $POE::Kernel::poe_kernel->ID_session_to_id($self), ")"
539           )
540         if ( $self->[SE_OPTIONS]->{+OPT_DEBUG} &&
541              (exists $self->[SE_STATES]->{$name})
542            );
543       $self->[SE_STATES]->{$name} = $handler;
544     }
545
546     # Non-coderef handlers may be package or object states.  See if
547     # the method belongs to the handler.
548
549     elsif ($handler->can($method)) {
550       carp( "redefining handler for event($name) for session(",
551             $POE::Kernel::poe_kernel->ID_session_to_id($self), ")"
552           )
553         if ( $self->[SE_OPTIONS]->{+OPT_DEBUG} &&
554              (exists $self->[SE_STATES]->{$name})
555            );
556       $self->[SE_STATES]->{$name} = [ $handler, $method ];
557     }
558
559     # Something's wrong.  This code also seems wrong, since
560     # ref($handler) can't be 'CODE'.
561
562     else {
563       if ( (ref($handler) eq 'CODE') and
564            $self->[SE_OPTIONS]->{+OPT_TRACE}
565          ) {
566         carp( $POE::Kernel::poe_kernel->ID_session_to_id($self),
567               " : handler for event($name) is not a proper ref - not registered"
568             )
569       }
570       else {
571         unless ($handler->can($method)) {
572           if (length ref($handler)) {
573             croak "object $handler does not have a '$method' method"
574           }
575           else {
576             croak "package $handler does not have a '$method' method";
577           }
578         }
579       }
580     }
581   }
582
583   # No handler.  Delete the state!
584
585   else {
586     delete $self->[SE_STATES]->{$name};
587   }
588 }
589
590 #------------------------------------------------------------------------------
591 # Return the session's ID.  This is a thunk into POE::Kernel, where
592 # the session ID really lies.
593
594 sub ID {
595   $POE::Kernel::poe_kernel->ID_session_to_id(shift);
596 }
597
598 #------------------------------------------------------------------------------
599 # Set or fetch session options.
600
601 sub option {
602   my $self = shift;
603   my %return_values;
604
605   # Options are set in pairs.
606
607   while (@_ >= 2) {
608     my ($flag, $value) = splice(@_, 0, 2);
609     $flag = lc($flag);
610
611     # If the value is defined, then set the option.
612
613     if (defined $value) {
614
615       # Change some handy values into boolean representations.  This
616       # clobbers the user's original values for the sake of DWIM-ism.
617
618       ($value = 1) if ($value =~ /^(on|yes|true)$/i);
619       ($value = 0) if ($value =~ /^(no|off|false)$/i);
620
621       $return_values{$flag} = $self->[SE_OPTIONS]->{$flag};
622       $self->[SE_OPTIONS]->{$flag} = $value;
623     }
624
625     # Remove the option if the value is undefined.
626
627     else {
628       $return_values{$flag} = delete $self->[SE_OPTIONS]->{$flag};
629     }
630   }
631
632   # If only one option is left, then there's no value to set, so we
633   # fetch its value.
634
635   if (@_) {
636     my $flag = lc(shift);
637     $return_values{$flag} =
638       ( exists($self->[SE_OPTIONS]->{$flag})
639         ? $self->[SE_OPTIONS]->{$flag}
640         : undef
641       );
642   }
643
644   # If only one option was set or fetched, then return it as a scalar.
645   # Otherwise return it as a hash of option names and values.
646
647   my @return_keys = keys(%return_values);
648   if (@return_keys == 1) {
649     return $return_values{$return_keys[0]};
650   }
651   else {
652     return \%return_values;
653   }
654 }
655
656 # Fetch the session's heap.  In rare cases, libraries may need to
657 # break encapsulation this way, probably also using
658 # $kernel->get_current_session as an accessory to the crime.
659
660 sub get_heap {
661   my $self = shift;
662   return $self->[SE_NAMESPACE];
663 }
664
665 #------------------------------------------------------------------------------
666 # Create an anonymous sub that, when called, posts an event back to a
667 # session.  This maps postback references (stringified; blessing, and
668 # thus refcount, removed) to parent session IDs.  Members are set when
669 # postbacks are created, and postbacks' DESTROY methods use it to
670 # perform the necessary cleanup when they go away.  Thanks to njt for
671 # steering me right on this one.
672
673 my %anonevent_parent_id;
674 my %anonevent_weakened;
675
676 # I assume that when the postback owner loses all reference to it,
677 # they are done posting things back to us.  That's when the postback's
678 # DESTROY is triggered, and referential integrity is maintained.
679
680 sub POE::Session::AnonEvent::DESTROY {
681   my $self = shift;
682   my $parent_id = delete $anonevent_parent_id{$self};
683   unless (delete $anonevent_weakened{$self}) {
684     $POE::Kernel::poe_kernel->refcount_decrement( $parent_id, 'anon_event' );
685   }
686 }
687
688 sub POE::Session::AnonEvent::weaken {
689   my $self = shift;
690   unless ($anonevent_weakened{$self}) {
691     my $parent_id = $anonevent_parent_id{$self};
692     $POE::Kernel::poe_kernel->refcount_decrement( $parent_id, 'anon_event' );
693     $anonevent_weakened{$self} = 1;
694   }
695   return $self;
696 }
697
698 # Tune postbacks depending on variations in toolkit behavior.
699
700 BEGIN {
701   # Tk blesses its callbacks internally, so we need to wrap our
702   # blessed callbacks in unblessed ones.  Otherwise our postback's
703   # DESTROY method probably won't be called.
704   if (exists $INC{'Tk.pm'}) {
705     eval 'sub USING_TK () { 1 }';
706   }
707   else {
708     eval 'sub USING_TK () { 0 }';
709   }
710 };
711
712 # Create a postback closure, maintaining referential integrity in the
713 # process.  The next step is to give it to something that expects to
714 # be handed a callback.
715
716 sub postback {
717   my ($self, $event, @etc) = @_;
718   my $id = $POE::Kernel::poe_kernel->ID_session_to_id($self);
719
720   my $postback = bless sub {
721     $POE::Kernel::poe_kernel->post( $id, $event, [ @etc ], [ @_ ] );
722     return 0;
723   }, 'POE::Session::AnonEvent';
724
725   $anonevent_parent_id{$postback} = $id;
726   $POE::Kernel::poe_kernel->refcount_increment( $id, 'anon_event' );
727
728   # Tk blesses its callbacks, so we must present one that isn't
729   # blessed.  Otherwise Tk's blessing would divert our DESTROY call to
730   # its own, and that's not right.
731
732   return sub { $postback->(@_) } if USING_TK;
733   return $postback;
734 }
735
736 # Create a synchronous callback closure.  The return value will be
737 # passed to whatever is handed the callback.
738
739 sub callback {
740   my ($self, $event, @etc) = @_;
741   my $id = $POE::Kernel::poe_kernel->ID_session_to_id($self);
742
743   my $callback = bless sub {
744     $POE::Kernel::poe_kernel->call( $id, $event, [ @etc ], [ @_ ] );
745   }, 'POE::Session::AnonEvent';
746
747   $anonevent_parent_id{$callback} = $id;
748   $POE::Kernel::poe_kernel->refcount_increment( $id, 'anon_event' );
749
750   # Tk blesses its callbacks, so we must present one that isn't
751   # blessed.  Otherwise Tk's blessing would divert our DESTROY call to
752   # its own, and that's not right.
753
754   return sub { $callback->(@_) } if USING_TK;
755   return $callback;
756 }
757
758 1;
759
760 __END__
761
762 =head1 NAME
763
764 POE::Session - a generic event-driven task
765
766 =head1 SYNOPSIS
767
768   use POE; # auto-includes POE::Kernel and POE::Session
769
770   POE::Session->create(
771     inline_states => {
772       _start => sub { $_[KERNEL]->yield("next") },
773       next   => sub {
774         print "tick...\n";
775         $_[KERNEL]->delay(next => 1);
776       },
777     },
778   );
779
780   POE::Kernel->run();
781   exit;
782
783 POE::Session can also dispatch to object and class methods through
784 L</object_states> and L</package_states> callbacks.
785
786 =head1 DESCRIPTION
787
788 POE::Session and its subclasses translate events from POE::Kernel's
789 generic dispatcher into the particular calling conventions suitable for
790 application code.  In design pattern parlance, POE::Session classes
791 are adapters between L<POE::Kernel> and application code.
792
793 The L<sessions|POE::Kernel/Sessions> that POE::Kernel manages are more
794 like generic task structures.  Unfortunately these two disparate
795 concepts have virtually identical names.
796
797 =head2 A note on nomenclature
798
799 This documentation will refer to event handlers as "states" in certain
800 unavoidable situations.  Sessions were originally meant to be
801 event-driven state machines, but their purposes evolved over time.
802 Some of the legacy vocabulary lives on in the API for backward
803 compatibility, however.
804
805 Confusingly, L<POE::NFA> is a class for implementing actual
806 event-driven state machines.  Its documentation uses "state" in the
807 proper sense.
808
809 =head1 USING POE::Session
810
811 POE::Session has two main purposes.  First, it maps event names to the
812 code that will handle them.  Second, it maps a consistent event
813 dispatch interface to those handlers.
814
815 Consider the L</SYNOPSIS> for example.  A POE::Session instance is
816 created with two C<inline_states>, each mapping an event name
817 ("_start" and "next") to an inline subroutine.  POE::Session ensures
818 that C<$_[KERNEL]> and so on are meaningful within an event handler.
819
820 Event handlers may also be object or class methods, using
821 L</object_states> and L</package_states> respectively.  The create()
822 syntax is different than for C<inline_states>, but the calling
823 convention is nearly identical.
824
825 Notice that the created POE::Session object has not been saved to a
826 variable.  The new POE::Session object gives itself to POE::Kernel,
827 which then manages it and all the resources it uses.
828
829 It's possible to keep references to new POE::Session objects, but it's 
830 not usually necessary.  If an application is not careful about 
831 cleaning up these references you will create circular references, 
832 which will leak memory when POE::Kernel would normally destroy 
833 the POE::Session object.  It is recommended that you keep 
834 the session's C</ID> instead.
835
836 =head2 POE::Session's Calling Convention
837
838 The biggest syntactical hurdle most people have with POE is
839 POE::Session's unconventional calling convention.  For example:
840
841   sub handle_event {
842     my ($kernel, $heap, $parameter) = @_[KERNEL, HEAP, ARG0];
843     ...;
844   }
845
846 Or the use of CL</$_[KERNEL]>, CL</$_[HEAP]> and CL</$_[ARG0]> inline, as is done
847 in most examples.
848
849 What's going on here is rather basic.  Perl passes parameters into
850 subroutines or methods using the @_ array.  C<KERNEL>, C<HEAP>, C<ARG0> and
851 others are constants exported by POE::Session (which is included for
852 free when a program uses POE).
853
854 So CL</$_[KERNEL]> is an event handler's KERNELth parameter.  C<@_[HEAP,
855 ARG0]> is a slice of @_ containing the HEAPth and ARG0th parameters.
856
857 While this looks odd, it's perfectly plain and legal Perl syntax.  POE
858 uses it for a few reasons:
859
860 =over 4
861
862 =item 1
863
864 In the common case, passing parameters in C<@_> is faster than passing
865 hash or array references and then dereferencing them in the handler.
866
867 =item 2
868
869 Typos in hash-based parameter lists are either subtle runtime
870 errors or requires constant runtime checking.  Constants are either
871 known at compile time, or are clear compile-time errors.
872
873 =item 3
874
875 Referencing C<@_> offsets by constants allows parameters to move
876 in the future without breaking application code.
877
878 =item 4
879
880 Most event handlers don't need all of C<@_>.  Slices allow handlers to
881 use only the parameters they're interested in.
882
883 =back
884
885 =head2 POE::Session Parameters
886
887 Event handlers receive most of their runtime context in up to nine
888 callback parameters.  POE::Kernel provides many of them.
889
890 =head3 $_[OBJECT]
891
892 C<$_[OBJECT]> is $self for event handlers that are an object method.  It is
893 the class (package) name for class-based event handlers.  It is undef
894 for plain coderef callbacks, which have no special C<$self>-ish value.
895
896 C<OBJECT> is always zero, since C<$_[0]> is always C<$self> or C<$class>
897 in object and class methods.  Coderef handlers are called with
898 an C<undef> placeholder in C<$_[0]> so that the other offsets remain valid.
899
900 It's often useful for method-based event handlers to call other
901 methods in the same object.  C<$_[OBJECT]> helps this happen.
902
903   sub ui_update_everything {
904     my $self = $_[OBJECT];
905     $self->update_menu();
906     $self->update_main_window();
907     $self->update_status_line();
908   }
909
910 You may also use method inheritance
911
912   sub Amethod {
913     my $self = shift;
914     $self->SUPER::Amethod( @_ );
915     # ... more work ...
916   }
917
918 =head3 $_[SESSION]
919
920 C<$_[SESSION]> is a reference to the current session object.  This lets event
921 handlers access their session's methods.  Programs may also compare
922 C<$_[SESSION]> to CL</$_[SENDER]> to verify that intra-session events did not
923 come from other sessions.
924
925 C<$_[SESSION]> may also be used as the destination for intra-session
926 CL<post()|POE::Kernel/post> and CL<call()|POE::Kernel/call>.  CL<yield()|POE::Kernel/yield> is marginally more convenient and
927 efficient than C<post($_[SESSION], ...)> however.
928
929 It is bad form to access another session directly.  The recommended
930 approach is to manipulate a session through an event handler.
931
932   sub enable_trace {
933     my $previous_trace = $_[SESSION]->option( trace => 1 );
934     my $id = $_[SESSION]->ID;
935     if ($previous_trace) {
936       print "Session $id: dispatch trace is still on.\n";
937     }
938     else {
939       print "Session $id: dispatch trace has been enabled.\n";
940     }
941   }
942
943 =head3 $_[KERNEL]
944
945 The KERNELth parameter is always a reference to the application's
946 singleton L<POE::Kernel> instance.  It is most often used to call
947 POE::Kernel methods from event handlers.
948
949   # Set a 10-second timer.
950   $_[KERNEL]->delay( time_is_up => 10 );
951
952 =head3 $_[HEAP]
953
954 Every POE::Session object contains its own variable namespace known as
955 the session's C<HEAP>.  It is modeled and named after process memory
956 heaps (not priority heaps).  Heaps are by default anonymous hash
957 references, but they may be initialized in L<create()|/create> to be almost
958 anything.  POE::Session itself never uses C<$_[HEAP]>, although some POE
959 components do.
960
961 Heaps do not overlap between sessions, although create()'s "heap"
962 parameter can be used to make this happen.
963
964 These two handlers time the lifespan of a session:
965
966   sub _start_handler {
967     $_[HEAP]{ts_start} = time();
968   }
969
970   sub _stop_handler {
971     my $time_elapsed = time() - $_[HEAP]{ts_start};
972     print "Session ", $_[SESSION]->ID, " elapsed seconds: $elapsed\n";
973   }
974
975 =head3 $_[STATE]
976
977 The STATEth handler parameter contains the name of the event being
978 dispatched in the current callback.  This can be important since the
979 event and handler names may significantly differ.  Also, a single
980 handler may be assigned to more than one event.
981
982   POE::Session->create(
983     inline_states => {
984       one => \&some_handler,
985       two => \&some_handler,
986       six => \&some_handler,
987       ten => \&some_handler,
988       _start => sub {
989         $_[KERNEL]->yield($_) for qw(one two six ten);
990       }
991     }
992   );
993
994   sub some_handler {
995     print(
996       "Session ", $_[SESSION]->ID,
997       ": some_handler() handled event $_[STATE]\n"
998     );
999   }
1000
1001 It should be noted however that having event names and handlers names match
1002 will make your code easier to navigate.
1003
1004 =head3 $_[SENDER]
1005
1006 Events must come from somewhere.  C<$_[SENDER]> contains the currently
1007 dispatched event's source.
1008
1009 C<$_[SENDER]> is commonly used as a return address for responses.  It may
1010 also be compared against C<$_[KERNEL]> to verify that timers and other
1011 POE::Kernel-generated events were not spoofed.
1012
1013 This C<echo_handler()> reponds to the sender with an "echo" event that
1014 contains all the parameters it received.  It avoids a feedback loop by
1015 ensuring the sender session and event (STATE) are not identical to the
1016 current ones.
1017
1018   sub echo_handler {
1019     return if $_[SENDER] == $_[SESSION] and $_[STATE] eq "echo";
1020     $_[KERNEL]->post( $_[SENDER], "echo", @_[ARG0..$#_] );
1021   }
1022
1023 TODO - Document which events should have $_[SENDER] == $_[KERNEL].
1024 Probably in POE::Kernel.
1025
1026 =head3 $_[CALLER_FILE], $_[CALLER_LINE] and $_[CALLER_STATE]
1027
1028 These parameters are a form of caller(), but they describe where the
1029 currently dispatched event originated.  CALLER_FILE and CALLER_LINE
1030 are fairly plain.  CALLER_STATE contains the name of the event that
1031 was being handled when the event was created, or when the event
1032 watcher that ultimately created the event was registered.
1033
1034 TODO - Rename SENDER_FILE, SENDER_LINE, SENDER_STATE?
1035
1036 =head3 @_[ARG0..ARG9] or @_[ARG0..$#_]
1037
1038 Parameters $_[ARG0] through the end of @_ contain parameters provided
1039 by application code, event watchers, or higher-level libraries.  These
1040 parameters are guaranteed to be at the end of @_ so that @_[ARG0..$#_]
1041 will always catch them all.
1042
1043 $#_ is the index of the last value in @_.  Blame Perl if it looks odd.
1044 It's merely the $#array syntax where the array name is an underscore.
1045
1046 Consider
1047
1048   $_[KERNEL]->yield( ev_whatever => qw( zero one two three ) );
1049
1050 The handler for ev_whatever will be called with "zero" in $_[ARG0],
1051 "one" in $_[ARG1], and so on.  @_[ARG0..$#_] will contain all four
1052 words.
1053
1054   sub ev_whatever {
1055     $_[OBJECT]->whatever( @_[ARG0..$#_] );
1056   }
1057
1058 =head2 Using POE::Session With Objects
1059
1060 One session may handle events across many objects.  Or looking at it
1061 the other way, multiple objects can be combined into one session.  And
1062 what the heck---go ahead and mix in some inline code as well.
1063
1064   POE::Session->create(
1065     object_states => [
1066       $object_1 => { event_1a => "method_1a" },
1067       $object_2 => { event_2a => "method_2a" },
1068     ],
1069     inline_states => {
1070       event_3 => \&piece_of_code,
1071     },
1072   );
1073
1074 However only one handler may be assigned to a given event name.
1075 Duplicates will overwrite earlier ones.
1076
1077 event_1a is handled by calling C<< $object_1->method_1a(...) >>.  C<$_[OBJECT]>
1078 is C<$object_1> in this case.  C<$_[HEAP]> belongs to the session, which
1079 means anything stored there will be available to any other event
1080 handler regardless of the object.
1081
1082 event_2a is handled by calling C<< $object_2->method_2a(...) >>.  In this
1083 case CL</$_[OBJECT]> is $object_2.  C<$_[HEAP]> is the same anonymous hashref
1084 that was passed to the event_1a handler, though.  The methods are resolved
1085 when the event is handled (late-binding).
1086
1087 event_3 is handled by calling C<piece_of_code(...)>.  C<$_[OBJECT]> is C<undef>
1088 here because there's no object.  And once again, C<$_[HEAP]> is the same
1089 shared hashref that the handlers for event_1a and event_2a saw.
1090
1091 Interestingly, there's no technical reason that a
1092 single object can't handle events from more than one session:
1093
1094   for (1..2) {
1095     POE::Session->create(
1096       object_states => [
1097         $object_4 => { event_4 => "method_4" },
1098       ]
1099     );
1100   }
1101
1102 Now C<< $object_4->method_4(...) >> may be called to handle events from one of
1103 two sessions.  In both cases, C<$_[OBJECT]> will be C<$object_4>, but
1104 C<$_[HEAP]> will hold data for a particular session.
1105
1106 The same goes for inline states.  One subroutine may handle events
1107 from many sessions.  C<$_[SESSION]> and C<$_[HEAP]> can be used within the
1108 handler to easily access the context of the session in which the event
1109 is being handled.
1110
1111 =head1 PUBLIC METHODS
1112
1113 POE::Session has just a few public methods.
1114
1115 =head2 create LOTS_OF_STUFF
1116
1117 C<create()> starts a new session running.  It returns a new POE::Session
1118 object upon success, but most applications won't need to save it.
1119
1120 C<create()> invokes the newly started session's _start event handler
1121 before returning.
1122
1123 C<create()> also passes the new POE::Session object to L</POE::Kernel>.
1124 POE's kernel holds onto the object in order to dispatch events to it.
1125 POE::Kernel will release the object when it detects the object has
1126 become moribund.  This should cause Perl to destroy the object if
1127 application code has not saved a copy of it.
1128
1129 C<create()> accepts several named parameters, most of which are optional.
1130 Note however that the parameters are not part of a hashref.
1131
1132 TODO - Is it time to bring new() back as a synonym for create()?
1133 TODO PG - NO!  IMHO ->new implies simply creating the object, and 
1134 TODO that you have to hold onto the object.  ->create implies other actions
1135 TODO are happening, and that you don't want to hold on to it.
1136
1137 TODO - Provide forward-compatible "handler" options and methods as
1138 synonyms for the "state" versions currently supported?
1139 TODO PG - No, that's for 1.01
1140
1141 TODO - Add a "class_handlers" as a synonym for "package_handlers"?
1142 TODO PG - Maybe. However, to many synonyms can be a pain for an API.  
1143
1144 TODO - The above TODOs may be summarized: "deprecate old language"?
1145 TODO PG - Oh, you are thinking of deprecating the old language... erm... no?
1146
1147
1148
1149 TODO PG - I notice these =head3 are in alphabetical order.  I think
1150 TODO all the *_states options should be together.  Followed by heap, args,
1151 TODO options
1152
1153
1154 =head3 args => ARRAYREF
1155
1156 The C<args> parameter accepts a reference to a list of parameters that
1157 will be passed to the session's _start event handler in C<@_> positions
1158 C<ARG0> through C<$#_> (the end of C<@_>).
1159
1160 This example would print "arg0 arg1 etc.":
1161
1162   POE::Session->create(
1163     inline_states => {
1164       _start => sub {
1165         print "Session started with arguments: @_[ARG0..$#_]\n";
1166       },
1167     },
1168     args => [ 'arg0', 'arg1', 'etc.' ],
1169   );
1170
1171 =head3 heap => ANYTHING
1172
1173 The C<heap> parameter allows a session's heap to be initialized
1174 differently at instantiation time.  Heaps are usually anonymous
1175 hashrefs, but C<heap> may set them to be array references or even
1176 objects.
1177
1178 This example prints "tree":
1179
1180   POE::Session->create(
1181     inline_states => {
1182       _start => sub {
1183         print "Slot 0 = $_[HEAP][0]\n";
1184       },
1185     },
1186     heap => [ 'tree', 'bear' ],
1187   );
1188
1189 Be careful when initializing the heap to be something that doesn't behave
1190 like a hashref.  Some libraries assume hashref heap semantics, and
1191 they will fail if the heap doesn't work that way.
1192
1193 =head3 inline_states => HASHREF
1194
1195 C<inline_states> maps events names to the subroutines that will handle
1196 them.  Its value is a hashref that maps event names to the coderefs of
1197 their corresponding handlers:
1198
1199   POE::Session->create(
1200     inline_states => {
1201       _start => sub {
1202         print "arg0=$_[ARG0], arg1=$_[ARG1], etc.=$_[ARG2]\n";
1203       },
1204       _stop  => \&stop_handler,
1205     },
1206     args => [qw( arg0 arg1 etc. )],
1207   );
1208
1209 The term "inline" comes from the fact that coderefs can be inlined
1210 anonymous subroutines.
1211
1212 Be very careful with closures, however.  L</Beware circular references>.
1213
1214 =head3 object_states => ARRAYREF
1215
1216 C<object_states> associates one or more objects to a session and maps
1217 event names to the object methods that will handle them.  It's value
1218 is an C<ARRAYREF>; C<HASHREFs> would stringify the objects, ruining them
1219 for method invocation.
1220
1221 Here _start is handled by C<< $object->_session_start() >> and _stop triggers
1222 C<< $object->_session_stop() >>:
1223
1224   POE::Session->create(
1225     object_states => [
1226       $object => {
1227         _start => '_session_start',
1228         _stop  => '_session_stop',
1229       }
1230     ]
1231   );
1232
1233 POE::Session also supports a short form where the event and method
1234 names are identical.  Here _start invokes $object->_start(), and _stop
1235 triggers $object->_stop():
1236
1237   POE::Session->create(
1238     object_states => [
1239       $object => [ '_start', '_stop' ],
1240     ]
1241   );
1242
1243 Methods are verified when the session is created, but also resolved when the
1244 handler is called (late binding).  Most of the time, a method won't change. 
1245 But in some circumstance, such as dynamic inheritance, a method could
1246 resolve to a different subroutine.
1247
1248 =head3 options => HASHREF
1249
1250 POE::Session sessions support a small number of options, which may be
1251 initially set with the C<option> constructor parameter and changed at
1252 runtime with the C<option()|/option> mehtod.
1253
1254 C<option> takes a hashref with option =E<gt> value pairs:
1255
1256   POE::Session->create(
1257     ... set up handlers ...,
1258     options => { trace => 1, debug => 1 },
1259   );
1260
1261 This is equivalent to the previous example:
1262
1263   POE::Session->create(
1264     ... set up handlers ...,
1265   )->option( trace => 1, debug => 1 );
1266
1267 The supported options and values are documented with the C<option()|/option>
1268 method.
1269
1270 =head3 package_states => ARRAYREF
1271
1272 C<package_states> associates one or more classes to a session and maps
1273 event names to the class methods that will handle them.  Its function
1274 is analogous to C<object_states>, but package names are specified
1275 rather than objects.
1276
1277 In fact, the following documentation is a copy of the C<object_states>
1278 description with some word substitutions.
1279
1280 The value for C<package_states> is an B<ARRAYREF> to be consistent
1281 with C<object_states>, even though class names (also known as package names) are
1282 already strings, so it's not necessary to avoid stringifying them.
1283
1284 Here _start is handled by C<< $class_name->_session_start() >> and _stop
1285 triggers C<< $class_name->_session_stop() >>:
1286
1287   POE::Session->create(
1288     package_states => [
1289       $class_name => {
1290         _start => '_session_start',
1291         _stop  => '_session_stop',
1292       }
1293     ]
1294   );
1295
1296 POE::Session also supports a short form where the event and method
1297 names are identical.  Here _start invokes C<< $class_name->_start() >>, and
1298 _stop triggers C<< $class_name->_stop() >>:
1299
1300   POE::Session->create(
1301     package_states => [
1302       $class_name => [ '_start', '_stop' ],
1303     ]
1304   );
1305
1306 =head2 ID
1307
1308 C<ID()> returns the session instance's unique identifier.  This is an
1309 integer that starts at 1 and counts up forever, or until the number
1310 wraps around.
1311
1312 It's theoretically possible that a session ID will not be unique, but
1313 this requires at least 4.29 billion sessions to be created within a
1314 program's lifespan.  POE guarantees that no two sessions will have the
1315 same ID at the same time, however;  your computer doesn't have enough memory
1316 to store 4.29 billion session objects.
1317
1318 A session's ID is unique within a running process, but multiple
1319 processes are likely to have the same session IDs.  If a global ID is
1320 required, it will need to include both C<< $_[KERNEL]->ID >> and
1321 C<< $_[SESSION]->ID >>.
1322
1323 =head2 option OPTION_NAME [, OPTION_VALUE [, OPTION_NAME, OPTION_VALUE]... ]
1324
1325 C<option()> sets and/or retrieves the values of various session options.
1326 The options in question are implemented by POE::Session and do not
1327 have any special meaning anywhere else.
1328
1329 It may be called with a single OPTION_NAME to retrieve the value of
1330 that option.
1331
1332   my $trace_value = $_[SESSION]->option('trace');
1333
1334 C<option()> sets an option's value when called with a single OPTION_NAME,
1335 OPTION_VALUE pair.  In this case, C<option()> returns the option's
1336 previous value.
1337
1338   my $previous_trace = $_[SESSION]->option(trace => 1);
1339
1340 C<option()> may also be used to set the values of multiple options at
1341 once.  In this case, C<option()> returns all the specified options'
1342 previous values in an anonymous hashref:
1343
1344   my $previous_values = $_[SESSION]->option(
1345     trace => 1,
1346     debug => 1,
1347   );
1348
1349   print "Previous option values:\n";
1350   while (my ($option, $old_value) = each %$previous_values) {
1351     print "  $option = $old_value\n";
1352   }
1353
1354 POE::Session currently supports three options:
1355
1356 =head3 The "debug" option.
1357
1358 The "debug" option is intended to enable additional warnings when
1359 strange things are afoot within POE::Session.  At this time, there is
1360 only one additional warning:
1361
1362 =over 4
1363
1364 =item * 
1365
1366 Redefining an event handler does not usually cause a warning, but it
1367 will when the "debug" option is set.
1368
1369 =back
1370
1371 =head3 The "default" option.
1372
1373 Enabling the "default" option causes unknown events to become
1374 warnings, if there is no _default handler to catch them.
1375
1376 The class-level C<POE::Session::ASSERT_STATES> flag is implemented by
1377 enabling the "default" option on all new sessions.
1378
1379 =head3 The "trace" option.
1380
1381 Turn on the "trace" option to dump a log of all the events dispatched
1382 to a particular session.  This is a session-specific trace option that
1383 allows individual sessions to be debugged.
1384
1385 Session-level tracing also indicates when events are redirected to
1386 _default.  This can be used to discover event naming errors.
1387
1388 =head3 User-defined options.
1389
1390 C<option()> does not verify whether OPTION_NAMEs are known, so C<option()>
1391 may be used to store and retrieve user-defined information.
1392
1393 Choose option names with caution.  There is no established convention
1394 to avoid namespace collisions between user-defined options and future
1395 internal options.
1396
1397 =head2 postback EVENT_NAME, EVENT_PARAMETERS
1398
1399 C<postback()> manufactures callbacks that post POE events.  It returns an
1400 anonymous code reference that will post EVENT_NAME to the target
1401 session, with optional EVENT_PARAMETERS in an array reference in ARG0.
1402 Parameters passed to the callback will be sent in an array reference
1403 in ARG1.
1404
1405 In other words, ARG0 allows the postback's creator to pass context
1406 through the postback.  ARG1 allows the caller to return information.
1407
1408 This example creates a coderef that when called posts "ok_button" to
1409 C<$some_session> with ARG0 containing C<[ 8, 6, 7 ]>.
1410
1411   my $postback = $some_session->postback( "ok_button", 8, 6, 7 );
1412
1413 Here's an example event handler for "ok_button".
1414
1415   sub handle_ok_button {
1416     my ($creation_args, $called_args) = @_[ARG0, ARG1];
1417     print "Postback created with (@$creation_args).\n";
1418     print "Postback called with (@$called_args).\n";
1419   }
1420
1421 Calling $postback->(5, 3, 0, 9) would perform the equivalent of...
1422
1423   $poe_kernel->post(
1424     $some_session, "ok_button",
1425     [ 8, 6, 7 ],
1426     [ 5, 3, 0, 9 ]
1427   );
1428
1429 This would be displayed when "ok_button" was dispatched to
1430 handle_ok_button():
1431
1432   Postback created with (8 6 7).
1433   Postback called with (5 3 0 9).
1434
1435 Postbacks hold references to their target sessions.  Therefore
1436 sessions with outstanding postbacks will remain active.  Under every
1437 event loop except Tk, postbacks are blessed so that DESTROY may be
1438 called when their users are done.  This triggers a decrement on their
1439 reference counts, allowing sessions to stop.
1440
1441 Postbacks have one method, weaken(), which may be used to reduce their
1442 reference counts upon demand.  weaken() returns the postback, so you
1443 can do:
1444
1445   my $postback = $session->postback("foo")->weaken();
1446
1447 Postbacks were created as a thin adapter between callback libraries
1448 and POE.  The problem at hand was how to turn callbacks from the Tk
1449 graphical toolkit's widgets into POE events without subclassing
1450 several Tk classes.  The solution was to provide Tk with plain old
1451 callbacks that posted POE events.
1452
1453 Since C<postback()> and C<callback()> are Session methods, they may be
1454 called on C<$_[SESSION]> or C<$_[SENDER]>, depending on particular needs.
1455 There are usually better ways to interact between sessions than
1456 abusing postbacks, however.
1457
1458 Here's a brief example of attaching a L<Gtk2> button to a POE event
1459 handler:
1460
1461   my $btn = Gtk2::Button->new("Clear");
1462   $btn->signal_connect( "clicked", $_[SESSION]->postback("ev_clear") );
1463
1464 Points to remember: The session will remain alive as long as $btn
1465 exists and holds a copy of $_[SESSION]'s postback.  Any parameters
1466 passed by the Gtk2 button will be in ARG1.
1467
1468 =head2 callback EVENT_NAME, EVENT_PARAMETERS
1469
1470 callback() manufactures callbacks that use C<< $poe_kernel->call() >> to
1471 deliver POE events rather than C<< $poe_kernel->post() >>.  It is identical
1472 to C<postback()> in every other respect.
1473
1474 callback() was created to avoid race conditions that arise when
1475 external libraries assume callbacks will execute synchronously.
1476 L<File::Find> is an obvious (but not necessarily appropriate) example.
1477 It provides a lot of information in local variables that stop being
1478 valid after the callback.  The information would be unavailable by the
1479 time a post()ed event was dispatched.
1480
1481 =head2 get_heap
1482
1483 C<get_heap()> returns a reference to a session's heap.  This is the same
1484 value as C<$_[HEAP]> for the target session.  C<get_heap()> is intended to
1485 be used with C<$poe_kernel> and POE::Kernel's C<get_active_session()> so
1486 that libraries do not need these three common values explicitly passed
1487 to them.
1488
1489 That is, it prevents the need for:
1490
1491   sub some_helper_function {
1492     my ($kernel, $session, $heap, @specific_parameters) = @_;
1493     ...;
1494   }
1495
1496 Rather, helper functions may use:
1497
1498   use POE::Kernel; # exports $poe_kernel
1499   sub some_helper_function {
1500     my (@specific_parameters) = @_;
1501     my $session = $kernel->get_active_session();
1502     my $heap = $session->get_heap();
1503   }
1504
1505 This isn't very convenient for people writing libraries, but it makes
1506 the libraries much more convenient to use.
1507
1508 Using C<get_heap()> to break another session's encapsulation is strongly
1509 discouraged.
1510
1511 =head2 instantiate CREATE_PARAMETERS
1512
1513 C<instantiate()> creates and returns an empty POE::Session object.  It is
1514 called with the CREATE_PARAMETERS in a hash reference just before
1515 C<create()> processes them.  Modifications to the CREATE_PARAMETERS will
1516 affect how C<create()> initializes the new session.
1517
1518 Subclasses may override C<instantiate()> to alter the underlying
1519 session's structure.  They may extend C<instantiate()> to add new
1520 parameters to C<create()>.
1521
1522 Any parameters not recognized by C<create()> must be removed from the
1523 CREATE_PARAMETERS before C<instantiate()> returns.  C<create()> will
1524 L<croak|Carp/croak>
1525 if it discovers unknown parameters.
1526
1527 Be sure to return C<$self> from instantiate.
1528
1529   sub instantiate {
1530     my ($class, $create_params) = @_;
1531
1532     # Have the base class instantiate the new session.
1533     my $self = $class->SUPER::instantiate($create_parameters);
1534
1535     # Extend the parameters recognized by create().
1536     my $new_option = delete $create_parameters->{new_option};
1537     if (defined $new_option) {
1538       # ... customize $self here ...
1539     }
1540
1541     return $self;
1542   }
1543
1544 =head2 try_alloc START_ARGS
1545
1546 C<try_alloc()> calls POE::Kernel's C<session_alloc()> to allocate a session
1547 structure and begin managing the session within POE's kernel.  It is
1548 called at the end of POE::Session's C<create()>.  It returns C<$self>.
1549
1550 It is a subclassing hook for late session customization prior to
1551 C<create()> returning.  It may also affect the contents of C<@_[ARG0..$#_]>
1552 that are passed to the session's _start handler.
1553
1554   sub try_alloc {
1555     my ($self, @start_args) = @_;
1556
1557     # Perform late initialization.
1558     # ...
1559
1560     # Give $self to POE::Kernel.
1561     return $self->SUPER::try_alloc(@args);
1562   }
1563
1564 =head1 POE::Session's EVENTS
1565
1566 Please do not define new events that begin with a leading underscore.
1567 POE claims /^_/ events as its own.
1568
1569 POE::Session only generates one event, _default.  All other internal
1570 POE events are generated by (and documented in) POE::Kernel.
1571
1572 =head2 _default
1573
1574 _default is the C<AUTOLOAD> of event handlers.  If POE::Session can't
1575 find a handler at dispatch time, it attempts to redirect the event to
1576 _default's handler instead.
1577
1578 If there's no _default handler, POE::Session will silently drop the
1579 event unless the "default" option is set.
1580
1581 To preserve the original information, the original event is slightly
1582 changed before being redirected to the _default handler:  The original
1583 event parameters are moved to an array reference in ARG1, and the
1584 original event name is passed to _default in ARG0.
1585
1586   sub handle_default {
1587     my ($event, $args) = @_[ARG0, ARG1];
1588     print(
1589       "Session ", $_[SESSION]->ID,
1590       " caught unhandled event $event with (@$args).\n"
1591     );
1592   }
1593
1594 _default is quite flexible.  It may be used for debugging, or to
1595 handle dynamically generated event names without pre-defining their
1596 handlers.  In the latter sense, _default performs analogously to
1597 Perl's C<AUTOLOAD>.
1598
1599 _default may also be used as the default or "otherwise" clause of a
1600 switch statement.  Consider an input handler that throws events based
1601 on a command name:
1602
1603   sub parse_command {
1604     my ($command, @parameters) = split /\s+/, $_[ARG0];
1605     $_[KERNEL]->post( "cmd_$command", @parameters );
1606   }
1607
1608 A _default handler may be used to emit errors for unknown commands:
1609
1610   sub handle_default {
1611     my $event = $_[ARG0];
1612     return unless $event =~ /^cmd_(\S+)/;
1613     warn "Unknown command: $1\n";
1614   }
1615
1616 The _default behavior is implemented in POE::Session, so it may be
1617 different for other session types.
1618
1619 =head2 POE::Session's Debugging Features
1620
1621 POE::Session contains one debugging assertion, for now.
1622
1623 =head3 ASSERT_STATES
1624
1625 Setting ASSERT_STATES to true causes every Session to warn when they
1626 are asked to handle unknown events.  Session.pm implements the guts of
1627 ASSERT_STATES by defaulting the "default" option to true instead of
1628 false.  See the option() method earlier in this document for details
1629 about the "default" option.
1630
1631 TODO - It's not much of an assertion if it only warns.
1632
1633 =head1 SEE ALSO
1634
1635 L<POE::Kernel>.
1636
1637 The SEE ALSO section in L<POE> contains a table of contents covering
1638 the entire POE distribution.
1639
1640 =head1 BUGS
1641
1642 There is a chance that session IDs may collide after Perl's integer
1643 value wraps.  This can occur after as I<few> as 4.29 billion sessions.
1644
1645 =head2 Beware circular references
1646
1647 As you're probably aware, a circular reference is when a variable is
1648 part of a reference chain that eventually refers back to itself.  Perl
1649 will not reclaim the memory involved in such a reference chain until
1650 the chain is manually broken.
1651
1652 Here a POE::Session is created that refers to itself via an external
1653 scalar.  The event handlers import $session via closures which are in
1654 turn stored within $session.  Even if this session stops, the circular
1655 references will remain.
1656
1657   my $session;
1658   $session = POE::Session->create(
1659     inline_states => {
1660       _start => sub {
1661         $_[HEAP]->{todo} = [ qw( step1 step2 step2a ) ],
1662         $_[KERNEL]->post( $session, 'next' );
1663       },
1664       next => sub {
1665         my $next = shift @{ $_[HEAP]->{todo} };
1666         return unless $next;
1667         $_[KERNEL]->post( $session, $next );
1668       }
1669       # ....
1670     }
1671   );
1672
1673 Reduced to its essence:
1674
1675   my %event_handlers;
1676   $event_handler{_start} = sub { \%event_handlers };
1677
1678 Note also that a anonymous sub creates a closure on all lexical
1679 variables in the scope it was defined in, even if it doesn't reference
1680 them.  $session is still being held in a circular reference here:
1681
1682   my $self = $package->new;
1683   my $session;
1684   $session = POE::Session->create(
1685     inline_state => {
1686       _start => sub { $self->_start( @_[ARG0..$#_] ) }
1687     }
1688   );
1689
1690 To avoid this, a session may set an alias for itself.  Other parts of
1691 the program may then refer to it by alias.  In this case, one needn't
1692 keep track of the session themselves (POE::Kernel will do it anyway).
1693
1694   POE::Session->create(
1695     inline_states => {
1696       _start => sub {
1697         $_[HEAP]->{todo} = [ qw( step1 step2 step2a ) ],
1698         $_[KERNEL]->alias_set('step_doer');
1699         $_[KERNEL]->post( 'step_doer', 'next' );
1700       },
1701       next => sub {
1702         my $next = shift @{ $_[HEAP]->{todo} };
1703         return unless $next;
1704         $_[KERNEL]->post( 'step_doer', $next );
1705       }
1706       # ....
1707     }
1708   );
1709
1710 Aliases aren't even needed in the previous example because the session
1711 refers to itself.  One could instead use POE::Kernel's yield() method
1712 to post the event back to the current session:
1713
1714   next => sub {
1715     my $next = shift @{ $_[HEAP]->{todo} };
1716     return unless $next;
1717     $_[KERNEL]->yield( $next );
1718   }
1719
1720 Or the L<$_[SESSION]> parameter passed to every event handler, but
1721 yield() is more efficient.
1722
1723   next => sub {
1724     my $next = shift @{ $_[HEAP]->{todo} };
1725     return unless $next;
1726     $_[KERNEL]->post( $_[SESSION], $next );
1727   }
1728
1729 Along the same lines as L<$_[SESSION]>, a session can respond back to
1730 the sender of an event by posting to L<$_[SENDER]>.  This is great for
1731 responding to requests.
1732
1733 If a program must hold onto some kind of dynamic session reference,
1734 it's recommended to use the session's numeric ID rather than the
1735 object itself.  A session ID may be converted back into its object,
1736 but post() accepts session IDs as well as objects and aliases:
1737
1738   my $session_id;
1739   $session_id = POE::Session->create(
1740     inline_states => {
1741       _start => sub {
1742         $_[HEAP]->{todo} = [ qw( step1 step2 step2a ) ],
1743         $_[KERNEL]->post( $session_id, 'next' );
1744       },
1745       # ....
1746     }
1747   )->ID;
1748
1749 =head1 AUTHORS & COPYRIGHTS
1750
1751 Please see L<POE> for more information about authors and contributors.
1752
1753 =cut
1754
1755 # rocco // vim: ts=2 sw=2 expandtab
1756 # TODO - Edit.