Provided by: libpoe-perl_1.3670-2_all bug

NAME

       POE - portable multitasking and networking framework for any event loop

SYNOPSIS

         #!/usr/bin/perl -w
         use strict;

         use POE;  # Auto-includes POE::Kernel and POE::Session.

         sub handler_start {
           my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
           print "Session ", $session->ID, " has started.\n";
           $heap->{count} = 0;
           $kernel->yield('increment');
         }

         sub handler_increment {
           my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
           print "Session ", $session->ID, " counted to ", ++$heap->{count}, ".\n";
           $kernel->yield('increment') if $heap->{count} < 10;
         }

         sub handler_stop {
           print "Session ", $_[SESSION]->ID, " has stopped.\n";
         }

         for (1..10) {
           POE::Session->create(
             inline_states => {
               _start    => \&handler_start,
               increment => \&handler_increment,
               _stop     => \&handler_stop,
             }
           );
         }

         POE::Kernel->run();
         exit;

DESCRIPTION

       POE is a framework for cooperative, event driven multitasking and networking in Perl.
       Other languages have similar frameworks.  Python has Twisted.  TCL has "the event loop".

       POE provides a unified interface for several other event loops, including select(),
       IO::Poll, Glib, Gtk, Tk, Wx, and Gtk2.  Many of these event loop interfaces were written
       by others, with the help of POE::Test::Loops.  They may be found on the CPAN.

       POE achieves its high degree of portability to different operating systems and Perl
       versions by being written entirely in Perl.  CPAN hosts optional XS modules for POE if
       speed is more desirable than portability.

       POE is designed in layers.  Each layer builds atop the lower level ones.  Programs are
       free to use POE at any level of abstraction, and different levels can be mixed and matched
       seamlessly within a single program.  Remember, though, that higher-level abstractions
       often require more resources than lower-level ones.  The conveniences they provide are not
       free.

       POE's bundled abstraction layers are the tip of a growing iceberg.  Sprocket, POE::Stage,
       and other CPAN distributions build upon this work.  You're encouraged to look around.

       No matter how high you go, though, it all boils down to calls to POE::Kernel.  So your
       down-to-earth code can easily cooperate with stratospheric systems.

   Layer 1: Kernel and Sessions
       The lowest public layer is comprised of POE::Kernel, POE::Session, and other session
       types.

       POE::Kernel does most of the heavy lifting.  It provides a portable interface for
       filehandle activity detection, multiple alarms and other timers, signal handling, and
       other less-common features.

       POE::Session and derived classes encapsulate the notion of an event driven task.  They
       also customize event dispatch to a particular calling convention.  POE::NFA, for example,
       is more of a proper state machine.  The CPAN has several other kinds of sessions.

       Everything ultimately builds on these classes or the concepts they implement.  If you're
       short on time, the things to read besides this are POE::Kernel and POE::Session.

   Layer 2: Wheels, Filters, and Drivers
       POE::Wheel objects are dynamic mix-ins for POE::Session instances. These "wheels" perform
       very common, generic tasks in a highly reusable and customizable way.
       POE::Wheel::ReadWrite, for example, implements non-blocking buffered I/O.  Nearly
       everybody needs this, so why require people to reinvent it all the time?

       POE::Filter objects customize wheels in a modular way.  Filters act as I/O layers, turning
       raw streams into structured data, and serializing structures into something suitable for
       streams.  The CPAN also has several of these.

       Drivers are where the wheels meet the road.  In this case, the road is some type of file
       handle.  Drivers do the actual reading and writing in a standard way so wheels don't need
       to know the difference between send() and syswrite().

       POE::Driver objects get relatively short shrift because very few are needed.  The most
       common driver, POE::Driver::SysRW is ubiquitous and also the default, so most people will
       never need to specify one.

   Layer 3: Components
       POE::Component classes are essentially Perl classes that use POE to perform tasks in a
       non-blocking or cooperative way.  This is a very broad definition, and POE components are
       all over the abstraction map.

       Many components, such as POE::Component::Server::SMTP, encapsulate the generic details of
       an entire application.  Others perform rather narrow tasks, such as
       POE::Component::DirWatch::Object.

       POE components are often just plain Perl objects.  The previously mentioned
       POE::Component::DirWatch::Object uses Moose.  Other object and meta-object frameworks are
       compatible.

       Also of interest is POE::Component::Generic, which allows you to create a POE component
       from nearly any blocking module.

       There are quite a lot of components on the CPAN.
       <http://search.cpan.org/search?query=poe+component&mode=all>

   Layer 4 and Beyond: Frameworks and Object Metaphors
       It's possible to abstract POE entirely behind a different framework.  In fact we encourage
       people to write domain-specific abstractions that entirely hide POE if necessary.  The
       nice thing here is that even at these high levels of abstraction, things will continue to
       interoperate all the way down to layer 1.

       Two examples of ultra-high level abstraction are Sprocket, a networking framework that
       does its own thing, and POE::Stage, which is POE's creator's attempt to formalize and
       standardize POE components.

       It is also possible to communicate between POE processes.  This is called IKC, for Inter-
       Kernel Communication.  There are a few IKC components on the CPAN
       (<http://search.cpan.org/search?query=IKC&mode=all>), notably POE::Component::IKC and
       POE::TIKC.

   Layer 0: POE's Internals
       POE's layered architecture continues below the surface.  POE's guts are broken into
       specific POE::Loop classes for each event loop it supports.  Internals are divided up by
       type, giving POE::Resource classes for Aliases, Controls, Events, Extrefs, FileHandles,
       SIDs, Sessions and Signals.

       POE::Kernel's APIs are extensible through POE::API mix-in classes.  Some brave souls have
       even published new APIs on CPAN, such as POE::API::Peek (which gives you access to some of
       the internal POE::Resource methods).

       By design, it's possible to implement new POE::Kernel guts by creating another
       POE::Resource class.  One can then expose the functionality with a new POE::API mix-in.

DOCUMENTATION ROADMAP

       You're reading the main POE documentation.  It's the general entry point to the world of
       POE.  You already know this, however, so let's talk about something more interesting.

   Basic Features
       POE's basic features are documented mainly in POE::Kernel and POE::Session.  Methods are
       documented in the classes that implement them.  Broader concepts are covered in the most
       appropriate class, and sometimes they are divided among classes that share in their
       implementation.

   Basic Usage
       Basic usage, even for POE.pm, is documented in POE::Kernel.  That's where most of POE's
       work is done, and POE.pm is little more than a class loader.

   @_[KERNEL, HEAP, etc.]
       Event handler calling conventions, that weird @_[KERNEL, HEAP] stuff, is documented in
       POE::Session.  That's because POE::Session implements the calling convention, and other
       session types often do it differently.

   Base Classes Document Common Features
       The POE::Wheel, POE::Driver, POE::Filter, and POE::Component base classes describe what's
       common among each class.  It's a good idea to at least skim the base class documentation
       since the subclasses tend not to rehash the common things.

       POE::Queue, POE::Resource, and POE::Loop document the concepts and sometimes the standard
       interfaces behind multiple subclasses.  You're encouraged to have a look.

   Helper Classes
       POE includes some helper classes for portability.  POE::Pipe, and its subclasses
       POE::Pipe::OneWay and POE::Pipe::TwoWay are portable pipes.

   Event Loop Bridges
       POE::Loop documents and specifies the interface for all of POE's event loop bridges.  The
       individual classes may document specific details, but generally they adhere to the spec
       strongly enough that they don't need to.

       Many of the existing POE::Loop bridges provided in POE's base distribution will move out
       to separate distributions shortly.  The documentation will probably remain the same,
       however.

   POE::Queue and POE::Queue::Array
       POE's event queue is basically a priority heap implemented as an ordered array.
       POE::Queue documents the standard interface for POE event queues, and POE::Queue::Array
       implements the ordered array queue.  Tony Cook has released POE::XS::Queue::Array, which
       is a drop-in C replacement for POE::Queue::Array.  You might give it a try if you need
       more performance.  POE's event queue is some of the hottest code in the system.

   This Section Isn't Complete
       Help organize the documentation.  Obviously we can't think of everything.  We're well
       aware of this and welcome audience participation.

   See SEE ALSO
       Wherever possible, the SEE ALSO section will cross-reference one module to related ones.

   Don't Forget the Web
       Finally, there are many POE resources on the web.  The CPAN contains a growing number of
       POE modules.  <http://poe.perl.org/> hosts POE's wiki, which includes tutorials, an
       extensive set of examples, documentation, and more.  Plus it's a wiki, so you can
       trivially pitch in your two cents.

SYSTEM REQUIREMENTS

       POE's basic requirements are rather light.  Most are included with modern versions of
       Perl, and the rest (if any) should be generally portable by now.

       Time::HiRes is highly recommended, even for older Perls that don't include it.  POE will
       work without it, but alarms and other features will be much more accurate if it's
       included. POE::Kernel will use Time::HiRes automatically if it's available.

       POE::Filter::Reference needs a module to serialize data for transporting it across a
       network.  It will use Storable, FreezeThaw, YAML, or some other package with freeze() and
       thaw() methods.  It can also use Compress::Zlib to conserve bandwidth and reduce latency
       over slow links, but it's not required.

       If you want to write web servers, you'll need to install libwww-perl, which requires
       libnet.  This is a small world of modules that includes HTTP::Status, HTTP::Request,
       HTTP::Date, and HTTP::Response.  They are generally good to have, and modern versions of
       Perl even include them.

       Programs that use POE::Wheel::Curses will of course require the Curses module, which in
       turn requires some sort of curses library.

       If you're using POE with Tk, you'll need Tk installed.

       And other obvious things.  Let us know if we've overlooked a non-obvious detail.

COMPATIBILITY ISSUES

       One of POE's design goals is to be as portable as possible.  That's why it's written in
       "Plain Perl".  XS versions of POE modules are available as third-party distributions.
       Parts of POE that require nonstandard libraries are optional, and not having those
       libraries should not prevent POE from installing.

       Despite Chris Williams' efforts, we can't test POE everywhere.  Please see the GETTING
       HELP section if you run into a problem.

       POE is expected to work on most forms of UNIX, including FreeBSD, MacOS X, Linux, Solaris.
       Maybe even AIX and QNX, but we're not sure.

       POE is also tested on Windows XP, using the latest version of ActiveState, Strawberry and
       Cygwin Perl.  POE is fully supported with Strawberry Perl, as it's included in the
       Strawberry distribution.

       OS/2 and MacOS 9 have been reported to work in the past, but nobody seems to be testing
       there anymore.  Reports and patches are still welcome.

       Past versions of POE have been tested with Perl versions as far back as 5.6.2 and as
       recent as "blead", today's development build.  We can no longer guarantee each release
       will work everywhere, but we will be happy to work with you if you need special support
       for a really old system. You can always use older POE releases that works on your version,
       please check BackPAN <http://backpan.perl.org/authors/id/R/RC/RCAPUTO/>.

       POE's quality is due in large part to the fine work of Chris Williams and the other CPAN
       testers.  They have dedicated resources towards ensuring CPAN distributions pass their own
       tests, and we watch their reports religiously.  You can, too.  The latest POE test reports
       can be found at <http://cpantesters.org/distro/P/POE.html>.

       Thanks also go out to Benjamin Smith and the 2006 Google Summer of Code.  Ben was awarded
       a grant to improve POE's test suite, which he did admirably.

   Windows Issues
       POE seems to work very nicely with Perl compiled for Cygwin.  If you must use ActiveState
       Perl, please use the absolute latest version.  ActiveState Perl's compatibility fluctuates
       from one build to another, so we tend not to support older releases.

       Windows and ActiveState Perl are considered an esoteric platform due to the complex
       interactions between various versions.  POE therefore relies on user feedback and support
       here.

       A number of people have helped bring POE's Windows support this far, through contributions
       of time, patches, and other resources.  Some of them are: Sean Puckett, Douglas Couch,
       Andrew Chen, Uhlarik Ondoej, Nick Williams, and Chris Williams (no relation).

   Linux/Unix Issues
       pty woes

       Some distributions chose to not completely setup the pseudo-tty support. This is needed
       for POE::Wheel::Run to interact with the subprocess. If you see something like this while
       running "make test" please look at your distribution's documentation on how to fix it. For
       example, on Debian-based systems the solution was to execute "sudo apt-get install udev".

         t/30_loops/io_poll/wheel_run.t ..................... 1/99
         pty_allocate(nonfatal): posix_openpt(): No such file or directory at /usr/local/lib/perl/5.10.0/IO/Pty.pm line 24.
         ...
         Cannot open a pty at /home/apoc/poe/blib/lib/POE/Wheel/Run.pm line 251
         Compilation failed in require at t/30_loops/io_poll/wheel_run.t line 24.
         # Looks like you planned 99 tests but ran 5.
         # Looks like your test exited with 22 just after 5.
         t/30_loops/io_poll/wheel_run.t ..................... Dubious, test returned 22 (wstat 5632, 0x1600)

   Other Compatibility Issues
       None currently known.  See GETTING HELP below if you've run into something.

GETTING HELP

       POE's developers take pride in its quality.  If you encounter a problem, please let us
       know.

   POE's Request Tracker
       You're welcome to e-mail questions and bug reports to <bug-POE@rt.cpan.org>.  This is not
       a realtime support channel, though.  If you need a more immediate response, try one of the
       methods below.

   POE's Mailing List
       POE has a dedicated mailing list where developers and users discuss the software and its
       use.  You're welcome to join us.  Send an e-mail to <poe-help@perl.org> for subscription
       instructions.  The subject and message body are ignored.

   POE's Web Site
       <http://poe.perl.org> contains recent information, tutorials, and examples.  It's also a
       wiki, so people are invited to share tips and code snippets there as well.

   POE's Source Code
       The following command will fetch the most current version of POE into the "poe"
       subdirectory:

         svn co https://poe.svn.sourceforge.net/svnroot/poe poe

   SourceForge
       http://sourceforge.net/projects/poe/ is POE's project page.

   Internet Relay Chat (IRC)
       irc.perl.org channel #poe is an informal place to waste some time and maybe even discuss
       Perl and POE.  Consider an SSH relay if your workplace frowns on IRC.  But only if they
       won't fire you if you're caught.

   Personal Support
       Unfortunately we don't have resources to provide free one-on-one personal support anymore.
       We'll do it for a fee, though.  Send Rocco an e-mail via his CPAN address.

SEE ALSO

       Broken down by abstraction layer.

   Layer 1
       POE::Kernel, POE::Session, POE::NFA

   Layer 2
       POE::Wheel, POE::Wheel::Curses, POE::Wheel::FollowTail, POE::Wheel::ListenAccept,
       POE::Wheel::ReadLine, POE::Wheel::ReadWrite, POE::Wheel::Run, POE::Wheel::SocketFactory

       POE::Driver, POE::Driver::SysRW

       POE::Filter, POE::Filter::Block, POE::Filter::Grep, POE::Filter::HTTPD, POE::Filter::Line,
       POE::Filter::Map, POE::Filter::RecordBlock, POE::Filter::Reference,
       POE::Filter::Stackable, POE::Filter::Stream

   Layer 3
       POE::Component, POE::Component::Client::TCP, POE::Component::Server::TCP

   Layer 0
       POE::Loop, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll, POE::Loop::Select,
       POE::Loop::Tk

       POE::Queue, POE::Queue::Array

       POE::Resource, POE::Resource::Aliases, POE::Resource::Events, POE::Resource::Extrefs,
       POE::Resource::FileHandles, POE::Resource::SIDs, POE::Resource::Sessions,
       POE::Resource::Signals

   Helpers
       POE::Pipe, POE::Pipe::OneWay, POE::Pipe::TwoWay

   Home Page
       http://poe.perl.org/

   Bug Tracker
       https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=POE

   Repositories and Changes
       Thanks to the magic of distributed version control, POE is hosted at three locations for
       redundancy.  You can browse the source at any one of:

       https://github.com/rcaputo/poe

       https://gitorious.org/poe

       http://poe.git.sourceforge.net/git/gitweb-index.cgi

       Complete change logs can also be browsed at those sites.  They all provide RSS news feeds
       for those who want to follow development in near-realtime.

   Other Resources
       https://metacpan.org/module/POE

       http://search.cpan.org/dist/POE

AUTHORS & COPYRIGHT

       POE is the combined effort of quite a lot of people.  This is an incomplete list of some
       early contributors.  A more complete list can be found in POE's change log.

       Ann Barcomb
         Ann Barcomb is <kudra@domaintje.com>, aka "kudra".  Ann contributed large portions of
         POE::Simple and the code that became the ReadWrite support in
         POE::Component::Server::TCP.  Her ideas also inspired Client::TCP component, introduced
         in version 0.1702.

       Artur Bergman
         Artur Bergman is <sky@cpan.org>.  He contributed many hours' work into POE and quite a
         lot of ideas.  Years later, I decide he's right and actually implement them.

         Artur is the author of Filter::HTTPD and Filter::Reference, as well as bits and pieces
         throughout POE.  His feedback, testing, design and inspiration have been instrumental in
         making POE what it is today.

         Artur is investing his time heavily into perl 5's iThreads and PONIE at the moment.
         This project has far-reaching implications for POE's future.

       Jos Boumans
         Jos Boumans is <kane@cpan.org>, aka "kane".  Jos is a major driving force behind the
         POE::Simple movement and has helped inspire the POE::Components for TCP clients and
         servers.

       Matt Cashner
         Matt Cashner is <sungo@pobox.com>, aka "sungo".  Matt is one of POE's core developers.
         He's spearheaded the movement to simplify POE for new users, flattening the learning
         curve and making the system more accessible to everyone.  He uses the system in mission
         critical applications, folding feedback and features back into the distribution for
         everyone's enjoyment.

       Andrew Chen
         Andrew Chen is <achen-poe@micropixel.com>.  Andrew is the resident POE/Windows guru.  He
         contributes much needed testing for Solaris on the SPARC and Windows on various Intel
         platforms.

       Douglas Couch
         Douglas Couch is <dscouch@purdue.edu>.  Douglas helped port and maintain POE for Windows
         early on.

       Jeffrey Goff
         Jeffrey Goff is <jgoff@blackboard.com>.  Jeffrey is the author of several POE modules,
         including a tokenizing filter and a component for managing user information,
         PoCo::UserBase.  He's also co-author of "A Beginner's Introduction to POE" at
         www.perl.com.

       Philip Gwyn
         Philip Gwyn is <gwynp@artware.qc.ca>.  He extended the Wheels I/O abstraction to support
         hot-swappable filters, and he eventually convinced Rocco that unique session and kernel
         IDs were a good thing.

         Philip also enhanced POE::Filter::Reference to support different serialization methods.
         He has also improved POE's quality by finding and fixing several bugs.  He provided POE
         a much needed code review around version 0.06.

         Lately, Philip tracked down the race condition in signal handling and fixed it with the
         signal pipe.

       Arnar M. Hrafnkelsson
         Arnar is <addi@umich.edu>.  Addi tested POE and POE::Component::IRC on Windows, finding
         bugs and testing fixes.  He appears throughout the Changes file.  He has also written
         "cpoe", which is a POE-like library for C.

       Dave Paris
         Dave Paris is <dparis@w3works.com>.  Dave tested and benchmarked POE around version
         0.05, discovering some subtle (and not so subtle) timing problems.  The pre-forking
         server sample was his idea.  Versions 0.06 and later scaled to higher loads because of
         his work.  He has contributed a lot of testing and feedback, much of which is tagged in
         the Changes file as a-mused.  The man is scarily good at testing and troubleshooting.

       Dieter Pearcey
         Dieter Pearcey is <dieter@bullfrog.perlhacker.org>.  He goes by several Japanese
         nicknames.  Dieter's current area of expertise is in Wheels and Filters.  He greatly
         improved POE::Wheel::FollowTail, and his Filter contributions include the basic Block
         filter, as well as Stackable, RecordBlock, Grep and Map.

       Plixer International
         Plixer International is at <http://plixer.com/>.  Their sponsorship has helped POE 1.300
         and beyond be significantly more robust using iThreads, especially when using fork() in
         Windows.

       Robert Seifer
         Robert Seifer is <e-mail unknown>.  He rotates IRC nicknames regularly.

         Robert contributed entirely too much time, both his own and his computers, towards the
         detection and eradication of a memory corruption bug that POE tickled in earlier Perl
         versions.  In the end, his work produced a simple compile-time hack that worked around a
         problem relating to anonymous subs, scope and @{} processing.

       Matt Sergeant
         Matt contributed "POE::Kernel::Poll", a more efficient way to watch multiple files than
         select().  It's since been moved to POE::Loop::IO_Poll.

       Richard Soderberg
         Richard Soderberg is <poe@crystalflame.net>, aka "coral".  Richard is a collaborator on
         several side projects involving POE.  His work provides valuable testing and feedback
         from a user's point of view.

       Dennis Taylor
         Dennis Taylor is <dennis@funkplanet.com>.  Dennis has been testing, debugging and
         patching bits here and there, such as Filter::Line which he improved by leaps in 0.1102.
         He's also the author of POE::Component::IRC, the widely popular POE-based successor to
         his wildly popular Net::IRC library.

       David Davis
         David Davis, aka Xantus is <xantus@cpan.org>.  David contributed patches to the HTTPD
         filter, and added CALLER_STATE to POE::Session.  He is the author of Sprocket, a
         networking framework built on POE.

       Others?
         Please contact the author if you've been forgotten and would like to be included here.

   Author
       Rocco Caputo
         Rocco Caputo is <rcaputo@cpan.org>.  POE is his brainchild.  He wishes to thank you for
         your interest, and he has more thanks than he can count for all the people who have
         contributed.  POE would not be nearly as cool without you.

         Except where otherwise noted, POE is Copyright 1998-2013 Rocco Caputo.  All rights
         reserved.  POE is free software; you may redistribute it and/or modify it under the same
         terms as Perl itself.

       Thank you for reading!