Install Now
POE - portable multitasking and networking framework for any event loop
Contents
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.
WindowsIssues
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/UnixIssuesptywoes
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)
OtherCompatibilityIssues
None currently known. See GETTING HELP below if you've run into something.
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.
Layer1:KernelandSessions
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.
Layer2:Wheels,Filters,andDrivers
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.
Layer3: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>
Layer4andBeyond:FrameworksandObjectMetaphors
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-KernelCommunication. 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.
Layer0:POE'sInternals
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.
BasicFeatures
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.
BasicUsage
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.
BaseClassesDocumentCommonFeatures
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.
HelperClasses
POE includes some helper classes for portability. POE::Pipe, and its subclasses POE::Pipe::OneWay and
POE::Pipe::TwoWay are portable pipes.
EventLoopBridges
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::QueueandPOE::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.
ThisSectionIsn'tComplete
Help organize the documentation. Obviously we can't think of everything. We're well aware of this and
welcome audience participation.
SeeSEEALSO
Wherever possible, the SEE ALSO section will cross-reference one module to related ones.
Don'tForgettheWeb
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.
Getting Help
POE's developers take pride in its quality. If you encounter a problem, please let us know.
POE'sRequestTracker
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'sMailingList
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'sWebSite
<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'sSourceCode
The following command will fetch the most current version of POE into the "poe" subdirectory:
git clone https://github.com/rcaputo/poe.git
SourceForgehttp://sourceforge.net/projects/poe/ is POE's project page.
InternetRelayChat(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.
PersonalSupport
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.
Name
POE - portable multitasking and networking framework for any event loop
See Also
Broken down by abstraction layer.
Layer1
POE::Kernel, POE::Session, POE::NFA
Layer2
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
Layer3
POE::Component, POE::Component::Client::TCP, POE::Component::Server::TCP
Layer0
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
HomePagehttp://poe.perl.org/BugTracker
https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=POE
RepositoriesandChanges
You can browse the POE source and complete change logs at https://github.com/rcaputo/poe. It also
provides an RSS news feed for those who want to follow development in near-realtime.
OtherResources
https://metacpan.org/module/POE
http://search.cpan.org/dist/POESynopsis
#!/usr/bin/perl
use warnings;
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;
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.
PNG Icons
Emojis
