POE::Session 0.9989

POE::Session is a Perl module for event driven abstract state machine.

SYNOPSIS

# Import POE::Session constants.
use POE::Session;

POE::Session->create(

# Inline or coderef states.
inline_states => {
state_one => &coderef_one,
state_two => sub { ... },
},

# Plain and mapped object states.
object_states => [
$object_one => [ state_three, state_four, state_five ],
$object_two => { state_nine => method_nine },
],

# Plain and mapped package states.
package_states => [
$package_one => [ state_six, state_seven, state_eight ],
$package_two => { state_ten => method_ten },
],

# Parameters for the sessions _start state.
args => [ argument_zero, argument_one, ... ],

# Initial options. See the option() method.
options => %options,

# Change the sessions heap representation.
heap => [ ],
);
Other methods:
# Retrieve a sessions unique identifier.
$session_id = $session->ID;

# Retrieve a reference to the sessions heap.
$session_heap = $session->get_heap();

# Set or clear session options.
$session->option( trace => 1, default => 1 );
$session->option( trace );

# Create a postback, then invoke it and pass back additional
# information.
$postback_coderef = $session->postback( $state_name, @state_args );
$postback_coderef->( @additional_args );

# Or do the same thing synchronously
$callback_coderef = $session->callback( $state_name, @state_args );
$retval = $callback_coderef->( @additional_args );

POE::Session combines a runtime context with an event driven state machine. Together they implement a simple cooperatively timesliced thread.
Sessions receive their timeslices as events from POE::Kernel. Each event has two fields, a state name and a session identifier. These fields describe the code to run and the context to run it in, respectively.

Events carry several other fields which will be discussed in the "Predefined Event Fields" section.

States are re-entrant since they are invoked with their runtime contexts. Although its not usually necessary, this re-entrancy allows a single function to be bound to several different sessions, under several different state names.
As sessions run, they post new events through the Kernel. These events may be for themselves or other sessions, in which case they act as a form of inter-session communications. The Kernel can also generate events based on external conditions such as file activity or the passage of time.

POE provides some convenient built-in states with special meanings. They will be covered later on in the "Predefined States" section.