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.