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

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.

States are invoked as: &$state_code_ref($kernel, $namespace, $source_session, @$etc).

PUBLIC METHODS

new POE::Session($kernel, 'state' => sub { ... }, ....);

Build an initial state table, and register it with a $kernel. Returns undef always since $kernel maintains it.

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.

_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(...).

Select States

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

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?

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 _defaul state if it exists and $state does not.

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