POE::Kernel - manage events, selects and signals for POE::Session instances
POE::Session
use POE::Kernel; use POE::Session; $kernel = new POE::Kernel; new POE::Session(...); # one or more starting sessions $kernel->run(); # run sessions; serve events, selects, signals exit;
POE::Kernel in a nutshell.
POE::Kernel
It queues and delivers events to instances of POE::Session. Alarms are implemented as delayed events.
It offers select(2) services for files based on IO::Handle. They are implemented as immediate events, allowing sessions to bypass the queue entirely.
It catches signals and passes them as events to POE::Session instances.
It allows sessions to modify their event handlers. Extensions add and remove features by altering code in the caller.
Creates a self-contained POE::Kernel object, and returns a reference to it. (Untested: It should be possible to run one Kernel per thread.)
Starts the kernel, and will not return until all its POE::Session instances have completed.
Manages read, write and exception bits for a IO::Handle object owned by the currently active POE::Session. Defined states are added, and undefined ones are removed. When select(2) unblocks, the named event handlers (states) are invoked with $handle to take care of file activity.
IO::Handle
$handle
Manages just the "read" select(2) vector for a $handle owned by the currently active POE::Session. Works like 1/3 of $kernel-select()>.
$kernel-
Manages just the "write" select(2) vector for a $handle owned by the currently active POE::Session. Works like 1/3 of $kernel-select()>.
Manages just the "exception" select(2) vector for a $handle. owned by the currently active POE::Session. Works like 1/3 of $kernel-select()>.
Add or remove an event handler for the signal named in $signal} (same names as with %SIG). If $state is defined, then that state will be invoked when a specified signal. If $state is undefined, then the $SIG{$signal} handler is removed.
$signal}
%SIG
$state
$SIG{$signal}
Enqueues an event ($state) for the $destination_session. Additional parameters (@etc) can be passed along.
$destination_session
@etc
Registers a CODE reference ($state_code) for the event $state_name in the currently active POE::Session. If $state_code is undefined, then the named state will be removed.
$state_code
$state_name
Posts a state for a specific future time, with possible extra parameters. The time is represented as system time, just like time() returns. If $time is zero, then the alarm is cleared. Otherwise $time is clipped to no earlier than the current time().
time()
$time
Fractional values of $time are supported, including subsecond alarms, if Time::HiRes is available.
Time::HiRes
The current session will receive its $state_name event when time() catches up with $time.
Any given $state_name may only have one alarm pending. Setting a subsequent alarm for an existing state will clear all pending events for that state, even if the existing states were not enqueued by previous calls to alarm().
alarm()
Posts a state for $delay seconds in the future. This is an alias for $kernel-alarm($state_name, time() + $time, @etc)>. If $delay is undefined, then the delay is removed.
$delay
The main benefit for having the alias within Kernel.pm is that it uses whichever time() that POE::Kernel does. Otherwise, POE::Session code may be using a different version of time(), and subsecond delays may not be working as expected.
Not for general use.
Enqueues a _start event for a session. The session is added to the kernel just before the event is dispatched.
_start
Immediately dispatches a _stop event for a session. Doing this from sessions is not recommended. Instead, post a _stop message $kernel-post($me, '_stop'), which does the same thing but with two advantages: you can use the $me namespace if a blessed $session is not known, and it allows any queued events to be processed before the session is torn down.
_stop
$kernel-post($me, '_stop')
$me
$session
Destroy the Kernel, and all associated resources. Nothing implemented yet.
Registered as a handle for allmost all the signals in %SIG. It enqueues _signal events for every active POE::Kernel. The kernels relay _signal events to every POE::Session registered for them.
_signal
Called after an event has been dispatched. This function stops sessions that have run out of things to do.
Immediately dispatches an event (state transition) from a source session to a destination session. \@etc is an optional array reference that holds additional information that the session expects.
\@etc
This helper checks IO::Select objects for activity. It uses _dispatch_state to notify POE::Session instances immediately.
IO::Select
_dispatch_state
Combines the parameters into an event (state transition), and enqueues it to be delivered at a particular time. Alarms are implemented as events that are scheduled to happen at a future time.
$time is clipped to time().
The guts of select(2) management. Registers or removes a select bit for IO::Handle. When select unblocks, an event ($state) will be immediately dispatched to $session, along with the $handle so it can be taken care of.
Register a handle resource ($handle) with this kernel, if one is not already there.
Remove a handle resource ($handle) from this kernel, if one exists.
Register or remove read, write and exception states for a handle all at once.
Please see the tests directory that comes with the POE bundle.
DESTROY is not implemented. This has not been a problem so far.
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.
1 POD Error
The following errors were encountered while parsing the POD:
A non-empty Z<>
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.