Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MultiDispatch(3)      User Contributed Perl Documentation     MultiDispatch(3)

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

	 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' );

	 # run Foo::Bar's done state last.
	 $session->last( done => 'Foo::Bar' );

	 exit 0;

       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

       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.

       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()" 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()" 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()" 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()" 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.

       No doubt.

       See 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.

       Casey West <>

       Matt Cashner -- Many features inspired by his earlier modle,

       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.

       perl, POE::Session, POE.

perl v5.32.1			  2003-02-01		      MultiDispatch(3)


Want to link to this manual page? Use this URL:

home | help