1POE(3)                User Contributed Perl Documentation               POE(3)
2
3
4

NAME

6       POE - portable multitasking and networking framework for any event loop
7

SYNOPSIS

9         #!/usr/bin/perl
10
11         use warnings;
12         use strict;
13
14         use POE;  # Auto-includes POE::Kernel and POE::Session.
15
16         sub handler_start {
17           my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
18           print "Session ", $session->ID, " has started.\n";
19           $heap->{count} = 0;
20           $kernel->yield('increment');
21         }
22
23         sub handler_increment {
24           my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
25           print "Session ", $session->ID, " counted to ", ++$heap->{count}, ".\n";
26           $kernel->yield('increment') if $heap->{count} < 10;
27         }
28
29         sub handler_stop {
30           print "Session ", $_[SESSION]->ID, " has stopped.\n";
31         }
32
33         for (1..10) {
34           POE::Session->create(
35             inline_states => {
36               _start    => \&handler_start,
37               increment => \&handler_increment,
38               _stop     => \&handler_stop,
39             }
40           );
41         }
42
43         POE::Kernel->run();
44         exit;
45

DESCRIPTION

47       POE is a framework for cooperative, event driven multitasking and
48       networking in Perl.  Other languages have similar frameworks.  Python
49       has Twisted.  TCL has "the event loop".
50
51       POE provides a unified interface for several other event loops,
52       including select(), IO::Poll, Glib, Gtk, Tk, Wx, and Gtk2.  Many of
53       these event loop interfaces were written by others, with the help of
54       POE::Test::Loops.  They may be found on the CPAN.
55
56       POE achieves its high degree of portability to different operating
57       systems and Perl versions by being written entirely in Perl.  CPAN
58       hosts optional XS modules for POE if speed is more desirable than
59       portability.
60
61       POE is designed in layers.  Each layer builds atop the lower level
62       ones.  Programs are free to use POE at any level of abstraction, and
63       different levels can be mixed and matched seamlessly within a single
64       program.  Remember, though, that higher-level abstractions often
65       require more resources than lower-level ones.  The conveniences they
66       provide are not free.
67
68       POE's bundled abstraction layers are the tip of a growing iceberg.
69       Sprocket, POE::Stage, and other CPAN distributions build upon this
70       work.  You're encouraged to look around.
71
72       No matter how high you go, though, it all boils down to calls to
73       POE::Kernel.  So your down-to-earth code can easily cooperate with
74       stratospheric systems.
75
76   Layer 1: Kernel and Sessions
77       The lowest public layer is comprised of POE::Kernel, POE::Session, and
78       other session types.
79
80       POE::Kernel does most of the heavy lifting.  It provides a portable
81       interface for filehandle activity detection, multiple alarms and other
82       timers, signal handling, and other less-common features.
83
84       POE::Session and derived classes encapsulate the notion of an event
85       driven task.  They also customize event dispatch to a particular
86       calling convention.  POE::NFA, for example, is more of a proper state
87       machine.  The CPAN has several other kinds of sessions.
88
89       Everything ultimately builds on these classes or the concepts they
90       implement.  If you're short on time, the things to read besides this
91       are POE::Kernel and POE::Session.
92
93   Layer 2: Wheels, Filters, and Drivers
94       POE::Wheel objects are dynamic mix-ins for POE::Session instances.
95       These "wheels" perform very common, generic tasks in a highly reusable
96       and customizable way.  POE::Wheel::ReadWrite, for example, implements
97       non-blocking buffered I/O.  Nearly everybody needs this, so why require
98       people to reinvent it all the time?
99
100       POE::Filter objects customize wheels in a modular way.  Filters act as
101       I/O layers, turning raw streams into structured data, and serializing
102       structures into something suitable for streams.  The CPAN also has
103       several of these.
104
105       Drivers are where the wheels meet the road.  In this case, the road is
106       some type of file handle.  Drivers do the actual reading and writing in
107       a standard way so wheels don't need to know the difference between
108       send() and syswrite().
109
110       POE::Driver objects get relatively short shrift because very few are
111       needed.  The most common driver, POE::Driver::SysRW is ubiquitous and
112       also the default, so most people will never need to specify one.
113
114   Layer 3: Components
115       POE::Component classes are essentially Perl classes that use POE to
116       perform tasks in a non-blocking or cooperative way.  This is a very
117       broad definition, and POE components are all over the abstraction map.
118
119       Many components, such as POE::Component::Server::SMTP, encapsulate the
120       generic details of an entire application.  Others perform rather narrow
121       tasks, such as POE::Component::DirWatch::Object.
122
123       POE components are often just plain Perl objects.  The previously
124       mentioned POE::Component::DirWatch::Object uses Moose.  Other object
125       and meta-object frameworks are compatible.
126
127       Also of interest is POE::Component::Generic, which allows you to create
128       a POE component from nearly any blocking module.
129
130       There are quite a lot of components on the CPAN.
131       <http://search.cpan.org/search?query=poe+component&mode=all>
132
133   Layer 4 and Beyond: Frameworks and Object Metaphors
134       It's possible to abstract POE entirely behind a different framework.
135       In fact we encourage people to write domain-specific abstractions that
136       entirely hide POE if necessary.  The nice thing here is that even at
137       these high levels of abstraction, things will continue to interoperate
138       all the way down to layer 1.
139
140       Two examples of ultra-high level abstraction are Sprocket, a networking
141       framework that does its own thing, and POE::Stage, which is POE's
142       creator's attempt to formalize and standardize POE components.
143
144       It is also possible to communicate between POE processes.  This is
145       called IKC, for Inter-Kernel Communication.  There are a few IKC
146       components on the CPAN
147       (<http://search.cpan.org/search?query=IKC&mode=all>), notably
148       POE::Component::IKC and POE::TIKC.
149
150   Layer 0: POE's Internals
151       POE's layered architecture continues below the surface.  POE's guts are
152       broken into specific POE::Loop classes for each event loop it supports.
153       Internals are divided up by type, giving POE::Resource classes for
154       Aliases, Controls, Events, Extrefs, FileHandles, SIDs, Sessions and
155       Signals.
156
157       POE::Kernel's APIs are extensible through POE::API mix-in classes.
158       Some brave souls have even published new APIs on CPAN, such as
159       POE::API::Peek (which gives you access to some of the internal
160       POE::Resource methods).
161
162       By design, it's possible to implement new POE::Kernel guts by creating
163       another POE::Resource class.  One can then expose the functionality
164       with a new POE::API mix-in.
165

DOCUMENTATION ROADMAP

167       You're reading the main POE documentation.  It's the general entry
168       point to the world of POE.  You already know this, however, so let's
169       talk about something more interesting.
170
171   Basic Features
172       POE's basic features are documented mainly in POE::Kernel and
173       POE::Session.  Methods are documented in the classes that implement
174       them.  Broader concepts are covered in the most appropriate class, and
175       sometimes they are divided among classes that share in their
176       implementation.
177
178   Basic Usage
179       Basic usage, even for POE.pm, is documented in POE::Kernel.  That's
180       where most of POE's work is done, and POE.pm is little more than a
181       class loader.
182
183   @_[KERNEL, HEAP, etc.]
184       Event handler calling conventions, that weird @_[KERNEL, HEAP] stuff,
185       is documented in POE::Session.  That's because POE::Session implements
186       the calling convention, and other session types often do it
187       differently.
188
189   Base Classes Document Common Features
190       The POE::Wheel, POE::Driver, POE::Filter, and POE::Component base
191       classes describe what's common among each class.  It's a good idea to
192       at least skim the base class documentation since the subclasses tend
193       not to rehash the common things.
194
195       POE::Queue, POE::Resource, and POE::Loop document the concepts and
196       sometimes the standard interfaces behind multiple subclasses.  You're
197       encouraged to have a look.
198
199   Helper Classes
200       POE includes some helper classes for portability.  POE::Pipe, and its
201       subclasses POE::Pipe::OneWay and POE::Pipe::TwoWay are portable pipes.
202
203   Event Loop Bridges
204       POE::Loop documents and specifies the interface for all of POE's event
205       loop bridges.  The individual classes may document specific details,
206       but generally they adhere to the spec strongly enough that they don't
207       need to.
208
209       Many of the existing POE::Loop bridges provided in POE's base
210       distribution will move out to separate distributions shortly.  The
211       documentation will probably remain the same, however.
212
213   POE::Queue and POE::Queue::Array
214       POE's event queue is basically a priority heap implemented as an
215       ordered array.  POE::Queue documents the standard interface for POE
216       event queues, and POE::Queue::Array implements the ordered array queue.
217       Tony Cook has released POE::XS::Queue::Array, which is a drop-in C
218       replacement for POE::Queue::Array.  You might give it a try if you need
219       more performance.  POE's event queue is some of the hottest code in the
220       system.
221
222   This Section Isn't Complete
223       Help organize the documentation.  Obviously we can't think of
224       everything.  We're well aware of this and welcome audience
225       participation.
226
227   See SEE ALSO
228       Wherever possible, the SEE ALSO section will cross-reference one module
229       to related ones.
230
231   Don't Forget the Web
232       Finally, there are many POE resources on the web.  The CPAN contains a
233       growing number of POE modules.  <http://poe.perl.org/> hosts POE's
234       wiki, which includes tutorials, an extensive set of examples,
235       documentation, and more.  Plus it's a wiki, so you can trivially pitch
236       in your two cents.
237

SYSTEM REQUIREMENTS

239       POE's basic requirements are rather light.  Most are included with
240       modern versions of Perl, and the rest (if any) should be generally
241       portable by now.
242
243       Time::HiRes is highly recommended, even for older Perls that don't
244       include it.  POE will work without it, but alarms and other features
245       will be much more accurate if it's included. POE::Kernel will use
246       Time::HiRes automatically if it's available.
247
248       POE::Filter::Reference needs a module to serialize data for
249       transporting it across a network.  It will use Storable, FreezeThaw,
250       YAML, or some other package with freeze() and thaw() methods.  It can
251       also use Compress::Zlib to conserve bandwidth and reduce latency over
252       slow links, but it's not required.
253
254       If you want to write web servers, you'll need to install libwww-perl,
255       which requires libnet.  This is a small world of modules that includes
256       HTTP::Status, HTTP::Request, HTTP::Date, and HTTP::Response.  They are
257       generally good to have, and modern versions of Perl even include them.
258
259       Programs that use POE::Wheel::Curses will of course require the Curses
260       module, which in turn requires some sort of curses library.
261
262       If you're using POE with Tk, you'll need Tk installed.
263
264       And other obvious things.  Let us know if we've overlooked a non-
265       obvious detail.
266

COMPATIBILITY ISSUES

268       One of POE's design goals is to be as portable as possible.  That's why
269       it's written in "Plain Perl".  XS versions of POE modules are available
270       as third-party distributions.  Parts of POE that require nonstandard
271       libraries are optional, and not having those libraries should not
272       prevent POE from installing.
273
274       Despite Chris Williams' efforts, we can't test POE everywhere.  Please
275       see the GETTING HELP section if you run into a problem.
276
277       POE is expected to work on most forms of UNIX, including FreeBSD, MacOS
278       X, Linux, Solaris.  Maybe even AIX and QNX, but we're not sure.
279
280       POE is also tested on Windows XP, using the latest version of
281       ActiveState, Strawberry and Cygwin Perl.  POE is fully supported with
282       Strawberry Perl, as it's included in the Strawberry distribution.
283
284       OS/2 and MacOS 9 have been reported to work in the past, but nobody
285       seems to be testing there anymore.  Reports and patches are still
286       welcome.
287
288       Past versions of POE have been tested with Perl versions as far back as
289       5.6.2 and as recent as "blead", today's development build.  We can no
290       longer guarantee each release will work everywhere, but we will be
291       happy to work with you if you need special support for a really old
292       system. You can always use older POE releases that works on your
293       version, please check BackPAN
294       <http://backpan.perl.org/authors/id/R/RC/RCAPUTO/>.
295
296       POE's quality is due in large part to the fine work of Chris Williams
297       and the other CPAN testers.  They have dedicated resources towards
298       ensuring CPAN distributions pass their own tests, and we watch their
299       reports religiously.  You can, too.  The latest POE test reports can be
300       found at <http://cpantesters.org/distro/P/POE.html>.
301
302       Thanks also go out to Benjamin Smith and the 2006 Google Summer of
303       Code.  Ben was awarded a grant to improve POE's test suite, which he
304       did admirably.
305
306   Windows Issues
307       POE seems to work very nicely with Perl compiled for Cygwin.  If you
308       must use ActiveState Perl, please use the absolute latest version.
309       ActiveState Perl's compatibility fluctuates from one build to another,
310       so we tend not to support older releases.
311
312       Windows and ActiveState Perl are considered an esoteric platform due to
313       the complex interactions between various versions.  POE therefore
314       relies on user feedback and support here.
315
316       A number of people have helped bring POE's Windows support this far,
317       through contributions of time, patches, and other resources.  Some of
318       them are: Sean Puckett, Douglas Couch, Andrew Chen, Uhlarik Ondoej,
319       Nick Williams, and Chris Williams (no relation).
320
321   Linux/Unix Issues
322       pty woes
323
324       Some distributions chose to not completely setup the pseudo-tty
325       support. This is needed for POE::Wheel::Run to interact with the
326       subprocess. If you see something like this while running "make test"
327       please look at your distribution's documentation on how to fix it. For
328       example, on Debian-based systems the solution was to execute "sudo apt-
329       get install udev".
330
331         t/30_loops/io_poll/wheel_run.t ..................... 1/99
332         pty_allocate(nonfatal): posix_openpt(): No such file or directory at /usr/local/lib/perl/5.10.0/IO/Pty.pm line 24.
333         ...
334         Cannot open a pty at /home/apoc/poe/blib/lib/POE/Wheel/Run.pm line 251
335         Compilation failed in require at t/30_loops/io_poll/wheel_run.t line 24.
336         # Looks like you planned 99 tests but ran 5.
337         # Looks like your test exited with 22 just after 5.
338         t/30_loops/io_poll/wheel_run.t ..................... Dubious, test returned 22 (wstat 5632, 0x1600)
339
340   Other Compatibility Issues
341       None currently known.  See GETTING HELP below if you've run into
342       something.
343

GETTING HELP

345       POE's developers take pride in its quality.  If you encounter a
346       problem, please let us know.
347
348   POE's Request Tracker
349       You're welcome to e-mail questions and bug reports to
350       <bug-POE@rt.cpan.org>.  This is not a realtime support channel, though.
351       If you need a more immediate response, try one of the methods below.
352
353   POE's Mailing List
354       POE has a dedicated mailing list where developers and users discuss the
355       software and its use.  You're welcome to join us.  Send an e-mail to
356       <poe-help@perl.org> for subscription instructions.  The subject and
357       message body are ignored.
358
359   POE's Web Site
360       <http://poe.perl.org> contains recent information, tutorials, and
361       examples.  It's also a wiki, so people are invited to share tips and
362       code snippets there as well.
363
364   POE's Source Code
365       The following command will fetch the most current version of POE into
366       the "poe" subdirectory:
367
368         git clone https://github.com/rcaputo/poe.git
369
370   SourceForge
371       http://sourceforge.net/projects/poe/ is POE's project page.
372
373   Internet Relay Chat (IRC)
374       irc.perl.org channel #poe is an informal place to waste some time and
375       maybe even discuss Perl and POE.  Consider an SSH relay if your
376       workplace frowns on IRC.  But only if they won't fire you if you're
377       caught.
378
379   Personal Support
380       Unfortunately we don't have resources to provide free one-on-one
381       personal support anymore.  We'll do it for a fee, though.  Send Rocco
382       an e-mail via his CPAN address.
383

SEE ALSO

385       Broken down by abstraction layer.
386
387   Layer 1
388       POE::Kernel, POE::Session, POE::NFA
389
390   Layer 2
391       POE::Wheel, POE::Wheel::Curses, POE::Wheel::FollowTail,
392       POE::Wheel::ListenAccept, POE::Wheel::ReadLine, POE::Wheel::ReadWrite,
393       POE::Wheel::Run, POE::Wheel::SocketFactory
394
395       POE::Driver, POE::Driver::SysRW
396
397       POE::Filter, POE::Filter::Block, POE::Filter::Grep, POE::Filter::HTTPD,
398       POE::Filter::Line, POE::Filter::Map, POE::Filter::RecordBlock,
399       POE::Filter::Reference, POE::Filter::Stackable, POE::Filter::Stream
400
401   Layer 3
402       POE::Component, POE::Component::Client::TCP,
403       POE::Component::Server::TCP
404
405   Layer 0
406       POE::Loop, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
407       POE::Loop::Select, POE::Loop::Tk
408
409       POE::Queue, POE::Queue::Array
410
411       POE::Resource, POE::Resource::Aliases, POE::Resource::Events,
412       POE::Resource::Extrefs, POE::Resource::FileHandles,
413       POE::Resource::SIDs, POE::Resource::Sessions, POE::Resource::Signals
414
415   Helpers
416       POE::Pipe, POE::Pipe::OneWay, POE::Pipe::TwoWay
417
418   Home Page
419       http://poe.perl.org/
420
421   Bug Tracker
422       https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=POE
423
424   Repositories and Changes
425       You can browse the POE source and complete change logs at
426       https://github.com/rcaputo/poe. It also provides an RSS news feed for
427       those who want to follow development in near-realtime.
428
429   Other Resources
430       https://metacpan.org/module/POE
431
432       http://search.cpan.org/dist/POE
433
435       POE is the combined effort of quite a lot of people.  This is an
436       incomplete list of some early contributors.  A more complete list can
437       be found in POE's change log.
438
439       Ann Barcomb
440         Ann Barcomb is <kudra@domaintje.com>, aka "kudra".  Ann contributed
441         large portions of POE::Simple and the code that became the ReadWrite
442         support in POE::Component::Server::TCP.  Her ideas also inspired
443         Client::TCP component, introduced in version 0.1702.
444
445       Artur Bergman
446         Artur Bergman is <sky@cpan.org>.  He contributed many hours' work
447         into POE and quite a lot of ideas.  Years later, I decide he's right
448         and actually implement them.
449
450         Artur is the author of Filter::HTTPD and Filter::Reference, as well
451         as bits and pieces throughout POE.  His feedback, testing, design and
452         inspiration have been instrumental in making POE what it is today.
453
454         Artur is investing his time heavily into perl 5's iThreads and PONIE
455         at the moment.  This project has far-reaching implications for POE's
456         future.
457
458       Jos Boumans
459         Jos Boumans is <kane@cpan.org>, aka "kane".  Jos is a major driving
460         force behind the POE::Simple movement and has helped inspire the
461         POE::Components for TCP clients and servers.
462
463       Matt Cashner
464         Matt Cashner is <sungo@pobox.com>, aka "sungo".  Matt is one of POE's
465         core developers.  He's spearheaded the movement to simplify POE for
466         new users, flattening the learning curve and making the system more
467         accessible to everyone.  He uses the system in mission critical
468         applications, folding feedback and features back into the
469         distribution for everyone's enjoyment.
470
471       Andrew Chen
472         Andrew Chen is <achen-poe@micropixel.com>.  Andrew is the resident
473         POE/Windows guru.  He contributes much needed testing for Solaris on
474         the SPARC and Windows on various Intel platforms.
475
476       Douglas Couch
477         Douglas Couch is <dscouch@purdue.edu>.  Douglas helped port and
478         maintain POE for Windows early on.
479
480       Jeffrey Goff
481         Jeffrey Goff is <jgoff@blackboard.com>.  Jeffrey is the author of
482         several POE modules, including a tokenizing filter and a component
483         for managing user information, PoCo::UserBase.  He's also co-author
484         of "A Beginner's Introduction to POE" at www.perl.com.
485
486       Philip Gwyn
487         Philip Gwyn is <gwynp@artware.qc.ca>.  He extended the Wheels I/O
488         abstraction to support hot-swappable filters, and he eventually
489         convinced Rocco that unique session and kernel IDs were a good thing.
490
491         Philip also enhanced POE::Filter::Reference to support different
492         serialization methods.  He has also improved POE's quality by finding
493         and fixing several bugs.  He provided POE a much needed code review
494         around version 0.06.
495
496         Lately, Philip tracked down the race condition in signal handling and
497         fixed it with the signal pipe.
498
499       Arnar M. Hrafnkelsson
500         Arnar is <addi@umich.edu>.  Addi tested POE and POE::Component::IRC
501         on Windows, finding bugs and testing fixes.  He appears throughout
502         the Changes file.  He has also written "cpoe", which is a POE-like
503         library for C.
504
505       Dave Paris
506         Dave Paris is <dparis@w3works.com>.  Dave tested and benchmarked POE
507         around version 0.05, discovering some subtle (and not so subtle)
508         timing problems.  The pre-forking server sample was his idea.
509         Versions 0.06 and later scaled to higher loads because of his work.
510         He has contributed a lot of testing and feedback, much of which is
511         tagged in the Changes file as a-mused.  The man is scarily good at
512         testing and troubleshooting.
513
514       Dieter Pearcey
515         Dieter Pearcey is <dieter@bullfrog.perlhacker.org>.  He goes by
516         several Japanese nicknames.  Dieter's current area of expertise is in
517         Wheels and Filters.  He greatly improved POE::Wheel::FollowTail, and
518         his Filter contributions include the basic Block filter, as well as
519         Stackable, RecordBlock, Grep and Map.
520
521       Plixer International
522         Plixer International is at <http://plixer.com/>.  Their sponsorship
523         has helped POE 1.300 and beyond be significantly more robust using
524         iThreads, especially when using fork() in Windows.
525
526       Robert Seifer
527         Robert Seifer is <e-mail unknown>.  He rotates IRC nicknames
528         regularly.
529
530         Robert contributed entirely too much time, both his own and his
531         computers, towards the detection and eradication of a memory
532         corruption bug that POE tickled in earlier Perl versions.  In the
533         end, his work produced a simple compile-time hack that worked around
534         a problem relating to anonymous subs, scope and @{} processing.
535
536       Matt Sergeant
537         Matt contributed "POE::Kernel::Poll", a more efficient way to watch
538         multiple files than select().  It's since been moved to
539         POE::Loop::IO_Poll.
540
541       Richard Soderberg
542         Richard Soderberg is <poe@crystalflame.net>, aka "coral".  Richard is
543         a collaborator on several side projects involving POE.  His work
544         provides valuable testing and feedback from a user's point of view.
545
546       Dennis Taylor
547         Dennis Taylor is <dennis@funkplanet.com>.  Dennis has been testing,
548         debugging and patching bits here and there, such as Filter::Line
549         which he improved by leaps in 0.1102.  He's also the author of
550         POE::Component::IRC, the widely popular POE-based successor to his
551         wildly popular Net::IRC library.
552
553       David Davis
554         David Davis, aka Xantus is <xantus@cpan.org>.  David contributed
555         patches to the HTTPD filter, and added CALLER_STATE to POE::Session.
556         He is the author of Sprocket, a networking framework built on POE.
557
558       Others?
559         Please contact the author if you've been forgotten and would like to
560         be included here.
561
562   Author
563       Rocco Caputo
564         Rocco Caputo is <rcaputo@cpan.org>.  POE is his brainchild.  He
565         wishes to thank you for your interest, and he has more thanks than he
566         can count for all the people who have contributed.  POE would not be
567         nearly as cool without you.
568
569         Except where otherwise noted, POE is Copyright 1998-2013 Rocco
570         Caputo.  All rights reserved.  POE is free software; you may
571         redistribute it and/or modify it under the same terms as Perl itself.
572
573       Thank you for reading!
574
575
576
577perl v5.38.0                      2023-07-21                            POE(3)
Impressum