NAME

POE::Session - a state machine, driven by POE::Kernel

SYNOPSIS

  new POE::Session(
    $kernel,
    '_start' => sub {
      my ($k, $me, $from) = @_;
      # initialize the session
    },
    '_stop'  => sub {
      my ($k, $me, $from) = @_;
      # shut down the session
    },
    '_default' => sub {
      my ($k, $me, $from, $state, @etc) = @_;
      # catches states for which no handlers are registered
      # returns 0 if the state is not handled; 1 if it is (for signal squelch)
      return 0;
    },
  );

  # ... or ...

  new POE::Session(
    $kernel,
    $object, \@methods,
    'state' => \&handler,
    $object_2, \@methods_2,
    'state2' => \&handler_2,
  );

DESCRIPTION

POE::Session builds an initial state table and registers it as a full session with POE::Kernel. The Kernel will invoke _start after the session is registered, and _stop just before destroying it. _default is called when a signal is dispatched to a nonexistent handler.

Regular states ('scalar' = $code_ref>) are invoked as: &$code_ref($kernel, $namespace, $source_session, @$etc).

Object states ($object, \@event_handler_methods) are invoked as $object-$method($kernel, $namespace, $source_session, @$etc)>. Don't forget that $_[0] is a reference to the object in this case.

PUBLIC METHODS

new POE::Session($kernel, $name, $handler, $name, $handler, ...);

Build an initial state table (list of events), and register it with a $kernel.

Normal events/states are named after $name, and handled by CODE references in $handler.

Then there is the $object, \@methods format. $object is a blessed object, and \@methods is a list of events that the object will handle. Methods are named after their corresponding events. When using this syntax, remember that Perl's "=> operator stringifies its left operand.

The Session will hold a copy of the $object reference for each registered method. These references will be freed when the Session exits, and the referenced $object should be garbage collected at that time. The references are also freed when handlers are deallocated, and deallocating the last handler in an object will free that object before the Session is destroyed.

new(...) returns a reference to the new Session, which should be discarded promptly since the $kernel will maintain it. Keeping extra copies of the reference will prevent sessions from being freed when they are done.

SPECIAL NAMESPACE VARIABLES

_debug

This will set the runtime debugging level for the POE::Session.

Currently it only toggles (true/false) displaying states as they are dispatched, and maybe some minor harmless warnings.

SPECIAL STATES

All states except _start are optional. Events will be discarded quietly for any states that do not exist.

_start ($kernel, $namespace, $from)

Informs a POE::Session that it has been added to a POE::Kernel.

$kernel is a reference to the kernel that owns this session; $namespace is a reference to a hash that has been set aside for this session to store persistent information; $from is the session that sent the _start event (usually a POE::Kernel).

This is the only required state.

_stop ($kernel, $namespace, $from)

Informs a POE::Session that is about to be removed from a POE::Kernel. Anything in $namespace that Perl cannot garbage-collect should be destroyed here to avoid leaking memory.

$kernel, $namespace and $from are the same as for _start.

_default ($kernel, $namespace, $from, $state, @etc)

Informs a POE::Session that it has received an event for which no state has been registered. Without a _default state, POE::Kernel will silently drop undeliverable events.

$kernel, $namespace and $from are the same as for _start. $state is the state name that would have received the event. @etc are any additional parameters (other than $kernel, $namespace and $from) that would have been sent to $state.

If the _default state handles the event, return 1. If the _default state does not handle the event, return 0. This allows default states to squelch signals by handling them.

_child ($kernel, $namespace, $departing_session)

Informs a POE::Session that a session it created (or inherited) is about to be stopped. One use for this is maintaining a limited pool of parallel sub-sessions, starting new sessions when old ones go away.

$kernel and $namespace are the same as for _start. $departing_session is a reference to the session going away.

_parent ($kernel, $namespace, $new_parent)

Informs a POE::Session that its parent session is stopping, and that its new parent will be $new_parent.

$kernel and $namespace are the same as for _start. $new_parent is the new parent of this session.

SPECIAL STATE CLASSES

Special States

These states are generated by POE::Kernel and mainly deal with session management. Construction, destruction, and parent/child relationships.

Signal States

These are states that have been registered as %SIG handlers by POE::Kernel::sig(...).

Signal states are invoked with these paramters:

$kernel

This is the kernel that is managing this session.

$namespace

This is a hash into which the session can store "persistent" data. The $namespace hash is preserved in the Kernel until the Session stops.

$from

This is the Session that generated this state. Under normal circumstances, this will be the Kernel.

$signal_name

The name of the signal that caused this state event to be sent. It does not include the "SIG" prefix (e.g., 'ZOMBIE'; not 'SIGZOMBIE').

Signal states should return 0 if they do not handle the signal, or 1 if the signal is handled. Sessions will be stopped if they do not handle terminal signals that they receive. Terminal signals currently are defined as SIGQUIT, SIGTERM, SIGINT, SIGKILL and SIGHUP in Kernel.pm.

Note: _default is also the default signal handle. It can prevent most signals from terminating a Session.

There is one "super-terminal" signal, SIGZOMBIE. It is sent to all tasks when the Kernel detects that nothing can be done. The session will be terminated after this signal is delivered, whether or not the signal is handled.

Select States

These states are registerd to signal(2) logic by POE::Kernel::select(...) and related functions.

Select states are invoked with these parameters:

$kernel

Same as it ever was.

$namespace

Same as it ever was.

$from

Same as it ever was.

$handle

This is the IO::Handle object that is ready for processing. How it should be processed (read, write or exception) depends on the previous $kernel->select(...) call.

Alarm States

These are states that accept delayed events sent by POE::Kernel::alarm(...), but any state can do this, so why is it listed separately?

$kernel

Same as it ever was.

$namespace

Same as it ever was.

$from

Same as it ever was.

@etc

Parameters passed to $kernel->alarm(...) when it was called will be sent to the alarm handler here.

Wheel States

These states are added to and removed from sessions whenever POE::Wheel derivatives are created or destroyed. They can last the entire life of a session, or they can come and go depending on the current needs of a session.

PROTECTED METHODS

$session->_invoke_state($kernel, $source_session, $state, \@etc)

Called by POE::Kernel to invoke state $state generated from $source_session with a list of optional parameters in \@etc. Invokes the _default state if it exists and $state does not.

Returns 1 if the event was dispatched, or 0 if the event had nowhere to go.

$session->register_state($state, $handler)

Called back by POE::Kernel to add, change or remove states from this session.

PRIVATE METHODS

DESTROY

Destroys the session. Deletes internal storage.

EXAMPLES

All the programs in tests/ use POE::Session, but especially see tests/sessions.perl and tests/forkbomb.perl.

BUGS

None known.

CONTACT AND COPYRIGHT

Copyright 1998 Rocco Caputo <troc@netrus.net>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.