POE::Session - a state machine, driven by POE::Kernel
POE::Kernel
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 }, );
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.
POE::Session
_start
_stop
_default
States are invoked as: &$state_code_ref($kernel, $namespace, $source_session, @$etc).
&$state_code_ref($kernel, $namespace, $source_session, @$etc)
Build an initial state table, and register it with a $kernel. Returns undef always since $kernel maintains it.
$kernel
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.
All states except _start are optional. Events will be discarded quietly for any states that do not exist.
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).
$namespace
$from
This is the only required state.
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.
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.
$state
@etc
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.
$departing_session
Informs a POE::Session that its parent session is stopping, and that its new parent will be $new_parent.
$new_parent
$kernel and $namespace are the same as for _start. $new_parent is the new parent of this session.
These states are generated by POE::Kernel and mainly deal with session management. Construction, destruction, and parent/child relationships.
These are states that have been registered as %SIG handlers by POE::Kernel::sig(...).
%SIG
POE::Kernel::sig(...)
These states are registerd to signal(2) logic by POE::Kernel::select(...) and related functions.
signal(2)
POE::Kernel::select(...)
These are states that accept delayed events sent by POE::Kernel::alarm(...), but any state can do this, so why is it listed separately?
POE::Kernel::alarm(...)
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.
POE::Wheel
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.
$source_session
\@etc
Called back by POE::Kernel to add, change or remove states from this session.
Destroys the session. Deletes internal storage.
All the programs in tests/ use POE::Session, but especially see tests/sessions.perl and tests/forkbomb.perl.
None known.
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.
To install POE, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE
CPAN shell
perl -MCPAN -e shell install POE
For more information on module installation, please visit the detailed CPAN module installation guide.