1POE(3) User Contributed Perl Documentation POE(3)
2
6 POE - portable multitasking and networking framework for any event loop
7
9 #!/usr/bin/perl
10 use warnings;
12 use strict;
13 use POE; # Auto-includes POE::Kernel and POE::Session.
15 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 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 sub handler_stop {
30 print "Session ", $_[SESSION]->ID, " has stopped.\n";
31 }
32 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 POE::Kernel->run();
44 exit;
45
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 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 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 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 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 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 Layer 1: Kernel and Sessions
77 The lowest public layer is comprised of POE::Kernel, POE::Session, and
78 other session types.
79 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 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 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 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 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 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 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 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 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 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 Also of interest is POE::Component::Generic, which allows you to create
128 a POE component from nearly any blocking module.
129 There are quite a lot of components on the CPAN.
131 <http://search.cpan.org/search?query=poe+component&mode=all>
132 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 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 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 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 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 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
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 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 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 @_[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 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 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 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 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 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 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 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 See SEE ALSO
228 Wherever possible, the SEE ALSO section will cross-reference one module
229 to related ones.
230 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
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 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 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 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 Programs that use POE::Wheel::Curses will of course require the Curses
260 module, which in turn requires some sort of curses library.
261 If you're using POE with Tk, you'll need Tk installed.
263 And other obvious things. Let us know if we've overlooked a non-
265 obvious detail.
266
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 Despite Chris Williams' efforts, we can't test POE everywhere. Please
275 see the GETTING HELP section if you run into a problem.
276 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 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 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 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 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 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 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 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 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 Linux/Unix Issues
322 pty woes
323 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 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 Other Compatibility Issues
341 None currently known. See GETTING HELP below if you've run into
342 something.
343
345 POE's developers take pride in its quality. If you encounter a
346 problem, please let us know.
347 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 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 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 POE's Source Code
365 The following command will fetch the most current version of POE into
366 the "poe" subdirectory:
367 git clone https://github.com/rcaputo/poe.git
369 SourceForge
371 http://sourceforge.net/projects/poe/ is POE's project page.
372 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 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
385 Broken down by abstraction layer.
386 Layer 1
388 POE::Kernel, POE::Session, POE::NFA
389 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 POE::Driver, POE::Driver::SysRW
396 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 Layer 3
402 POE::Component, POE::Component::Client::TCP,
403 POE::Component::Server::TCP
404 Layer 0
406 POE::Loop, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
407 POE::Loop::Select, POE::Loop::Tk
408 POE::Queue, POE::Queue::Array
410 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 Helpers
416 POE::Pipe, POE::Pipe::OneWay, POE::Pipe::TwoWay
417 Home Page
419 http://poe.perl.org/
420 Bug Tracker
422 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=POE
423 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 Other Resources
430 https://metacpan.org/module/POE
431 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 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 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 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 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 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 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 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 Douglas Couch
477 Douglas Couch is <dscouch@purdue.edu>. Douglas helped port and
478 maintain POE for Windows early on.
479 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 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 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 Lately, Philip tracked down the race condition in signal handling and
497 fixed it with the signal pipe.
498 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 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 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 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 Robert Seifer
527 Robert Seifer is <e-mail unknown>. He rotates IRC nicknames
528 regularly.
529 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 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 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 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 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 Others?
559 Please contact the author if you've been forgotten and would like to
560 be included here.
561 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 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 Thank you for reading!
574perl v5.36.0 2023-01-20 POE(3)