Casey West > POE-Session-MultiDispatch > POE::Session::MultiDispatch

Download:
POE-Session-MultiDispatch-1.3.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 1.3   Source  

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.

AUTHOR ^

Casey West <casey@geeknest.com>

THANKS ^

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

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 ^

perl, POE::Session, POE.

syntax highlighting: