1INSTALLATION 2 3To install this module type the following: 4 5 perl Makefile.PL 6 make 7 make test 8 make install # as root 9 10NAME 11 POE::Session::MultiDispatch - Callback dispatch for session events. 12 13SYNOPSIS 14 use POE qw[Session::MultiDispatch]; 15 16 my $session = POE::Session::MultiDispatch->create( 17 inline_states => { _start => \&_start }, 18 package_states => [ ... ], 19 object_states => [ ... ], 20 ); 21 22 sub _start { 23 # Execute Foo::Bar's _start state first. 24 $_[SESSION]->first( _start => 'Foo::Bar' ); 25 $_[SESSION]->stop; 26 } 27 28 # run Foo::Bar's done state last. 29 $session->last( done => 'Foo::Bar' ); 30 31 $poe_kernel->run; 32 exit 0; 33 34DESCRIPTION 35 POE::Session::MultiDispatch is a drop in replacement for POE::Session 36 that adds callback dispatch functionality to POE sessions. Each event 37 may have multiple handlers associated with it. Fine control over the 38 order of execution is available using helper methods that extend the 39 interface of a POE::Session. 40 41 POE::Session::MultiDispatch uses POE::Session as a base class. When 42 multiple callbacks are registered for an event, only the last callback 43 survives, all the others are clobbered. POE::Session::MultiDispatch is 44 much nicer to your registered callbacks, it keeps them all in the order 45 they were defined. When an event is triggered, all the callbacks are 46 then executed in that same order (unless you muck around with said 47 order). 48 49 Just what is the order? Last I checked it is "inline_states", 50 "package_states", and "object_states". As you can probably tell, that 51 order is by no means documented (here or anywhere else) as something 52 that is stead fast and solid. You should be careful and know what you're 53 doing if you intend to care too much about the order. Having said that, 54 my guess is that it won't change. But don't take my word for it. 55 56 All the real heavy lifting is still done in POE::Session. The interface 57 is exactly the same with the exception of the following additions. 58 Please read the POE::Session documentation for details on working with 59 POE sessions. 60 61 Methods 62 63 These methods have been added to POE::Sessions's interface. They can be 64 accessed from an event by using the session object stored in 65 "$_[SESSION]". Alternativley, you can use the object returned when 66 calling "create()" to call these methods. 67 68 stop 69 "stop()" tells the session dispatcher to stop processing callbacks 70 for this event, after the current one is finished processing. 71 72 go "go()" tells the session dispatcher to continue processing callbacks 73 for this event. 74 75 status 76 "status()" returns the current status of the event. It returns true 77 if the callback stack is set to be stopped, false if we're still 78 going through. 79 80 up EVENT, STATE, DIFFERENCE 81 "up()" moves a state up in the calling order for an event. The 82 difference is how far up to move it, the default is 1. A state is 83 given by name. 84 85 Inline states don't usually have a name, so one is assigned. Names 86 follow the convention 'inline_state_N' where 'N' is a number, zero 87 indexed. Package states are named using the package name. Object 88 states are named using the object name. 89 90 down EVENT, STATE, DIFFERENCE 91 "down()" moves a state down in the calling order for an event. The 92 difference is how far down to move it, the default is 1. A state is 93 given by name. 94 95 first EVENT, STATE 96 "first()" moves a state to the beginning of the callback stack. 97 98 last EVENT, STATE 99 "last()" moves a state to the end of the callback stack. 100 101 swap EVENT, STATE1, STATE2 102 "swap()" well... swaps the position of two states. 103 104BUGS 105 No doubt. 106 107 See http://rt.cpan.org to report bugs. 108 109 Known Issues 110 111 The following is what I would consider known issues. 112 113 Updates to the call stack take place right away. When moving a state 114 for an event down in the stack, during that event, it will be called 115 twice. I think that isn't a good idea. 116 117 You can call "stop()" and "go()" from outside an event callback. 118 This is not useful and will almost guarantee a suprise when it's 119 time to start POE. 120 121 I'm sure I can guess reasonable defaults for "up()", "down()", 122 "first()", "last()", and event "swap" if I wanted to, but I haven't 123 even tried. This would be most useful. 124 125 Obviously the testing suite is more than lacking, but it does check 126 some basics, and it gives an example of usage. Please help me write 127 more. 128 129AUTHOR 130 Casey West <casey@geeknest.com> 131 132COPYRIGHT 133 Copyright (c) 2003 Casey West. All rights reserved. This program is free 134 software; you can redistribute it and/or modify it under the same terms 135 as Perl itself. 136 137SEE ALSO 138 the perl manpage, the POE::Session manpage, the POE manpage. 139 140