This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: POE/Driver, Next: POE/Driver/SysRW, Prev: POE/Component/UserBase, Up: Module List POE Read/Write Abstraction ************************** NAME ==== POE::Driver - POE Read/Write Abstraction SYNOPSIS ======== $driver = new POE::Driver::Something(); $arrayref_of_data_chunks = $driver->get($filehandle); $queue_octets = $driver->put($arrayref_of_data_chunks); $queue_octets = $driver->flush($filehandle); $queue_messages = $driver->get_out_messages_buffered(); DESCRIPTION =========== Drivers provide a generic interface for low-level file I/O. Wheels use this interface to read and write files, sockets, and things, without having to know the details for each. In theory, drivers should be pretty much interchangeable. In practice, there seems to be an impermeable barrier between the different SOCK_* types. PUBLIC DRIVER METHODS ===================== These methods are the generic Driver interface. Specific drivers may have additional methods. * POE::Driver::new() The new() method creates and initializes a new driver. Specific drivers may have different constructor parameters. * POE::Driver::get($filehandle) The get() method immediately tries to read information from a filehandle. It returns a reference to an array of received data chunks. The array may be empty if nothing could be read. The array reference it returns is a suitable parameter to POE::Filter::get(). get() returns undef on an error. Wheels usually call the get() method from their read select states. * POE::Driver::put($arrayref_of_data_chunks) The put() method places raw data into the driver's output queue. Some drivers may flush data from the put() method. It accepts a reference to an array of writable chunks, and it returns the number of octets in its output queue. Wheels usually call the put() method from their own put() methods. * POE::Driver::flush($filehandle) The flush() method attempts to flush some data from the driver's output queue to the file. It returns the number of octets remaining in the output queue after the flush. Wheels usually call the flush() method from their write select states. * POE::Driver::get_out_messages_buffered() Returns the number of messages in the driver's output buffer. If the top message is partially flushed, it is still counted as a full one. SEE ALSO ======== POE::Driver::SysRW BUGS ==== There is no POE::Driver::SendRecv AUTHORS & COPYRIGHTS ==================== Please see the POE manpage.  File: pm.info, Node: POE/Driver/SysRW, Next: POE/Filter, Prev: POE/Driver, Up: Module List POE sysread/syswrite Abstraction ******************************** NAME ==== POE::Driver::SysRW - POE sysread/syswrite Abstraction SYNOPSIS ======== $driver = new POE::Driver::SysRW(); $arrayref_of_data_chunks = $driver->get($filehandle); $queue_octets = $driver->put($arrayref_of_data_chunks); $queue_octets = $driver->flush($filehandle); $queue_messages = $driver->get_out_messages_buffered(); DESCRIPTION =========== This driver provides an abstract interface to sysread and syswrite. PUBLIC METHODS ============== * POE::Driver::SysRW::new( ... ); The new() constructor accepts one optional parameter: BlockSize => $block_size This is the maximum data size that the SysRW driver will read at once. If omitted, $block_size defaults to 512. SEE ALSO ======== POE::Driver BUGS ==== Oh, probably some. AUTHORS & COPYRIGHTS ==================== Please see the POE manpage.  File: pm.info, Node: POE/Filter, Next: POE/Filter/Block, Prev: POE/Driver/SysRW, Up: Module List POE Protocol Abstraction ************************ NAME ==== POE::Filter - POE Protocol Abstraction SYNOPSIS ======== $filter = new POE::Filter::Something(); $arrayref_of_logical_chunks = $filter->get($arrayref_of_raw_chunks_from_driver); $arrayref_of_streamable_chunks_for_driver = $filter->put($arrayref_of_logical_chunks); DESCRIPTION =========== Filters provide a generic interface for low and medium level protocols. Wheels use this interface to communicate in different protocols without necessarily having to know the details for each. In theory, filters should be interchangeable. In practice, stream and block protocols tend to be incompatible. PUBLIC FILTER METHODS ===================== These methods are the generic Filter interface. Specific filters may have additional methods. * POE::Filter::new() The new() method creates and initializes a new filter. Specific filters may have different constructor parameters. * POE::Filter::get($arrayref_of_raw_chunks_from_driver) The get() method translates raw stream data into logical units. It accepts a reference to an array of raw stream chunks as returned from POE::Driver::get(). It returns a reference to an array of complete logical data chunks. There may or may not be a 1:1 correspondence between raw stream chunks and logical data chunks. Some filters may buffer partial logical units until they are completed in subsequent get() calls. The get() method returns a reference to an empty array if the stream doesn't include enough information for a complete logical unit. * POE::Filter::put($arrayref_of_logical_chunks) The put() method takes a reference to an array of logical data chunks. It serializes them into streamable representations suitable for POE::Driver::put(). It returns the raw streamable versions in a different array reference. * POE::Filter::get_pending() The get_pending() method is part of wheels' buffer swapping mechanism. It clears the filter's input buffer and returns a copy of whatever was in it. It doesn't manipulate filters' output buffers because they don't exist (filters expect to receive entire logical data chunks from sessions, so there's no reason to buffer data and frame it). *Please note that relying on the get_pending() method in networked settings require some forethought.* For instance, POE::Filter::Stream never buffers data. Switching filters usually requires some sort of flow control, otherwise it's easy to cause a race condition where one side sends the wrong type of information for the other side's current filter. Framing errors will ensue. Consider the following: Assume a server and client are using POE::Filter::Line. When the client asks the server to switch to POE::Filter::Reference, it should wait for the server's ACK or NAK before changing its own filter. This lets the client avoid sending referenced data while the server still is parsing lines. Here's something else to consider. Programs using POE::Wheel::put() on TCP sockets cannot rely on each put data chunk arriving separately on the receiving end of the connection. This is because TCP coalesces packets whenever possible, to minimize packet header overhead. Most systems have a way to disable the TCP delay (Nagle's algorithm), in one form or another. If you need this, please check your C headers for the TCP_NODELAY socket option. It's neither portable, nor supported in Perl by default. The filterchange.perl sample program copes with flow control while switching filters. SEE ALSO ======== POE::Filter::HTTPD; POE::Filter::Line; POE::Filter::Reference; POE::Filter::Stream BUGS ==== Oh, probably some. AUTHORS & COPYRIGHTS ==================== Please see the POE manpage.  File: pm.info, Node: POE/Filter/Block, Next: POE/Filter/CTCP, Prev: POE/Filter, Up: Module List POE Block Protocol Abstraction ****************************** NAME ==== POE::Filter::Block - POE Block Protocol Abstraction SYNOPSIS ======== $filter = new POE::Filter::Block( BlockSize => 1024 ); $arrayref_of_blocks = $filter->get($arrayref_of_raw_chunks_from_driver); $arrayref_of_streamable_chunks_for_driver = $filter->put($arrayref_of_blocks); $arrayref_of_streamable_chunks_for_driver = $filter->put($single_block); $arrayref_of_leftovers = $filter->get_pending(); DESCRIPTION =========== The Block filter translates streams to and from blocks of bytes. If a block size is specified when the filter is constructed, then fixed-length blocks of that size will be built or parsed. Otherwise it builds and parses length-prepended variable-sized blocks. Programs that specify block sizes less than 1 byte are soundly spanked, just as they deserve. Extra bytes are buffered until more bytes arrive to complete a block. PUBLIC FILTER METHODS ===================== Please see POE::Filter. SEE ALSO ======== POE::Filter; POE::Filter::HTTPD; POE::Filter::Reference; POE::Filter::Stream; POE::Filter::Line BUGS ==== None known. AUTHORS & COPYRIGHTS ==================== The Block filter was contributed by Dieter Pearcey, with changes by Rocco Caputo. Please see the POE manpage for more information about authors and contributors.  File: pm.info, Node: POE/Filter/CTCP, Next: POE/Filter/HTTPD, Prev: POE/Filter/Block, Up: Module List A POE-based parser for the IRC protocol. **************************************** NAME ==== POE::Filter::CTCP - A POE-based parser for the IRC protocol. SYNOPSIS ======== my $filter = POE::Filter::IRC->new(); my @events = @{$filter->get( [ @lines ] )}; my @msgs = @{$filter->put( [ @messages ] )}; DESCRIPTION =========== POE::Filter::CTCP converts normal text into thoroughly CTCP-quoted messages, and transmogrifies CTCP-quoted messages into their normal, sane components. Rather what you'd expect a filter to do. A note: the CTCP protocol sucks bollocks. If I ever meet the fellow who came up with it, I'll shave their head and tattoo obscenities on it. Just read the "specification" at http://cs-pub.bu.edu/pub/irc/support/ctcp.spec and you'll hopefully see what I mean. Quote this, quote that, quote this again, all in different and weird ways... and who the hell needs to send mixed CTCP and text messages? WTF? It looks like it's practically complexity for complexity's sake. Anyhow, enough ranting. Onto the rest of the docs... METHODS ======= * new Creates a new POE::Filter::CTCP object. Duh. :-) Takes no arguments. * get Takes an array reference containing one or more lines of CTCP-quoted text. Returns an array reference of processed, pasteurized events. * put Takes an array reference of CTCP messages to be properly quoted. This doesn't support CTCPs embedded in normal messages, which is a brain-dead hack in the protocol, so do it yourself if you really need it. Returns an array reference of the quoted lines for sending. AUTHOR ====== Dennis "fimmtiu" Taylor, . SEE ALSO ======== The documentation for POE and POE::Component::IRC.  File: pm.info, Node: POE/Filter/HTTPD, Next: POE/Filter/IRC, Prev: POE/Filter/CTCP, Up: Module List POE HTTP 1.0 (Server Side) Protocol Abstraction *********************************************** NAME ==== POE::Filter::HTTPD - POE HTTP 1.0 (Server Side) Protocol Abstraction SYNOPSIS ======== $httpd = new POE::Filter::HTTPD(); $arrayref_with_http_response_as_string = $httpd->put($full_http_response_object); $arrayref_with_http_request_object = $line->get($arrayref_of_raw_data_chunks_from_driver); DESCRIPTION =========== The HTTPD filter parses the first HTTP 1.0 request from an incoming stream into an HTTP::Request object. It accepts a single HTTP::Response object, and returns a HTTP 1.0 stream for sending. Please see the documentation for HTTP::Request and HTTP::Response. PUBLIC FILTER METHODS ===================== Please see POE::Filter. SEE ALSO ======== POE::Filter; POE::Filter::Line; POE::Filter::Reference; POE::Filter::Stream; HTTP::Request; HTTP::Response BUGS ==== Keep-alive is not supported. AUTHORS & COPYRIGHTS ==================== The HTTPD filter was contributed by Artur Bergman. Please see the POE manpage for more information about authors and contributors.  File: pm.info, Node: POE/Filter/IRC, Next: POE/Filter/Line, Prev: POE/Filter/HTTPD, Up: Module List A POE-based parser for the IRC protocol. **************************************** NAME ==== POE::Filter::IRC - A POE-based parser for the IRC protocol. SYNOPSIS ======== my $filter = POE::Filter::IRC->new(); my @events = @{$filter->get( [ @lines ] )}; DESCRIPTION =========== POE::Filter::IRC takes lines of raw IRC input and turns them into weird little data structures, suitable for feeding to POE::Component::IRC. They look like this: { name => 'event name', args => [ some info about the event ] } METHODS ======= * new Creates a new POE::Filter::IRC object. Duh. :-) Takes no arguments. * get Takes an array reference full of lines of raw IRC text. Returns an array reference of processed, pasteurized events. * put There is no "put" method. That would be kinda silly for this filter, don't you think? AUTHOR ====== Dennis "fimmtiu" Taylor, . SEE ALSO ======== The documentation for POE and POE::Component::IRC.  File: pm.info, Node: POE/Filter/Line, Next: POE/Filter/Reference, Prev: POE/Filter/IRC, Up: Module List POE Line Protocol Abstraction ***************************** NAME ==== POE::Filter::Line - POE Line Protocol Abstraction SYNOPSIS ======== $filter = POE::Filter::Line->new(); $arrayref_of_lines = $filter->get($arrayref_of_raw_chunks_from_driver); $arrayref_of_streamable_chunks_for_driver = $filter->put($arrayref_of_lines); $arrayref_of_streamable_chunks_for_driver = $filter->put($single_line); $arrayref_of_leftovers = $filter->get_pending(); # To use a literal newline terminator for input and output: $filter = POE::Filter::Line->new( Literal => "\x0D\x0A" ); # To terminate input lines with a string regexp: $filter = POE::Filter::Line->new( InputRegexp => '[!:]', OutputLiteral => "!" ); # To terminate input lines with a compiled regexp (requires perl # 5.005 or newer): $filter = POE::Filter::Line->new( InputRegexp => qr/[!:]/, OutputLiteral => "!" ); # To autodetect the input line terminator: $filter = POE::Filter::Line->new( InputLiteral => undef ); DESCRIPTION =========== The Line filter translates streams to and from newline-separated lines. The lines it returns do not contain newlines. Neither should the lines given to it. By default, incoming newline are recognized with a regular subexpression: `/(\x0D\x0A?|\x0A\x0D?)/'. This encompasses all sorts of variations on CR and LF, but it has a problem. If incoming data is broken between CR and LF, then the second character will be interpreted as a blank line. This doesn't happen often, but it can happen often enough. *People are advised to specify custom newlines in applications where blank lines are significant.* By default, outgoing lines have traditional network newlines attached to them: `"\x0D\x0A"', or CRLF. The `OutputLiteral' parameter is used to specify a new one. PUBLIC FILTER METHODS ===================== Please see POE::Filter. SEE ALSO ======== POE::Filter; POE::Filter::HTTPD; POE::Filter::Reference; POE::Filter::Stream BUGS ==== The default input newline regexp has a race condition where incomplete newlines can generate spurious blank input lines. AUTHORS & COPYRIGHTS ==================== Please see the POE manpage.  File: pm.info, Node: POE/Filter/Reference, Next: POE/Filter/Stream, Prev: POE/Filter/Line, Up: Module List POE Freeze/Thaw Protocol Abstraction ************************************ NAME ==== POE::Filter::Reference - POE Freeze/Thaw Protocol Abstraction SYNOPSIS ======== $filter = new POE::Filter::Reference(); $arrayref_of_perl_references = $filter->get($arrayref_of_raw_chunks_from_driver); $arrayref_of_serialized_perl_references = $filter->put($arrayref_of_perl_references); DESCRIPTION =========== The "put" half of this filter freezes referenced Perl structures into serialized versions for sending. The "get" half of this filter thaws serialized Perl structures back into references. This provides a handy way to ship data between processes and systems. Serializers should recognize that POE::Filter::Reference is used to ship data between systems with different byte orders. PUBLIC FILTER METHODS ===================== * POE::Filter::Reference::new( ... ) The new() method creates and initializes the reference filter. It accepts optional parameters to specify a serializer and the use of compression. The serializer may be a package or an object; the compression flag is a Perl "boolean" value. A package serializer must have a thaw() function, and it must have either a freeze() or nfreeze() function. If it has both freeze() and nfreeze(), then Filter::Reference will use nfreeze() for portability. These functions match Storable and FreezeThaw's call signatures. An object serializer must have a thaw() method. It also must have either a freeze() or nfreeze() method. If it has both freeze() and nfreeze(), then Filter::Reference will use nfreeze() for portability. The thaw() method accepts $self and a scalar; it should return a reference to the reconstituted data. The freeze() and nfreeze() methods receive $self and a reference; they should return a scalar with the reference's serialized representation. If the serializer parameter is undef, a default one will be used. This lets programs specify compression without having to worry about naming a serializer. For example: # Use the default filter (either Storable or FreezeThaw). my $filter = new POE::Filter::Reference(); # Use Storable explicitly, specified by package name. my $filter = new POE::Filter::Reference('Storable'); # Use an object. my $filter = new POE::Filter::Reference($object); # Use an object, with compression. my $filter = new POE::Filter::Reference($object, 1); # Use the default serializer, with compression. my $filter = new POE::Filter::Reference(undef, 1); The new() method will try to require any packages it needs. The default behavior is to try Storable first, FreezeThaw second, and fail if neither is present. This is rapidly becoming moot because of the PM_PREREQ entry in Makefile.PL, which makes CPAN and "make" carp about requirements even when they aren't required. * POE::Filter::Reference::get($frozen_data) The get() method thaws streamed, frozen data into references. References will be blessed, if necessary. If the reference points to an object, be sure the receiving end has use'd it before calling its methods. * POE::Filter::Reference::put($reference) The put() method freezes references and returns their serialized, streamable representations. SEE ALSO ======== POE::Filter; POE::Filter::HTTPD; POE::Filter::Line; POE::Filter::Stream BUGS ==== Oh, probably some. AUTHORS & COPYRIGHTS ==================== The Reference filter was contributed by Arturn Bergman, with changes by Philip Gwyn. Please see the POE manpage for more information about authors and contributors.  File: pm.info, Node: POE/Filter/Stream, Next: POE/Kernel, Prev: POE/Filter/Reference, Up: Module List POE Stream (Null) Protocol Abstraction ************************************** NAME ==== POE::Filter::Stream - POE Stream (Null) Protocol Abstraction SYNOPSIS ======== $filter = new POE::Filter::Stream(); $arrayref_of_logical_chunks = $filter->get($arrayref_of_raw_chunks_from_driver); $arrayref_of_streamable_chunks_for_driver = $filter->put($arrayref_of_logical_chunks); DESCRIPTION =========== This filter passes data through unchanged. It is a "null" filter. SEE ALSO ======== POE::Filter; POE::Filter::HTTPD; POE::Filter::Line; POE::Filter::Reference; POE::Filter::Stream BUGS ==== Oh, probably some. AUTHORS & COPYRIGHTS ==================== Please see the POE manpage.  File: pm.info, Node: POE/Kernel, Next: POE/NFA, Prev: POE/Filter/Stream, Up: Module List an event dispatcher and resource watcher **************************************** NAME ==== POE::Kernel - an event dispatcher and resource watcher SYNOPSIS ======== The POE manpage includes and describes a sample program. POE comes with its own event loop, which is based on select() and written exclusively in Perl. To use it, simply: use POE; POE's functions will also map to Gtk's event loop if Gtk is used first. No other actions are required to begin using POE with Gtk. See POE::Session's postback() method for mapping Gtk callbacks to POE events. See the test program 21_gtk.t for a sample POE program that uses Gtk. use Gtk; use POE; POE's functions will also map to Tk's event loop if Tk is used first. No other actions are required to begin using POE with Tk. See POE::Session's postback() method for mapping Tk callbacks to POE events. See the test program 06_tk.t for a sample POE program that uses Tk. use Tk; use POE; POE can also encapsulate Event's event loop. If Event is used before POE, then POE will use it for you. POE::Session's postback() method can also be used here to have Event's watchers post POE events. 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. $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 ); # Synchronous state call, bypassing the event queue and returning # the state's return value directly. $state_return_value = $kernel->call( $session, $state_name, @state_args ); Alarm and delay methods: # Post an event which will be delivered at an absolute Unix epoch # time. This clears previous timed events for the same state. $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 some number of # seconds. This clears previous timed events for the same state. $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. Clear a read select # from a filehandle. $kernel->select_read( $file_handle, $state_name ); $kernel->select_read( $file_handle ); # Watch for write readiness on a filehandle. Clear a write select # from a filehandle. $kernel->select_write( $file_handle, $state_name ); $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 ); # Watch for out-of-bound (expedited) read readiness on a filehandle. # Clear an expedite select from a filehandle. $kernel->select_expedite( $file_handle, $state_name ); $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: # Map a signal name to its handler state. Clear a signal-to-handler # mapping. $kernel->sig( $signal_name, $state_name ); $kernel->sig( $signal_name ); # Simulate a system signal by posting it through POE rather than # through the underlying OS. $kernel->signal( $session, $signal_name ); State management methods: # Remove an existing state from the current machine. $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 # This is the Gtk or Tk top-level (or main) window widget. POE uses # it for a couple things: It's how Tk's event loop is accessed, and # its closure fires the UIDESTROY signal. $poe_main_window DESCRIPTION =========== POE::Kernel is an event dispatcher and resource watcher. It provides a consistent interface to the most common event loop features whether the underlying architecture is its own, Gtk-Perl's, Tk-Perl's, or Event's. Other loop features can be integrated with POE through POE::Session's postback() method. USING POE::Kernel ================= The POE manpage describes a shortcut for using several POE modules at once. POE::Kernel supports four event loops: Its own select loop, included with POE and coded in Perl for maximum portability; Gtk's and Tk's loops, which let programs interact with users through a graphical interface; and Event's loop, which is written in C for maximum performance. POE::Kernel uses its own loop by default, but it will adapt to whichever external event loop is loaded before it. POE's functions work the same regardless of the underlying event loop. # Use POE's select loop. use POE::Kernel; # Use Gtk's event loop. use Gtk; use POE::Kernel; # Use Tk's event loop. use Tk; use POE::Kernel; # Use Event's loop. use Event; use POE::Kernel; All of the other event loops assume their native watchers will invoke callbacks. POE::Session's postback() method is used to create callbacks that post POE events. Programs can use it to take advantage of otherwise "unsupported" native callbacks. It also is possible to enable assertions and debugging traces by defining the constants that enable them before POE::Kernel does. Every definition follows the form: sub POE::Kernel::ASSERT_SOMETHING () { 1 } Assertions are quiet until something wrong has been detected, and then they die right away with an error. Their main use is for sanity checks in POE's test suite. 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. Assertions will be discussed first. ASSERT_DEFAULT The value of ASSERT_DEFAULT is used as the default value for the other assertion constants. Setting this true is a quick and reliable way to ensure that all assertions are enabled. ASSERT_GARBAGE Enabling ASSERT_GARBAGE has POE::Kernel verify its internal record keeping against sane conditions. In particular, it ensures that sessions have released all their resources before destroying them. ASSERT_REFCOUNT Setting ASSERT_REFCOUNT true enables checks for negative reference counts and nonzero reference counts in destroyed sessions. It complements ASSERT_GARBAGE. ASSERT_RELATIONS Enabling ASSERT_RELATIONS turns on parent/child referential integrity checks. ASSERT_SELECT Setting ASSERT_SELECT true enables extra error checking in POE::Kernel's select logic. It has no effect if POE is using an external event loop. ASSERT_SESSIONS POE::Kernel normally discards events that are posted to nonexistent sessions. This is a deliberate feature, but it means that certain typographical errors can go unnoticed. A true ASSERT_SESSIONS constant will cause POE to check session resolution and die if an unknown session is referenced. This may catch problems that are otherwise difficult to spot. Then there are the trace options. TRACE_DEFAULT TRACE_DEFAULT works like ASSERT_DEFAULT except for traces. That is, its value is used as the default for the other trace constants. Setting it true is a quick and reliable way to turn on every type of trace. TRACE_EVENTS The music goes around and around, and it comes out here. Enabling TRACE_EVENTS causes POE::Kernel to tell you what happens to FIFO and alarm events: when they're enqueued, dispatched or discarded, and what their states return. TRACE_GARBAGE 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 stay alive. TRACE_PROFILE This trace constant switches on state profiling, causing POE::Kernel to keep a count of every state it dispatches. It displays a frequency report when the event loop finishes. TRACE_QUEUE 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 Setting TRACE_REFCOUNT to true enables debugging output whenever an external reference count changes. TRACE_SELECT TRACE_SELECT enables or disables statistics about POE::Kernel's default select loop's select parameters and return values. POE::Kernel Exports =================== 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 This 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, most programs call `$poe_kernel-'run()> to run its event loop. States rarely need to use $poe_kernel directly since they receive a copy of it in $_[KERNEL]. $poe_main_window POE creates a "main" or "top-level" window when Tk or Gtk are used. Tk requires a main window before its events can be used, and both toolkits signal destruction through a top-level window callback. That callback is used to fire a UIDESTROY signal when a program is closed. Rather than waste the window, POE exports it as $poe_main_window. PRIVATE KERNEL METHODS ====================== The private kernel methods are private. All the usual "here there be private methods" caveats apply. As such, they won't be documented here. The terminally curious, however, will note that POE::Kernel contains a lot of comments. PUBLIC KERNEL METHODS ===================== This section discusses in more detail the POE::Kernel methods that appear in the SYNOPSIS. It uses the same syntax conventions as the perlfunc manpage. Methods to manage the process' global Kernel instance ----------------------------------------------------- ID Return the POE::Kernel instance's unique identifier. 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 Runs the chosen event loop, returning only after every session has stopped. It returns immediately if no sessions have yet been started. $poe_kernel->run(); exit; The run() method does not return a meaningful value. FIFO event methods ------------------ Events posted with these methods are dispatched back to sessions in first-in/first-out order (in case you didn't know what FIFO meant). Sessions will not spontaneously stop if they have pending FIFO events. In other words, FIFO events keep sessions alive. post SESSION, STATE_NAME, PARAMETER_LIST post SESSION, STATE_NAME Posts an event for STATE_NAME in SESSION. If a PARAMETER_LIST is included, its values will be used as arguments to STATE_NAME. $_[KERNEL]->post( $session, 'do_this' ); $_[KERNEL]->post( $session, 'do_that', $with_this, $and_this ); $_[KERNEL]->post( $session, 'do_that', @with_these ); The post() method a boolean value indicating whether the event was enqueued successfully. The $! variable will explain why post() failed. * ESRCH POE cannot find SESSION. yield STATE_NAME, PARAMETER_LIST yield STATE_NAME Posts an event for STATE_NAME in the current session. If a PARAMETER_LIST is included, its values will be used as arguments to STATE_NAME. Observant readers will note that this is just post() to the current session. Events posted with yield() must propagate through POE's FIFO before they're dispatched. This effectively yields FIFO time to other sessions which already have events enqueued. $kernel->yield( 'do_this' ); $kernel->yield( 'do_that', @with_these ); The yield() method does not return a meaningful value. call SESSION, STATE_NAME, PARAMETER_LIST call SESSION, STATE_NAME Calls STATE_NAME in a SESSION, bypassing the FIFO. Values from the optional PARAMETER_LIST will be passed as arguments to STATE_NAME at dispatch time. The call() method returns its status in $!, which is 0 for success or a nonzero reason for failure. $return_value = $kernel->call( 'do_this_now' ); 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: * ESRCH POE disbelieves in SESSION. Alarm and delay methods ----------------------- POE also manages timed events. These are events that should be dispatched after at a certain time or after some time has elapsed. Alarms and delays always are enqueued for the current session, so a SESSION parameter is not needed. POE's timed events fall into two major categories: ones which are to be dispatched at an absolute time, and ones that will be dispatched after a certain amount of time has elapsed. Each category is further divided into methods that clear previous timed events before posting new ones, and methods that post timed events in addition to the ones already in the queue. POE will use Time::HiRes to increase timed events' accuracy. It will use the less accurate time(2) if Time::HiRes isn't available. Sessions will not spontaneously stop if they have pending timed events. In other words, these events keep sessions alive. alarm STATE_NAME, EPOCH_TIME, PARAMETER_LIST alarm STATE_NAME, EPOCH_TIME alarm STATE_NAME Clears all the timed events destined for STATE_NAME in the current session then optionally sets a new one. The new timed event will be dispatched to STATE_NAME no earlier than EPOCH_TIME and can include values from an optional PARAMETER_LIST. The timed event queue is kept in time order. Posting an alarm with an EPOCH_TIME in the past will do the obvious thing. The first two forms reset a one-shot timed event by clearing any pending ones for STATE_NAME before setting a new one. $kernel->alarm( 'do_this', $at_this_time, @with_these_parameters ); $kernel->alarm( 'do_this', $at_this_time ); The last form clears all pending timed events for the state without setting a new one. $kernel->alarm( 'do_this' ); This method will clear timed events regardless of how they were set. `alarm()' returns 0 on success or a reason for its failure: * EINVAL STATE_NAME is undefined. alarm_add STATE_NAME, EPOCH_TIME, PARAMETER_LIST alarm_add STATE_NAME, EPOCH_TIME Sets an additional timed event for STATE_NAME in the current session without clearing previous ones. The timed event will be dispatched no earlier than EPOCH_TIME. $kernel->alarm_add( 'do_this', $at_this_time, @with_these_parameters ); $kernel->alarm_add( 'do_this', $at_this_time ); Use the alarm() or delay() method to clear timed events set by alarm_add(). `alarm_add()' returns 0 on success or a reason for failure: * EINVAL Either STATE_NAME or EPOCH_TIME is undefined. delay STATE_NAME, SECONDS, PARAMETER_LIST delay STATE_NAME, SECONDS delay STATE_NAME Clears all the timed events destined for STATE_NAME in the curernt session then optionally sets a new one. The new timed event will be dispatched to STATE_NAME after no fewer than SECONDS have elapsed. If the optional PARAMETER_LIST is included, then its values will be passed along to the state when it's invoked. delay() uses whichever time(2) is available to POE::Kernel. It uses the more accurate Time::HiRes::time() if it's available, or plain time(2) if it's not. This obviates the need to check for Time::HiRes in your own code. The timed event queue is kept in time order, and delays posted with negative SECONDS will do the obvious thing. SECONDS may be fractional regardless of which time() function is available. The first two forms enqueue a new delay after the pending timed events for STATE_NAME are cleared. $kernel->delay( 'do_this', $after_this_much_time, @with_these ); $kernel->delay( 'do_this', $after_this_much_time ); The last form clears pending timed events without setting a new one. $kernel->delay( 'do_this' ); delay() returns 0 on success or a reason for its failure: * EINVAL STATE_NAME is undefined. delay_add STATE_NAME, SECONDS, PARAMETER_LIST delay_add STATE_NAME, SECONDS Sets an additional timed event for STATE_NAME in the current session without clearing previous ones. The event will be dispatched no sooner than SECONDS seconds hence. $kernel->delay_add( 'do_this', $after_this_much_time, @with_these ); $kernel->delay_add( 'do_this', $after_this_much_time ); Use the alarm() or delay() method to clear timed events set by alarm_add(). `delay_add()' returns 0 on success or a reason for failure: * EINVAL Either STATE_NAME or SECONDS is undefined. queue_peek_alarms Returns a time-ordered list of state names in the current session that have pending timed events. my @pending_alarms = $kernel->queue_peek_alarms(); Symbolic name, or session alias methods --------------------------------------- Methods in this section allow sessions to refer to each-other by symbolic name or numeric ID. Session IDs are quite a lot like process IDs, but they are unique to the sessions within the current POE::Kernel. In theory, a combination of POE::Kernel and Session IDs should be enough to uniquely identify a particular session anywhere in the world. Most POE::Kernel methods resolve SESSION internally, so it's possible to refer to sessions by a number of things. See the alias_resolve() description for more information. Sessions will not spontaneously stop if they have aliases. In other words, aliases keep sessions alive. alias_set ALIAS Sets an ALIAS for the current session. ALIAS then may be used nearly everywhere instead of SESSION. Sessions may have more than one ALIAS; each must be defined in a separate alias_set() call. $kernel->alias_set( 'ishmael' ); 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', 'my_state' ); alias_set() returns 0 on success, or a nonzero failure indicator: * EEXIST The alias already is assigned to a different session. alias_remove ALIAS Clears an existing ALIAS from the current session. ALIAS will no longer refer to this session. $kernel->alias_remove( 'shirley' ); The session will begin its destruction if the alias was all that kept it alive. alias_remove() returns 0 on success or a reason for its failure: * ESRCH POE::Kernel disavows all knowledge of the alias. * EPERM The alias belongs to another session, and the current one has no permission to clear it. alias_resolve ALIAS Resolves an alias name into a session reference. alias_resolve() has been overloaded over time to look up additional things, and now ALIAS may be: A session alias: $session_reference = $kernel->alias_resolve( 'irc_component' ); A stringified session reference: $blessed_session_reference = $kernel->alias_resolve( "$stringified_one" ); Or a session ID: $session_reference = $kernel->alias_resolve( $session_id ); alias_resolve() returns undef upon failure, setting $! to explain the error: * ESRCH POE::Kernel can't find ALIAS anywhere. The following functions work with IDs directly. They were at one point depreciated, but it was decided to keep them since they're faster than alias_resolve() for working solely with session IDs. For example, Philip Gwyn's inter-kernel calls module, POE::Component::IKC, uses these to resolve sessions across processes. ID_id_to_session SESSION_ID Resolves a session reference from a SESSION_ID. $session_reference = ID_id_to_session( $session_id ); It returns a session reference on success or undef on failure. If it fails, $! contains the reason why: * ESRCH POE::Kernel doesn't have session SESSION_ID. ID_session_to_id SESSION_REFERENCE Resolves a session ID from a session reference. This is virtually identical to SESSION_REFERENCE->ID, except that SESSION_REFERENCE may be stringified: $session_id = ID_session_to_id( $stringified_session_reference ); It returns a session ID on success or undef in the case of a failure. If it fails, $! says why: * ESRCH POE::Kernel has no session matching SESSION_REFERENCE. Filehandle watcher methods -------------------------- Sessions use these methods to tell POE::Kernel what type of filehandle activity they're interested in. POE::Kernel synchronously calls states registered to deal with filehandle activity when one of these interesting events occurs. States are called synchronously so that the filehandle activity may be dealt with immediately. This avoids the watcher seeing the same activity twice. When a state is called, it receives a copy of the filehandle in $_[ARG0]. ARG0 is one of POE::Session's parameter offset constants; you can read more about it in the POE::Session manpage. Sessions will not spontaneously stop as long as they are watching at least one filehandle. In other words, watching a filehandle keep a session alive. States that are invoked by select watchers receive some parameters to help them remember why they were called. select_read FILE_HANDLE, STATE_NAME select_read FILE_HANDLE Starts and stops calling the current session's STATE_NAME state when FILE_HANDLE becomes ready for reading. $kernel->select_read( $filehandle, 'do_a_read' ); $kernel->select_read( $filehandle ); select_read() does not return a meaningful value. select_write FILE_HANDLE, STATE_NAME select_write FILE_HANDLE Starts and stops calling the current session's STATE_NAME state when FILE_HANDLE becomes ready for writing. $kernel->select_write( $filehandle, 'flush_some_data' ); $kernel->select_write( $filehandle ); select_write() does not return a meaningful value. select_expedite FILE_HANDLE, STATE_NAME select_expedite FILE_HANDLE Starts and stops calling the current session's STATE_NAME state when FILE_HANDLE becomes ready for out-of-band reading. $kernel->select_expedite( $filehandle, 'do_an_oob_read' ); $kernel->select_expedite( $filehandle ); select_expedite() does not return a meaningful value. select_pause_write FILE_HANDLE select_resume_write FILE_HANDLE Temporarily pauses and resumes write watching on a filehandle. These functions only manipulate the select(2) write bits for FILE_HANDLE. They don't perform full resource management on FILE_HANDLE. This makes select_pause_write() and select_resume_write() ideal for data flushers. $kernel->select_pause_write( $filehandle ); $kernel->select_resume_write( $filehandle ); These methods don't return meaningful values. select FILE_HANDLE, READ_STATE_NAME, WRITE_STATE_NAME, EXPEDITE_STATE_NAME Sets or clears read, write, and expedite watchers on a filehandle all together. Watchers for defined state names will be set, and undefined state names will clear the corresponding watchers. For example, set all three: $kernel->select( $filehandle, 'do_a_read', 'flush', 'read_oob' ); And to clear all three: $kernel->select( $filehandle ); To configure watchers for a read-only handle: $kernel->select( $filehandle, 'do_a_read', undef, 'read_oob' ); And a write-only handle: $kernel->select( $filehandle, undef, 'flush' ); This method does not return a meaningful value. Signal watcher and generator methods ------------------------------------ Sessions always receive signal events, even if they aren't explicitly watching for them. These signal watcher methods merely manage mappings between signal names and state names. The POE::Session manpage describes the default signal handler state, _signal, in a little more detail. Unlike with the previous resource watchers, sessions may spontaneously stop even if they are hold signal name maps. In other words, signal name maps *do not* keep sessions alive. POE does not make Perl's signal handling safe by itself. The Event module, however, does implement safe signals, and POE will take advantage of them when they're available. Most signals propagate depth first through the sessions' parent/child relationships. That is, they are delivered to grandchildren, then children, then parents, then grandparents, all the way back to the global POE::Kernel instance, which is the oldest ancestor in the tree. There are three signal levels: nonmaskable, terminal, and benign. A benign signal never stops a session, even if the session doesn't handle it. Most signals are benign. Note, however, that at the time of this writing even benign signals can crash Perl. A terminal signal will stop any session that doesn't handle it. There are relatively few terminal signals: HUP, IDLE (fictitious; explained below), INT, KILL, QUIT, TERM. A nonmaskable signal always stops a session, even if the session says it's been handled. There are only two nonmaskable signals, and they both are fictitious and explained shortly: ZOMBIE and UIDESTROY. A signal handling state's return value tells POE whether it handled the signal. A true return value means that the state handled the signal; a false value indicates that the state did not. Handling a signal does not prevent it from propagating up the sessions' relationship tree. As was previously mentioned, POE generates three fictitious signals. These notify sessions when extraordinary circumstances occur. They are IDLE, UIDESTROY and ZOMBIE. The terminal IDLE signal is posted when the only sessions remaning are alive by virtue of having aliases. This situation occurs when daemon sessions exist without any clients to interact with. POE posts IDLE to them, giving them an opportunity to prove they're not yet dead. The UIDESTROY signal is, regrettably nonmaskable. It indicates that the program's UI has signaled its destruction. In Gtk and Tk, it means that the main or top-level window is being closed, and everything must go. ZOMBIE is a nonmaskable signal as well. It's posted if IDLE hasn't been effective in waking any lingering daemon sessions. It tells the remaining sessions that they've wasted their opportunity to do something, and now it's time to die. Three system signals have special handling. They are SIGCH?LD, SIGPIPE, and SIGWINCH. POE::Kernel's SIGCHLD and SIGCLD handlers both appear to sessions as CHLD. The Kernel's handlers automatically call waitpid(2) on behalf of sessions, collecting stopped child process' IDs and return values. CHLD signal handlers receive stopped child PIDs in $_[ARG1], and the return value form $? in $_[ARG2]. As usual, $_[ARG0] contains 'CHLD'. POE::Kernel's SIGPIPE handler only posts PIPE to the currently running session. This may be a problem since signals are delivered asynchronously to processes; the author has been saved so far because nobody seems to use SIGPIPE for anything anyway. Finally, SIGWINCH is just ignored outright. Window managers generate several of these all at once, which, at the time of this writing, kills Perl in short order. sig SIGNAL_NAME, STATE_NAME sig SIGNAL_NAME Registers or unregisters a handler for SIGNAL_NAME. Signal names are the same as %SIG use, with one exception: CLD will be delivered as CHLD, so sessions handling CHLD will get both. $kernel->sig( INT => 'sigint_handler' ); The handler for SIGNAL_NAME will be unregistered if STATE_NAME is omitted. $kernel->sig( INT ); It is possible to register handlers for signals that the operating system will never deliver. This allows sessions to watch for fictitious signals that are generated through POE instead of kill(2). The sig() method does not return a meaningful value. signal SESSION, SIGNAL_NAME Posts a signal to a session through POE::Kernel rather than via kill(2). SIGNAL_NAME needn't be supported by the underlying operating system. $kernel->signal( $session, 'DIEDIEDIE' ); POE::Kernel's signal() method doesn't return a meaningful value. State management methods ------------------------ These methods allow sessions to modify their states at runtime. It would be rude to alter other sessions' states, so these methods only affects the current session. state STATE_NAME state STATE_NAME, CODE_REFERENCE state STATE_NAME, OBJECT_REFERENCE state STATE_NAME, OBJECT_REFERENCE, OBJECT_METHOD_NAME state STATE_NAME, PACKAGE_NAME state STATE_NAME, PACKAGE_NAME, PACKAGE_METHOD_NAME Adds a new state to the current session, removes an existing state from it, or replaces an existing state in it. The first form deletes a state, regardless whether it's handled by a code reference, an object method or a package method. $kernel->state( 'do_this' ); The second form registers a new handler or overwrites an existing one with a new coderef. They were originally called inline states because early POE prototypes defined them with inline anonymous subs. $kernel->state( 'do_this', \&this_does_it ); The third and fourth forms register a new handler or overwrite an existing one with an object method. These are known as object states. In the third form, the object's method matches the state's name: $kernel->state( 'do_this', $with_this_object ); The fourth form allows state names to be mapped to differently named object methods. This example defines a mapped object state: $kernel->state( 'do_this', $with_this_object, $and_this_method ); The fifth and sixth forms allow state names register a new handler or owerwrite an existing one with a package method. These are known as package states. In the fifth form, the package's method matches the state's name: $kernel->state( 'do_this', $with_this_package ); The sixth form allows state names to be mapped to differently named package methods. This example defines a mapped package state: $kernel->state( 'do_this', $with_this_package, $and_this_method ); POE::Kernel's state() method returns 0 on success or a nonzero code explaining why it failed: * ESRCH POE::Kernel has no knowledge of the currently active session. This occurs when state() is called when no session is active. External reference count methods -------------------------------- External reference counts were created so POE could cooperate with other event loops. They external resource watchers to prevent sessions from spontaneously self-destructing. Held external events essentially say "Ok, don't die 'til I'm done." External reference counts are kept by name. This feature is still relatively new, so there is no convention in place to prevent namespace collisions. If anyone has ideas about this, please contact the author. refcount_increment SESSION_ID, REFCOUNT_NAME refcount_decrement SESSION_ID, REFCOUNT_NAME Increments or decrements a reference count called REFCOUNT_NAME in the session identified by SESSION_ID. Returns undef on failure, or the new reference count on success. $new_count = $kernel->refcount_increment( $session_id, 'postback' ); $new_count = $kernel->refcount_decrement( $session_id, 'postback' ); These methods set $! upon failure: * ESRCH The session formerly known as SESSION_ID no longer (or perhaps never did) exist. Kernel Data Accessors --------------------- These functions provide a consistent interface to the Kernel's internal data. get_active_session This function returns a reference to the session which is currently being invoked by the Kernel. When no session is currently being invoked, it returns a reference to the Kernel itself. This is one of the times where the Kernel pretends its a session. Note, though, that the Kernel does not have a heap. Attempting something like this will fail if get_active_session() returns a reference to the Kernel. $kernel->get_active_session()->get_heap()->{key} = $value; SEE ALSO ======== The POE manpages contains holistic POE information. BUGS ==== There are no currently known bugs. If you find one, tell the author! AUTHORS & COPYRIGHTS ==================== Please see the POE manpage for authors and licenses.