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 aPOE::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 aPOE::Kernel
).This is the only required state.
- _stop ($kernel, $namespace, $from)
-
Informs a
POE::Session
that is about to be removed from aPOE::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 byPOE::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 byPOE::Kernel::select(...)
and related functions.Select states are invoked with these parameters:
- 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 _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.