NAME

POE::Kernel - manage events, selects and signals for POE::Session instances

SYNOPSIS

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;

DESCRIPTION

POE::Kernel in a nutshell.

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

PUBLIC METHODS

new POE::Kernel;

Creates a self-contained POE::Kernel object, and returns a reference to it. (Untested: It should be possible to run one Kernel per thread.)

$kernel->run()

Starts the kernel, and will not return until all its POE::Session instances have completed.

$kernel->select($handle, $state_r, $state_w, $state_e)

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.

$kernel->select_read($handle, $state)

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->select_write($handle, $state)

Manages just the "write" select(2) vector for a $handle owned by the currently active POE::Session. Works like 1/3 of $kernel-select()>.

$kernel->select_exception($handle, $state)

Manages just the "exception" select(2) vector for a $handle. owned by the currently active POE::Session. Works like 1/3 of $kernel-select()>.

$kernel->sig($signal, $state)

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.

$kernel->post($destination_session, $state_name, @etc)

Enqueues an event ($state) for the $destination_session. Additional parameters (@etc) can be passed along.

$kernel->state($state_name, $state_code)

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.

$kernel->alarm($state_name, $time, @etc)

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

Fractional values of $time are supported, including subsecond alarms, if Time::HiRes is available.

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

$kernel->delay($state_name, $delay, @etc)

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.

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.

PROTECTED METHODS

Not for general use.

$kernel->session_alloc($session)

Enqueues a _start event for a session. The session is added to the kernel just before the event is dispatched.

$kernel->session_free($session)

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.

PRIVATE METHODS

Not for general use.

DESTROY

Destroy the Kernel, and all associated resources. Nothing implemented yet.

_signal_handler

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.

$kernel->_check_session_resources($session)

Called after an event has been dispatched. This function stops sessions that have run out of things to do.

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

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.

$kernel->_dispatch_selects($select_handles, $selects_index)

This helper checks IO::Select objects for activity. It uses _dispatch_state to notify POE::Session instances immediately.

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

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

$kernel->_internal_select($session, $handle, $state, $select, $select_index)

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.

$kernel->_maybe_add_handle($handle)

Register a handle resource ($handle) with this kernel, if one is not already there.

$kernel->_maybe_remove_handle($handle)

Remove a handle resource ($handle) from this kernel, if one exists.

$kernel->_kernel_select($session, $handle, $state_r, $state_w, $state_e)

Register or remove read, write and exception states for a handle all at once.

EXAMPLES

Please see the tests directory that comes with the POE bundle.

BUGS

DESTROY is not implemented. This has not been a problem so far.

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.