POE::Session::PlainCall - POE sessions with plain perl calls

    Something->spawn( @args );

    POE::Kernel->run();

    package Something;
    use POE::Session::PlainCall;

    sub new {
        # Normal object constructor
    }

    sub spawn {
        my( $package, @args ) = @_;
        POE::Session::PlainCall->create(
                        package   => $package,
                        ctor_args => \@args,
                        states    => [ qw( _start load load_done ) ]
                    );
    }

    sub _start {
        my( $self ) = @_;
        poe->kernel->alias_set( $self->{alias} );
    }

    sub load {
        my( $self, $uri, $reply ) = @_;
        $self->{todo}{$uri} = [ poe->sender, $reply ];
        # Start doing some processing on $uri
    }

    sub load_done {
        my( $self, $uri ) = @_;
        # The processing of URI is complete
        my $reply = delete $self->{todo}{$uri};
        poe->kernel->post( @$reply, $req->reply );
    }

POE::Session::PlainCall provides standard perl object-oriented call signature to your POE event handlers. This allows for your methods and functions to be called either via POE events or as normal methods and functions. It also requires less typing then the POE argument constants.

Where a normal POE object method event handler would fetch it's arguments with:

    my( $self, $something, $backto ) = @_[ OBJECT, ARG0, ARG1 ];

POE::Session::PlainCall event handlers do it the normal way:

    my( $self, $something, $backto ) = @_;

Method overloading becomes much less fraught:

    # POE::Session
    shift->SUPER::method( @_ ); # wait, what if shift was already called?
    # POE::Session::PlainCall
    $self->SUPER::method( @_ );

The other elements of @_ (SENDER, HEAP, CALLER_STATE, etc) are available through a small object called poe.

    my $kernel = poe->kernel;       # $_[KERNEL] / $poe_kernel
    my $heap = poe->heap;           # $_[HEAP]
    my $from = poe->caller_state;   # $_[CALLER_STATE]
    # and so on

The one difference is that sender is in fact the sender session's ID. This is to help prevent you from keeping a reference to a POE::Session object.

    my $sender = poe->sender;       # $_[SENDER]->ID
    my $sender_ses = poe->kernel->ID_id_to_session( $sender );

However, if you really have a legitimate reason to want the session object, you may use SENDER.

    my $sender_ses = poe->SENDER;   # $_[SENDER]

But please remember to never keep a reference to a POE::Session object.

POE::Session::PlainCall also allows you to use package methods as event handlers:

    POE::Session::PlainCall->create(
                package_states => {
                        'Some::Package' => {
                                event => 'handler'
                            }
                    }
                # ...
            );

The package methods will be called as you would expect them to be:

    sub handler {
        my( $package, @args ) = @_;
        my $event = poe->state;         # $_[STATE]
        # $event would be 'event'
    }

But that's not all! Even though this package is called POE::Session::PlainCall, you can also use plain functions and coderefs as event handlers:

    POE::Session::PlainCall->create(
                inline_states => {
                        _start  => sub { poe->kernel->yield( 'work', @args ) },

                        work    => \&work,
                    }
                # ...
            );

The event handlers as you would expect them to be:

    sub work {
        my( @args ) = @_;
        my $event = poe->state;         # $_[STATE]
        # $event would be 'work'
    }

Wheels and other external modules can add or remove event handlers with POE::Kernel/state. These event handlers expect to be called with @_ as POE::Kernel would supply it. POE::Session::PlainCall has to know if a given event handler is internal (our call signature) or external (POE call signature). Internal event handlers are defined via create or state. External event handlers can be defined via state in POE::Kernel, which is what wheels and other components will already do.

For historical reasons POE refers to event handlers as state handlers. This nomenclature, while incorrect from a computer science standpoint, is preserved in POE::Session::PlainCall's API. However, the present documentation uses the more correct event handlers.

create() starts a new session running. It returns a new POE::Session object upon success. All the regular create in POE::Session named parameters are available.

You may also use:

object

    object => $obj

Object reference that the event handlers will be invoked on.

package

    package => 'Some::Package'

If you do not supply an object POE::Session::PlainCall will construct one by calling new on this package, with ctor_args as arguments.

ctor_args

    ctor_args => ARRAYREF

Arguments that are passed to package->new. If absent, an empty list is used.

states

    states => ARRAYREF
    states => HASHREF

states defines a list of methods to be called on your object when a given event happens.

In other words:

    POE::Session::PlainCall->create(
                    object => $object,
                    states => [ qw( one two ) ]
                );

Is the same as:

    POE::Session::PlainCall->create(
                    object_states => [ 
                            $object => [ qw( one two ) ] 
                    ]
                );

events

    events => ARRAYREF
    events => HASHREF

Syntactic sugar for states

    poe->session->state( $event => $object => $method );
    poe->session->state( $event );

To allow POE::Session::PlainCall to play nicely with other modules, specifically POE::Wheels, POE::Session::PlainCall must track which event handlers need the new call signature and which need the POE call signature.

New event handlers defined with POE::Kernel/state will be invoked with the POE call signature. New event handlers defined with /state will be invoked with the new call signature.

    poe->session->state( 'something', $self );
    # $self->something() is invoked like a normal method
    sub something {
        my( $self, @args ) = @_;
        # ...
    }




    POE::Kernel->state( 'other', $self );
    # $self->other() is inovked like a POE event handler
    sub other {
        my( $self, @args ) = @_[ OBJECT, ARG0 .. $#_ ];
        # ...
    }

POE::Session::PlainCall exports one function and one variable.

Courtesy export of $POE::Kernel::poe_kernel.

The poe function returns an object that you use to find additional information about an event method invocation:

object

The current object, Equivalent to $_[OBJECT]. undef for inline_states.

package

Package of the current object or simply the package for package_states event handlers. undef for inline_states.

session

The current session. Equivalent to $_[OBJECT].

    poe->session->state( $new_state => 'does_state' );

kernel

The POE kernel. Equivalent to $_[KERNEL] or $poe_kernel.

heap

The session heap. Equivalent to $_[HEAP].

state

The name of the currently running event. Equivalent to $_[STATE].

event

Syntactic sugar for state.

method

Name of the current method being invoked as an event handler. If you specify a hashref to events you can map an event handler to a method that doesn't carry the same name as event. If you specify an arrayref, then method returns the same thing as state.

No equivalent in POE, but this information is available through caller in perlfunc.

sender

The ID of the session that sent the current event. Equivalent to $_[SENDER]->ID.

SENDER

The session object that sent the current event. Equivalent to $_[SENDER].

caller_file

Name of the source code file where an event was posted from. Equivalent to $_[CALLER_FILE].

caller_line

Line within the source code file where an event was posted from. Equivalent to $_[CALLER_LINE].

caller_state

Name of the event that the current event was posted from. Equivalent to $_[CALLER_STATE].

POE::Session, POE.

Philip Gwyn, <gwyn-at-cpan.org<gt>

Copyright (C) 2009, 2011 by Philip Gwyn

Contains code from POE::Session. Please see POE for more information about authors and contributors.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.