Philip Gwyn
and 1 contributors


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


    Something->spawn( @args );


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

    sub new {
        # Normal object constructor

    sub spawn {
        my( $package, @args ) = @_;
                        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.

Package Methods

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

                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:

                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.



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 => $obj

Object reference that the event handlers will be invoked on.

    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 => ARRAYREF

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

    states => ARRAYREF
    states => HASHREF

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

In other words:

                    object => $object,
                    states => [ qw( one two ) ]

Is the same as:

                    object_states => [ 
                            $object => [ qw( one two ) ] 
    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:


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


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


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

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

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


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


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


Syntactic sugar for "state".


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.


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


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


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


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


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


POE::Session, POE.


Philip Gwyn, <<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.