GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  POE::SESSION::MULTIDISPATCH (3)

.ds Aq ’

NAME

POE::Session::MultiDispatch - Callback dispatch for session events.

CONTENTS

SYNOPSIS



  use POE qw[Session::MultiDispatch];
 
  my $session = POE::Session::MultiDispatch->create(
    inline_states  => { _start => \&_start },
    package_states => [ ... ],
    object_states  => [ ... ],
  );

  sub _start {
    # Execute Foo::Bars _start state first.
    $_[SESSION]->first( _start => Foo::Bar );
    $_[SESSION]->stop;
  }

  # run Foo::Bars 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.
o 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.
o 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.
o 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.
o 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.

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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MULTIDISPATCH (3) 2003-02-01

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.