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>
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!