The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

POE::Session::MessageBased - a message-based (not @_ based) POE::Session

SYNOPSIS

        use POE::Kernel;
        use POE::Session::MessageBased;

        POE::Session::MessageBased->create(
                inline_states => {
                        _start => sub {
                                my $message = shift;
                                print "Started.\n";
                                $message->kernel->yield( count => 2 );
                        },
                        count => sub {
                                my ($message, $count) = @_;
                                print "Counted to $count.\n";
                                if ($count < 10) {
                                        $message->kernel->yield( count => ++$count );
                                }
                        },
                        _stop => sub {
                                print "Stopped.\n";
                        }
                },
        );

        POE::Kernel->run();

DESCRIPTION

POE::Session::MessageBased exists mainly to replace @_[KERNEL, etc.] with message objects that encapsulate various aspects of each event. It also exists as an example of a subclassed POE::Session, in case someone wants to create new callback or Session semantics.

People generally balk at the @_[KERNEL, etc.] calling convention that POE uses by default. The author defends the position that this calling convention is a simple combination of common Perl features. Interested people can read http://poe.perl.org/?POE_FAQ/calling_convention for a more detailed account.

Anyway, POE::Session::MessageBased subclasses POE::Session and works almost identically to it. The major change is the way event handlers (states) are called.

Inline (coderef) handlers gather their parameters like this.

        my ($message, @args) = @_;

Package and object-oriented handlers receive an additional parameter representing the package or object. This is part of the common calling convention that Perl uses.

        my ($package, $message, @args) = @_;  # Package states.
        my ($self, $message, @args) = @_;     # Object states.

The $message parameter is an instance of POE::Session::Message, which is not documented elsewhere. POE::Session::Message encapsulates every POE parameter and provides accessors for them.

        POE::Session             POE::Session::MessageBased
        ------------------------ -----------------------------------
        $_[OBJECT]               $package, or $self
        $_[SESSION]              $message->session
        $_[KERNEL]               $message->kernel
        $_[HEAP]                 $message->heap
        $_[STATE]                $message->state
        $_[SENDER]               $message->sender
        $_[CALLER_FILE]          $message->caller_file
        $_[CALLER_LINE]          $message->caller_line
        @_[ARG0..$#_]            $message->args (in list context)

You do not need to use POE::Session::Message yourself. It is included in POE::Session::MessageBased itself.

BUGS

$message->args() always returns a list: @_[ARG0..$#_]. It would be nice to return a list reference in scalar context.

BUG TRACKER

https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=POE-Session-MessageBased

REPOSITORY

http://github.com/rcaputo/poe-session-messagebased http://gitorious.org/poe-session-messagebased

OTHER RESOURCES

http://search.cpan.org/dist/POE-Session-MessageBased/

AUTHOR & LICENSE

POE::Session::MessageBased is Copyright 2002-2010 by Rocco Caputo. All rights are reserved. POE::Session::MessageBased is free software; you may redistribute it and/or modify it under the same terms as Perl itself.