POE(3pm)

📦

version 1.3700 · 7 versions

1.3700 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing (latest)
1.368 · epel 9
1.370 · arch rolling
1.370 · fedora 43
1.3680 · ubuntu jammy
1.370 · fedora 44
1.3700 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

🌸 POE 💖 portable multitasking and networking framework for any event loop

okay bestie, sit DOWN, because this is POE(3pm) — the manual page for the whole POE universe — and it's a big one. grab a snack. 🍓

✨ SYNOPSIS ✨

like, here's the whole vibe in one little program. look at it. it's gorgeous.

#!/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;

💫 DESCRIPTION 💫

so POE is a framework for cooperative, event driven multitasking and networking in Perl. periodt. other languages have their own little versions of this — Python has Twisted, TCL has "the event loop". we have POE and honestly? we ate. 💅

POE gives you one unified interface over a whole bunch of other event loops, including select(), IO::Poll, Glib, Gtk, Tk, Wx, and Gtk2. a lot of those event loop interfaces were written by other people, with help from POE::Test::Loops, and you can find them on the CPAN. 🫶

the way POE stays portable across so many operating systems and Perl versions is that it's written entirely in Perl. if you care more about speed than portability, the CPAN hosts optional XS modules for POE. your call, bestie.

POE is designed in layers. each layer sits on top of the lower ones. your program can use POE at any level of abstraction, and different levels can be mixed and matched seamlessly inside a single program. 🦋 but remember — higher-level abstractions usually want more resources than lower-level ones. those conveniences are not free, no cap.

the abstraction layers bundled with POE are just the tip of a growing iceberg. Sprocket, POE::Stage, and other CPAN distributions build on top of all this. go look around, it's a whole world. 🌈

and no matter how high up you go? it all boils down to calls to POE::Kernel. so your down-to-earth code can totally cooperate with stratospheric systems. iconic.

🧚 Layer 1: Kernel and Sessions

the lowest public layer is made of POE::Kernel, POE::Session, and other session types.

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

POE::Session and its derived classes encapsulate the whole idea 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 too.

everything ultimately builds on these classes, or on the concepts they implement. if you're short on time, the things to read besides this page 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" do 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 that, so why make everyone reinvent it over and over? exactly. 💅

POE::Filter objects customize wheels in a modular way. filters act as I/O layers — they turn raw streams into structured data, and serialize structures into something suitable for streams. the CPAN has several of these too.

Drivers are where the wheels meet the road 🛣️ — and 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. lowkey perfect. ✨

🌸 Layer 3: Components

POE::Component classes are essentially Perl classes that use POE to do tasks in a non-blocking or cooperative way. that's a very broad definition, and POE components are all over the abstraction map.

many components, like POE::Component::Server::SMTP, encapsulate the generic details of an entire application. others do pretty narrow tasks, like POE::Component::DirWatch::Object.

POE components are often just plain Perl objects. the previously mentioned POE::Component::DirWatch::Object uses Moose, and other object and meta-object frameworks are compatible. 🫶

also of interest: POE::Component::Generic, which lets you create a POE component from nearly any blocking module. not me being obsessed with that.

there are quite a lot of components on the CPAN, bestie: 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 completely hide POE if necessary. the nice thing is that even at these high levels of abstraction, things keep interoperating all the way down to layer 1. 🤝

two examples of ultra-high level abstraction: 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's 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 keeps going below the surface. POE's guts are broken into specific POE::Loop classes, one for each event loop it supports. internals are divided up by type, giving you 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 the CPAN, like 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. then you can expose that functionality with a new POE::API mix-in. main character energy, honestly. 👑

🌈 DOCUMENTATION ROADMAP 🌈

you're reading the main POE documentation right now — it's the general entry point to the whole world of POE. but you already knew that, 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 live in the most appropriate class, and sometimes they're 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 gets done, and POE.pm is little more than a class loader. fr fr, that's all it is.

💖 `@_[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 docs, 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. cute, useful, we love. 🎀

💖 Event Loop Bridges

POE::Loop documents and specifies the interface for all of POE's event loop bridges. individual classes may document specific details, but generally they stick 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 stay the same though, so no stress. 🦋

💖 `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. 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 we 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 🧚

okay so the bar is LOW bestie, POE does not need much. most of what it wants already ships with modern Perl, and the leftovers (if there even are any) are basically portable at this point. it's giving low-maintenance icon 💅

Time::HiRes — highly recommended, even for older Perls that don't ship it already. POE will run without it, but alarms and other features get way more accurate when it's there. and plot twist: POE::Kernel will just use Time::HiRes automatically if it's available. no config, no drama ✨
POE::Filter::Reference — needs a module to serialize data so it can travel across a network. it'll reach for Storable, FreezeThaw, YAML, or honestly any other package that has freeze() and thaw() methods. it can also use Compress::Zlib to conserve bandwidth and reduce latency over slow links, but that one is not required.
web servers? — you'll need to install libwww-perl, which needs libnet. it's a whole little friend group of modules: HTTP::Status, HTTP::Request, HTTP::Date, and HTTP::Response. generally good to have around, and modern Perls even include them already 🫶
POE::Wheel::Curses — programs using this will of course need the Curses module, which itself needs some sort of curses library.
Tk — using POE with Tk? you need Tk installed. obviously.
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 humanly possible, which is why it's written in "Plain Perl". XS versions of POE modules exist as third-party distributions. parts of POE that need nonstandard libraries are optional, and not having those libraries should not prevent POE from installing. periodt.

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, since 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 work 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 live 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. ate and left no crumbs 💅

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). 😭 iconic

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:

git clone https://github.com/rcaputo/poe.git

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, because we're organized like that ✨

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

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 🦋

Other Resources

👑 AUTHORS & COPYRIGHT 👑

okay bestie, real talk: POE is the combined effort of a lot of people. This is an incomplete list of some early contributors — a more complete list lives in POE's change log. So if your fave isn't here, that's not shade, that's just page real estate. 💖

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 the Client::TCP component, introduced in version 0.1702. queen behavior, honestly. 👑

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. 😭 (the way that happens)

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. main character energy fr fr. ✨

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. no cap, iconic. 🔥

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. the range?? unmatched. 🌸

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. actual legend for this one. 😭

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. (not me forgetting you on purpose, i promise 🙈)

💜 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. 🥹

Thank you for reading! ⭐

and that's a wrap bestie, tysm for reading the whole thing, you ate that 🍓 this page came from perl v5.34.0, dated 2022-03-25, and yes it's POE(3pm) — now go build something iconic with it 💅🌈

📦 where this page comes from

debian bookworm: libpoe-perl 2:1.3700-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libpoe-perl 2:1.3700-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libpoe-perl 2:1.3700-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu questing: libpoe-perl 2:1.3700-1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms