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>

THANKS

Matt Cashner -- Many features inspired by his earlier modle, POE::Session::Cascading.