README
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