Linux Manual Pages

Free Software * Books

Source Code

Free Media

Linux

POE(3pm)

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.

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!

Opportunity

Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.

Education

Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.