POE::Kernel - an event driven threaded application kernel in Perl
POE comes with its own event loop, which is based on select() and written entirely in Perl. To use it, simply:
use POE;
POE's event loop will also work cooperatively with Gtk's, Tk's or Event's. POE will see either of these three modules if it's used first and change its behavior accordingly.
use Gtk; # or use Tk; or use Event; use POE;
Methods to manage the process' global Kernel instance:
# Retrieve the kernel's unique identifier. $kernel_id = $kernel->ID; # Run the event loop, only returning when it has no more sessions to # dispatche events to. $poe_kernel->run();
FIFO event methods:
# Post an event to an arbitrary session. $kernel->post( $session, $state_name, @state_args ); # Post an event back to the current session. $kernel->yield( $state_name, @state_args ); # Call a state synchronously, bypassing the event queue and # returning the state's return value. $state_return_value = $kernel->call( $session, $state_name, @state_args );
Alarm and delay methods:
# Post an event which will be delivered at a given Unix epoch time. # time. This clears previous timed events with the same state name. $kernel->alarm( $state_name, $epoch_time, @state_args ); # Post an additional alarm, leaving existing ones in the queue. $kernel->alarm_add( $state_name, $epoch_time, @state_args ); # Post an event which will be delivered after a delay, specified in # seconds hence. This clears previous timed events with the same # state name. $kernel->delay( $state_name, $seconds, @state_args ); # Post an additional delay, leaving existing ones in the queue. $kernel->delay_add( $state_name, $seconds, @state_args ); # Return the names of pending timed events. @state_names = $kernel->queue_peek_alarms( );
Symbolic name, or session alias methods:
# Set an alias for the current session. $status = $kernel->alias_set( $alias ); # Clear an alias for the current session: $status = $kernel->alias_remove( $alias ); # Resolve an alias into a session reference. Most POE::Kernel # methods do this for you. $session_reference = $kernel->alias_resolve( $alias ); # Resolve a session ID to a session reference. The alias_resolve # method does this as well, but this is faster. $session_reference = $kernel->ID_id_to_session( $session_id ); # Return a session ID for a session reference. It is functionally # equivalent to $session->ID. $session_id = $kernel->ID_session_to_id( $session_reference );
Filehandle watcher methods:
# Watch for read readiness on a filehandle. $kernel->select_read( $file_handle, $state_name ); # Stop watching a filehandle for read-readiness. $kernel->select_read( $file_handle ); # Watch for write readiness on a filehandle. $kernel->select_write( $file_handle, $state_name ); # Stop watching a filehandle for write-readiness. $kernel->select_write( $file_handle ); # Pause and resume write readiness watching. These have lower # overhead than full select_write() calls. $kernel->select_pause_write( $file_handle ); $kernel->select_resume_write( $file_handle ); # Pause and resume read readiness watching. These have lower # overhead than full select_read() calls. $kernel->select_pause_read( $file_handle ); $kernel->select_resume_read( $file_handle ); # Watch for out-of-bound (expedited) read readiness on a filehandle. $kernel->select_expedite( $file_handle, $state_name ); # Stop watching a filehandle for out-of-bound data. $kernel->select_expedite( $file_handle ); # Set and/or clear a combination of selects in one call. $kernel->select( $file_handle, $read_state_name, # or undef to clear it $write_state_name, # or undef to clear it $expedite_state_same, # or undef to clear it );
Signal watcher and generator methods:
# Generate an event when a particular signal arrives. $kernel->sig( $signal_name, $state_name ); # Stop watching for a signal. $kernel->sig( $signal_name ); # Post a signal through POE rather than through the underlying OS. # This only works within the same process. $kernel->signal( $session, $signal_name );
State management methods:
# Remove an existing state from the current Session. $kernel->state( $state_name ); # Add a new inline state, or replace an existing one. $kernel->state( $state_name, $code_reference ); # Add a new object or package state, or replace an existing one. # The object method will be the same as the state name. $kernel->state( $state_name, $object_ref_or_package_name ); # Add a new object or package state, or replace an existing one. # The object method may be different from the state name. $kernel->state( $state_name, $object_ref_or_package_name, $method_name );
External reference count methods:
# Increment a session's external reference count. $kernel->refcount_increment( $session_id, $refcount_name ); # Decrement a session's external reference count. $kernel->refcount_decrement( $session_id, $refcount_name );
Kernel data accessors:
# Return a reference to the currently active session, or to the # kernel if called outside any session. $session = $kernel->get_active_session();
Exported symbols:
# A reference to the global POE::Kernel instance. $poe_kernel # Some graphical toolkits (Tk) require at least one active widget in # order to use their event loops. POE allocates a main window so it # can function when using one of these toolkits. $poe_main_window
POE::Kernel is an event application kernel. It provides a lightweight, cooperatively-timesliced process model in addition to the usual basic event loop functions.
POE::Kernel cooperates with three external event loops. This is discussed after the public methods are described.
The POE manpage describes a shortcut for using several POE modules at once. It also includes a complete sample program with a brief walkthrough of its parts.
This section discusses in more detail the POE::Kernel methods that appear in the SYNOPSIS.
These functions manipulate the Kernel itself or retrieve information from it.
ID() returns the kernel's unique identifier.
print "The currently running Kernel is: $kernel->ID\n";
Every POE::Kernel instance is assigned an ID at birth. This ID tries to differentiate any given instance from all the others, even if they exist on the same machine. The ID is a hash of the machine's name and the kernel's instantiation time and process ID.
~/perl/poe$ perl -wl -MPOE -e 'print $poe_kernel->ID' rocco.homenet-39240c97000001d8
run() starts the kernel's event loop. It returns only after every session has stopped, or immediately if no sessions have yet been started.
#!/usr/bin/perl -w use strict; use POE; # ... start bootstrap session(s) ... $poe_kernel->run(); exit;
The run() method does not return a meaningful value.
FIFO events are dispatched in the order in which they were queued. These methods queue new FIFO events. A session will not spontaneously stop as long as it has at least one FIFO event in the queue.
post() enqueues an event to be dispatched to STATE_NAME in SESSION. If a PARAMETER_LIST is included, its values will be passed as arguments to STATE_NAME's handler.
$_[KERNEL]->post( $session, 'do_this' ); $_[KERNEL]->post( $session, 'do_that', $with_this, $and_this ); $_[KERNEL]->post( $session, 'do_that', @with_these ); POE::Session->new( do_this => sub { print "do_this called with $_[ARG0] and $_[ARG1]\n" }, do_that => sub { print "do_that called with @_[ARG0..$#_]\n" }, );
The post() method returns a boolean value indicating whether the event was enqueued successfully. $! will explain why the post() failed:
SESSION did not exist at the time of the post() call.
yield() enqueues an event to be dispatched to STATE_NAME in the same session. If a PARAMETER_LIST is included, its values will be passed as argumets to STATE_NAME's handler.
Events posted with yield() must propagate through POE's FIFO before they're dispatched. This effectively yields timeslices to other sessions which have events enqueued before it.
$kernel->yield( 'do_this' ); $kernel->yield( 'do_that', @with_these );
The yield() method does not return a meaningful value.
Sometimes it's necessary to invoke a state right away, for example to handle a time-critical external event that would be spoiled by the time an event propagated through POE's FIFO. The kernel's call() method provides for time-critical events.
call() bypasses the FIFO to call STATE_NAME in a SESSION, optionally with values from a PARAMETER_LIST. The values will be passed as arguments to STATE_NAME at dispatch time.
call() returns whatever STATE_NAME's handler does. The call() call's status is returned in $!, which is 0 for success or a nonzero reason for failure.
$return_value = $kernel->call( 'do_this_now' ); die "could not do_this_now: $!" if $!;
POE uses call() to dispatch some resource events without FIFO latency. Filehandle watchers, for example, would continue noticing a handle's readiness until the it was serviced by a state. This could result in several redundant readiness events being enqueued before the first one was dispatched.
Reasons why call() might fail:
SESSION did not exist at the time call() was called.
POE also manages timed events. These are events that should be dispatched after at a certain time or after some time has elapsed. A session will not spontaneously stop as long as it has at least one pending timed event. Alarms and delays always are enqueued for the current session, so a SESSION parameter is not needed.
The kernel manages two types of timed event. Alarms are set to be dispatched at a particular time, and delays are set to go off after a certain interval.
If Time::HiRes is installed, POE::Kernel will use it to increase the accuracy of timed events. The kernel will use the less accurate built-in time() if Time::HiRes isn't available.
POE::Kernel's alarm() is a single-shot alarm. It first clears all the timed events destined for STATE_NAME in the current session. It then may set a new alarm for STATE_NAME if EPOCH_TIME is included, optionally including values from a PARAMETER_LIST.
It is possible to post an alarm with an EPOCH_TIME in the past; in that case, it will be dispached immediately.
To clear existing timed events for 'do_this' and set a new alarm with parameters:
$kernel->alarm( 'do_this', $at_this_time, @with_these_parameters );
Clear existing timed events for 'do_that' and set a new alarm without parameters:
$kernel->alarm( 'do_that', $at_this_time );
To clear existing timed events for 'do_the_other_thing' without setting a new alarm:
$kernel->alarm( 'do_the_other_thing' );
This method will clear both alarms and delays.
POE::Kernel's alarm() returns 0 on success or a reason for its failure:
STATE_NAME is undefined.
alarm_add() sets an additional timed event for STATE_NAME in the current session without clearing pending timed events. The new alarm event will be dispatched no earlier than EPOCH_TIME.
To enqueue additional alarms for 'do_this':
$kernel->alarm_add( 'do_this', $at_this_time, @with_these_parameters ); $kernel->alarm_add( 'do_this', $at_this_time );
Additional alarms can be cleared with POE::Kernel's alarm() method.
alarm_add() returns 0 on success or a reason for failure:
Either STATE_NAME or EPOCH_TIME is undefined.
delay() is a single-shot delayed event. It first clears all the timed events destined for STATE_NAME in the current session. If SECONDS is included, it will set a new delay for STATE_NAME to be dispatched SECONDS seconds hence, optionally including values from a PARAMETER_LIST.
delay() uses whichever time(2) is available within POE::Kernel. That may be the more accurate Time::HiRes::time(), or perhaps not. Regardless, delay() will do the right thing without sessions testing for Time::HiRes themselves.
It's possible to post delays with negative SECONDS; in those cases, they will be dispatched immediately.
To clear existing timed events for 'do_this' and set a new delay with parameters:
$kernel->delay( 'do_this', $after_this_much_time, @with_these );
Clear existing timed events for 'do_that' and set a new delay without parameters:
$kernel->delay( 'do_this', $after_this_much_time );
To clear existing timed events for 'do_the_other_thing' without setting a new delay:
$kernel->delay( 'do_the_other_thing' );
delay() returns 0 on success or a reason for its failure:
delay()
delay_add() sets an additional delay for STATE_NAME in the current session without clearing pending timed events. The new delay will be dispatched no sooner than SECONDS seconds hence.
To enqueue additional delays for 'do_this':
$kernel->delay_add( 'do_this', $after_this_much_time, @with_these ); $kernel->delay_add( 'do_this', $after_this_much_time );
Additional alarms cas be cleared with POE::Kernel's delay() method.
delay_add() returns 0 on success or a reason for failure:
Either STATE_NAME or SECONDS is undefined.
queue_peek_alarms() returns a time-ordered list of state names from the current session that have pending timed events. If a state has more than one pending timed event, it will be listed that many times.
my @pending_timed_events = $kernel->queue_peek_alarms();
Every session is given a unique ID at birth. This ID combined with the kernel's own ID can uniquely identify a particular session anywhere in the world.
Sessions can also use the kernel's alias dictionary to give themselves symbolic names. Once a session has a name, it may be referred to by that name wherever a kernel method expects a session reference or ID.
Sessions with aliases are treated as daemons within the current program (servlets?). They are kept alive even without other things to do on the assumption that some other session will need their services.
Daemonized sessions may spontaneously self-destruct if no other sessions are active. This prevents "zombie" servlets from keeping a program running with nothing to do.
alias_set() sets an ALIAS for the current session. The ALIAS may then be used nearly everywhere a session reference or ID is expected. Sessions may have more than one alias, and each must be defined in a separate alias_set() call.
$kernel->alias_set( 'ishmael' ); # o/` A name I call myself. o/`
Having an alias "daemonizes" a session, allowing it to stay alive even when there's nothing for it to do. Sessions can use this to become autonomous services that other sessions refer to by name.
$kernel->alias_set( 'httpd' ); $kernel->post( httpd => set_handler => $uri_regexp => 'callback_event' );
alias_set() returns 0 on success, or a nonzero failure indicator:
The alias already is assigned to a different session.
alias_remove() clears an existing ALIAS from the current session. The ALIAS will no longer refer to this session, and some other session may claim it.
$kernel->alias_remove( 'Shirley' ); # And don't call me Shirley.
If a session is only being kept alive by its aliases, it will stop once they are removed.
alias_remove() returns 0 on success or a reason for its failure:
The Kernel's dictionary does not include the ALIAS being removed.
ALIAS belongs to some other session, and the current one does not have the authority to clear it.
alias_resolve() returns a session reference corresponding to its given ALIAS. This method has been overloaded over time, and now ALIAS may be several things:
An alias:
$session_reference = $kernel->alias_resolve( 'irc_component' );
A stringified session reference. This is a form of weak reference:
$blessed_session_reference = $kernel->alias_resolve( "$stringified_one" );
A numeric session ID:
$session_reference = $kernel->alias_resolve( $session_id );
alias_resolve() returns undef upon failure, setting $! to explain the error:
The Kernel's dictionary does not include ALIAS.
These functions work directly with session IDs. They are faster than alias_resolve() in the specific cases where they're useful.
ID_id_to_session() returns a session reference for a given numeric session ID.
$session_reference = ID_id_to_session( $session_id );
It returns undef if a lookup fails, and it sets $! to explain why the lookup failed.
The session ID does not refer to a running session.
ID_session_to_id() returns the ID associated with a session reference. This is virtually identical to SESSION_REFERENCE->ID, except that SESSION_REFERENCE may have been stringified. For example, this will work, provided that the session exists:
$session_id = ID_session_to_id( "$session_reference" );
ID_session_to_id() returns undef if a lookup fails, and it sets $! to explain why the lookup failed.
The session reference does not describe a session which is currently running.
Selects emit synchronous events when filehandles become ready. Synchronous events bypass the FIFO queue so that time-critical handlers may run right away.
Select handlers are expected to deal with filehandles so that they stop being ready. For example, a select_read() handler should try to read as much data from a filehandle as it can.
Select events include one parameter, ARG0, which contains the handle for the file that is ready. ARG0 and the other event handler parameter constants is covered in POE::Session.
ARG0
Sessions will not spontaneously stop as long as they are watching at least one filehandle.
select_read() starts or stops the kernel from watching to see if a filehandle can be read. The Kernel will call the handler for STATE_NAME whenever the filehandle has data to be read.
# Emit 'do_a_read' whenever $filehandle has data to be read. $kernel->select_read( $filehandle, 'do_a_read' ); # Stop watching for $filehandle to be readable. $kernel->select_read( $filehandle );
select_read() does not return a meaningful value.
select_write() starts or stops the kernel from watching to see if a filehandle can be written to. The Kernel will call the handler for STATE_NAME whenever the filehandle has room for new data to be written.
# Emit 'flush_data' whenever $filehandle can be written. $kernel->select_writ( $filehandle, 'flush_data' ); # Stop watching for $filehandle to be writable. $kernel->select_write( $filehandle );
select_write() does not return a meaningful value.
select_expedite() starts or stops the kernel from watching to see if a filehandle can be read out-of-band. The Kernel will call the handler for STATE_NAME whenever the filehandle has out-of-band data to be read.
# Emit 'do_an_oob_read' whenever $filehandle has data to be read. $kernel->select_expedite( $filehandle, 'do_an_oob_read' ); # Stop watching for expedited data on the $filehandle. $kernel->select_expedite( $filehandle );
select_expedite() does not return a meaningful value.
select_pause_write() temporarily pauses event generation when a FILE_HANDLE can be written to. select_resume_write() turns event generation back on.
These functions are more efficient than select_write() because they don't perform full resource management.
Pause and resume a filehandle's writable events:
$kernel->select_pause_write( $filehandle ); $kernel->select_resume_write( $filehandle );
These methods don't return meaningful values.
POE::Kernel's select() method alters a filehandle's read, write, and expedite selects at the same time. It's one method call more expensive than doing the same thing manually, but it's more convenient to code.
Defined state names set or change the events that will be emitted when the filehandle becomes ready. Undefined names clear those aspects of the watcher, stopping it from generating those types of events.
This sets all three types of events at once.
$kernel->select( $filehandle, 'do_read', 'do_flush', 'do_read_oob' );
This clears all three types of events at once. If this filehandle is the only thing keeping a session alive, then clearing its selects will stop the session.
$kernel->select( $filehandle );
This sets up a filehandle for read-only operation.
$kernel->select( $filehandle, 'do_read', undef, 'do_read_oob' );
This sets up a filehandle for write-only operation.
$kernel->select( $filehandle, undef, 'do_flush' );
This method does not return a meaningful value.
Sessions always receive events for signals. By default, signals are sent as _signal events. Signal "watchers" just map particular signals to events other than _signal.
The default _signal event is covered in more detail in POE::Session, along with the other standard events.
Signal watchers do not prevent sessions from spontaneously stopping.
Perl's signal handling is not safe by itself, and while POE tries its best to avoid signal problems, they will occur. The Event module implements safe signals, and POE will take advantage of them when Event is used before it.
Signal events propagate from a session's children up to it. This ensures that the leaves of a session's family tree are signalled before branches, and so on up to it. By the time a session receives a signal, all its descendents already have.
The Kernel acts as the ancestor of every session. Signalling it, as the operating system does, propagates signal events to every session.
It's possible to post fictitious signals from within POE. These are injected into the queue as if they came from the underlying operating system, but they are not limited to the signals that the system recognizes. POE uses fictitious signals to notify every session about certain global events.
Sessions that don't handle signal events may incur side effects. Event handlers tell the Kernel that they've handled a signal by returning true. The Kernel will consider a signal unhandled if its event handler returns false or doesn't exist. Either way, the signal will continue propagating up the ancestor tree.
There are three signal levels. They are listed from least to most strident.
Benign signals just notify sessions that signals have been caught. They have no side effects if they aren't handled.
Terminal signals will stop any session that doesn't handle them. The terminal system signals are: HUP, INT, KILL, QUIT and TERM. There is also one terminal fictitious signal, IDLE, which is used to notify leftover sessions that the program has run out of things to do.
Nonmaskable signals are similar to terminal signals, but they stop a session regardless of its handler's return value. There are two nonmaskable signals, both of which are fictitious:
ZOMBIE is fired if the terminal signal IDLE did not wake anything up; it's used to stop the remaining "zombie" sessions so that an inactive program will exit.
UIDESTROY is fired when a program's main or top-level widget has been destroyed. It's used to shut down programs when their interfaces have been closed.
Some system signals are handled specially. These are SIGCHLD/SIGCLD, SIGPIPE, and SIGWINCH.
POE::Kernel generates the same event when it receives either a SIGCHLD or SIGCLD signal from the operating system. This is done so sessions don't have to worry about which one they'll receive.
Additionally, the Kernel's SIGCHLD/SIGCLD handler determines the exiting child's process ID and return value on behalf of sessions. This lets several sessions receive that information without deciding which will call waitpid(2).
The SIGCHLD/SIGCHLD signal event comes with three custom parameters. ARG0 contains 'CHLD' even if SIGCLD was caught. ARG1 contains the child's process ID. ARG2 contains the child's return value from $?.
ARG1
ARG2
$?
Normally, system signals are posted to the Kernel so they can propagate to every session. SIGPIPE is an exception to this rule; it's posted to the session that's currently running. It still will propagate through that session's children, but it won't go beyond that parent/child tree.
Window resizes can generate a large number of signals very quickly, and this can easily cause perl to dump core. Because of this, POE ignores SIGWINCH outright unless it's using Event's safe signals.
Finally, here are POE::Kernel's signal methods themselves.
sig() registers or unregisters a STATE_NAME event for a particular SIGNAL_NAME. Signal names are the same as %SIG uses, with one exception: CLD is always delivered as CHLD, so handling CHLD will always do the right thing.
$kernel->sig( INT => 'event_sigint' );
To unregister a signal handler, just leave off the event it should generate, or pass it in undefined.
$kernel->sig( 'INT' ); $kernel->sig( INT => undef );
It's possible to register events for signals that the operating system will never generate. These "fictitious" signals can however be generated through POE's signal() method instead of kill(2).
The sig() method does not return a meaningful value.
signal() posts a signal event to a session through POE::Kernel rather than actually signalling the process through the operating system. Because it injects signal events directly into POE's Kernel, its SIGNAL_NAME doesn't have to be one the operating system understands.
For example, this posts a fictitious signal to some session:
$kernel->signal( $session, 'DIEDIEDIE' );
POE::Kernel's signal() method doesn't return a meaningful value.
This registers a widget with POE::Kernel such that the Kernel fires a UIDESTROY signal when the widget is closed or destroyed. The exact trigger depends on the graphical toolkit currently being used.
# Fire a UIDESTROY signal when this top-level window is deleted. $heap->{gtk_toplevel_window} = Gtk::Window->new('toplevel'); $kernel->signal_ui_destroy( $heap->{gtk_toplevel_window} );
State management methods let sessions hot swap their event handlers. It would be rude to change another session's states, so these methods only affect the current session.
Depending on how it's used, state() can add, remove, or update an event handler in the current session.
The simplest form of state() call deletes a handler for an event. This example removes the current session's "do_this" handler.
$kernel->state( 'do_this' );
The next form assigns a coderef to an event. If the event is already being handled, its old handler will be discarded. Any events already in POE's queue will be dispatched to the new handler.
Plain coderef handlers are also called "inline" handlers because they originally were defined with inline anonymous subs.
$kernel->state( 'do_this', \&this_does_it );
The third and fourth forms register or replace a handler with an object method. These handlers are called "object states". The third form maps an event to a method with the same name.
$kernel->state( 'do_this', $with_this_object );
The fourth form maps an event to a method with a different name.
$kernel->state( 'do_this', $with_this_object, $calling_this_method );
The fifth and sixth forms register or replace a handler with a package method. These handlers are called "package states". The fifth form maps an event to a function with the same name.
$kernel->state( 'do_this', $with_this_package );
The sixth form maps an event to a function with a different name.
$kernel->state( 'do_this', $with_this_package, $calling_this_function );
POE::Kernel's state() method returns 0 on success or a nonzero code explaining why it failed:
The Kernel doesn't recognize the currently active session. This happens when state() is called when no session is active.
The Kernel internally maintains reference counts on sessions that have active resource watchers. The reference counts are used to ensure that a session doesn't self-destruct while it's doing something important.
POE::Kernel's external reference counting methods let resource watcher developers manage their own reference counts. This lets the watchers keep their sessions alive when necessary.
refcount_increment() increments a session's external reference count, returning the reference count after the increment.
refcount_decrement() decrements a session's external reference count, returning the reference count after the decrement.
$new_count = $kernel->refcount_increment( $session_id, 'thingy' ); $new_count = $kernel->refcount_decrement( $session_id, 'thingy' );
Both methods return undef on failure and set $! to explain the failure.
There is no session SESSION_ID currently active.
The Kernel keeps some information which can be useful to other libraries. These functions provide a consistent, safe interface to the Kernel's internal data.
get_active_session() returns a reference to the session which is currently running. It returns a reference to the Kernel itself if no other session is running. This is one of the times where the Kernel pretends it's just another session.
my $active_session = $poe_kernel->get_active_session();
This is a convenient way for procedurally called libraries to get a reference to the current session. Otherwise a programmer would tediously need to include SESSION with every call.
SESSION
POE::Kernel supports four event loops. Three of them come from other modules, and the Kernel will adapt to whichever one is loaded before it. The Kernel's resource functions are designed to work the same regardless of the underlying event loop.
This is the default event loop. It is included in POE::Kernel and written in plain Perl for maximum portability.
Event is written in C for maximum performance. It requires either a C compiler or a binary distribtution for your platform, and its C nature allows it to implement safe signals.
use Event; use POE;
This loop allows POE to work in graphical programs using the Gtk-Perl library.
This loop allows POE to work in graphical programs using the Tk-Perl library.
External event loops expect plain coderefs as callbacks. POE::Session has a postback() method which will create callbacks these loops can use. Callbacks created with postback() are designed to post POE events when called, letting just about any loop's native callbacks work with POE. This includes widget callbacks and event watchers POE never dreamt of.
postback()
POE::Kernel contains a number of debugging assertions and traces.
Assertions remain quiet until something wrong has been detected; then they die right away with an error. They're mainly used for sanity checking in POE's test suite and to make the developers' lives easier. Traces, on the other hand, are never fatal, but they're terribly noisy.
Both assertions and traces incur performance penalties, so they should be used sparingly, if at all. They all are off by default. POE's test suite runs slower than normal because assertions are enabled during all the tests.
Assertion and tracing constants can be redefined before POE::Kernel is first used.
# Turn on everything. sub POE::Kernel::ASSERT_DEFAULT () { 1 } sub POE::Kernel::TRACE_DEFAULT () { 1 } use POE;
Assertions will be discussed first.
ASSERT_DEFAULT is used as the default value for all the other assert constants. Setting it true is a quick and reliable way to ensure all assertions are enabled.
ASSERT_GARBAGE turns on checks for proper garbage collection. In particular, it ensures that sessions have released all their resources before they're destroyed.
ASSERT_REFCOUNT enables checks for negative reference counts.
ASSERT_RELATIONS turns on parent/child referential integrity checks.
ASSERT_RETURNS causes POE::Kernel's methods to croak instead of returning error codes. See also TRACE_RETURNS if you don't want the Kernel to be so strict.
ASSERT_SELECT enables extra error checking in the Kernel's select logic. It has no effect if POE is using an external event loop.
ASSERT_SESSIONS makes it fatal to send an event to a nonexistent session.
ASSERT_USAGE enables runtime parameter checking in a lot of POE::Kernel method calls. These are disabled by default because they impart a hefty performance penalty.
Then there are the trace options.
TRACE_DEFAULT is used as the default value for all the other trace constants. Setting it true is a quick and reliable way to ensure all traces are enabled.
The music goes around and around, and it comes out here. TRACE_EVENTS enables messages that tell what happens to FIFO and alarm events: when they're queued, dispatched, or discarded, and what their states return.
TRACE_GARBAGE shows what's keeping sessions alive. It's useful for determining why a session simply refuses to die, or why it won't stick around.
TRACE_PROFILE switches on state profiling. This causes the Kernel to keep a count of every state it dispatches. It displays a frequency report when run() is about to return.
TRACE_QUEUE complements TRACE_EVENTS. When enabled, it traces the contents of POE's event queues, giving some insight into how events are ordered. This has become less relevant since the alarm and FIFO queues have separated.
TRACE_REFCOUNT enables debugging output whenever an external reference count changes.
TRACE_RETURNS enables carping whenever a Kernel method is about to return an error. See ASSERT_RETURNS if you'd like the Kernel to be stricter than this.
TRACE_SELECT enables or disables statistics about select()'s parameters and return values. It's only relevant when using POE's own select() loop.
select()
POE::Kernel exports two symbols for your coding enjoyment: $poe_kernel and $poe_main_window. POE::Kernel is implicitly used by POE itself, so using POE gets you POE::Kernel (and its exports) for free.
$poe_kernel
$poe_main_window
$poe_kernel contains a reference to the process' POE::Kernel instance. It's mainly useful for getting at the kernel from places other than states.
For example, programs can't call the Kernel's run() method without a reference, and they normally don't get references to the Kernel without being in a running state. This gets them going:
$poe_kernel->run();
It's also handy from within libraries, but states themselves receive KERNEL parameters and don't need to use $poe_kernel directly.
KERNEL
Some graphical toolkits (currently only Tk) require at least one widget be created before their event loops are usable. POE::Kernel allocates a main window in these cases, and exports a reference to that window in $poe_main_window. For all other toolkits, this exported variable is undefined.
Programs are free to use $poe_main_window for whatever needs. They may even assign a widget to it when using toolkits that don't require an initial widget (Gtk for now).
$poe_main_window is undefined if a graphical toolkit isn't used.
See: signal_ui_destroy
The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.
alarm() and delay() clear all the timed events for the current session and the named state. It's not possible to clear some and leave others.
There is no mechanism in place to prevent external reference count names from clashing.
Please see POE for more information about authors and contributors.
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
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.