INSTALLATION
To install this module type the following:
perl Makefile.PL
make
make test
make install # as root
NAME
POE::Session::MultiDispatch - Callback dispatch for session events.
SYNOPSIS
use POE qw[Session::MultiDispatch];
my $session = POE::Session::MultiDispatch->create(
inline_states => { _start => \&_start },
package_states => [ ... ],
object_states => [ ... ],
);
sub _start {
# Execute Foo::Bar's _start state first.
$_[SESSION]->first( _start => 'Foo::Bar' );
$_[SESSION]->stop;
}
# run Foo::Bar's done state last.
$session->last( done => 'Foo::Bar' );
$poe_kernel->run;
exit 0;
DESCRIPTION
POE::Session::MultiDispatch is a drop in replacement for POE::Session
that adds callback dispatch functionality to POE sessions. Each event
may have multiple handlers associated with it. Fine control over the
order of execution is available using helper methods that extend the
interface of a POE::Session.
POE::Session::MultiDispatch uses POE::Session as a base class. When
multiple callbacks are registered for an event, only the last callback
survives, all the others are clobbered. POE::Session::MultiDispatch is
much nicer to your registered callbacks, it keeps them all in the order
they were defined. When an event is triggered, all the callbacks are
then executed in that same order (unless you muck around with said
order).
Just what is the order? Last I checked it is "inline_states",
"package_states", and "object_states". As you can probably tell, that
order is by no means documented (here or anywhere else) as something
that is stead fast and solid. You should be careful and know what you're
doing if you intend to care too much about the order. Having said that,
my guess is that it won't change. But don't take my word for it.
All the real heavy lifting is still done in POE::Session. The interface
is exactly the same with the exception of the following additions.
Please read the POE::Session documentation for details on working with
POE sessions.
Methods
These methods have been added to POE::Sessions's interface. They can be
accessed from an event by using the session object stored in
"$_[SESSION]". Alternativley, you can use the object returned when
calling "create()" to call these methods.
stop
"stop()" tells the session dispatcher to stop processing callbacks
for this event, after the current one is finished processing.
go "go()" tells the session dispatcher to continue processing callbacks
for this event.
status
"status()" returns the current status of the event. It returns true
if the callback stack is set to be stopped, false if we're still
going through.
up EVENT, STATE, DIFFERENCE
"up()" moves a state up in the calling order for an event. The
difference is how far up to move it, the default is 1. A state is
given by name.
Inline states don't usually have a name, so one is assigned. Names
follow the convention 'inline_state_N' where 'N' is a number, zero
indexed. Package states are named using the package name. Object
states are named using the object name.
down EVENT, STATE, DIFFERENCE
"down()" moves a state down in the calling order for an event. The
difference is how far down to move it, the default is 1. A state is
given by name.
first EVENT, STATE
"first()" moves a state to the beginning of the callback stack.
last EVENT, STATE
"last()" moves a state to the end of the callback stack.
swap EVENT, STATE1, STATE2
"swap()" well... swaps the position of two states.
BUGS
No doubt.
See http://rt.cpan.org to report bugs.
Known Issues
The following is what I would consider known issues.
Updates to the call stack take place right away. When moving a state
for an event down in the stack, during that event, it will be called
twice. I think that isn't a good idea.
You can call "stop()" and "go()" from outside an event callback.
This is not useful and will almost guarantee a suprise when it's
time to start POE.
I'm sure I can guess reasonable defaults for "up()", "down()",
"first()", "last()", and event "swap" if I wanted to, but I haven't
even tried. This would be most useful.
Obviously the testing suite is more than lacking, but it does check
some basics, and it gives an example of usage. Please help me write
more.
AUTHOR
Casey West <casey@geeknest.com>
COPYRIGHT
Copyright (c) 2003 Casey West. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.
SEE ALSO
the perl manpage, the POE::Session manpage, the POE manpage.