The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
POE-Session-PlainCall-0.0301
River stage one • 4 direct dependents • 5 total dependents
++
/ POE::Session::PlainCall

NAME

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

SYNOPSIS

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

DESCRIPTION

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.

Package Methods

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'
    }

Functions

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 event handlers

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.

Nomenclature: state vs event

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.

METHODS

create

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"

state

    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 .. $#_ ];
        # ...
    }

EXPORT

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

$poe_kernel

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

poe

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

SEE ALSO

POE::Session, POE.

AUTHOR

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

COPYRIGHT AND LICENSE

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.