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 -w
10 use strict;
11 use POE; # Auto-includes POE::Kernel and POE::Session.
13 sub handler_start {
15 my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
16 print "Session ", $session->ID, " has started.\n";
17 $heap->{count} = 0;
18 $kernel->yield('increment');
19 }
20 sub handler_increment {
22 my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
23 print "Session ", $session->ID, " counted to ", ++$heap->{count}, ".\n";
24 $kernel->yield('increment') if $heap->{count} < 10;
25 }
26 sub handler_stop {
28 print "Session ", $_[SESSION]->ID, " has stopped.\n";
29 }
30 for (1..10) {
32 POE::Session->create(
33 inline_states => {
34 _start => \&handler_start,
35 increment => \&handler_increment,
36 _stop => \&handler_stop,
37 }
38 );
39 }
40 POE::Kernel->run();
42 exit;
43
45 POE is a framework for cooperative, event driven multitasking and
46 networking in Perl. Other languages have similar frameworks. Python
47 has Twisted. TCL has "the event loop".
48 POE provides a unified interface for several other event loops,
50 including select(), IO::Poll, Glib, Gtk, Tk, Wx, and Gtk2. Many of
51 these event loop interfaces were written by others, with the help of
52 POE::Test::Loops. They may be found on the CPAN.
53 POE achieves its high degree of portability to different operating
55 systems and Perl versions by being written entirely in Perl. CPAN
56 hosts optional XS modules for POE if speed is more desirable than
57 portability.
58 POE is designed in layers. Each layer builds atop the lower level
60 ones. Programs are free to use POE at any level of abstraction, and
61 different levels can be mixed and matched seamlessly within a single
62 program. Remember, though, that higher-level abstractions often
63 require more resources than lower-level ones. The conveniences they
64 provide are not free.
65 POE's bundled abstraction layers are the tip of a growing iceberg.
67 Sprocket, POE::Stage, and other CPAN distributions build upon this
68 work. You're encouraged to look around.
69 No matter how high you go, though, it all boils down to calls to
71 POE::Kernel. So your down-to-earth code can easily cooperate with
72 stratospheric systems.
73 Layer 1: Kernel and Sessions
75 The lowest public layer is comprised of POE::Kernel, POE::Session, and
76 other session types.
77 POE::Kernel does most of the heavy lifting. It provides a portable
79 interface for filehandle activity detection, multiple alarms and other
80 timers, signal handling, and other less-common features.
81 POE::Session and derived classes encapsulate the notion of an event
83 driven task. They also customize event dispatch to a particular
84 calling convention. POE::NFA, for example, is more of a proper state
85 machine. The CPAN has several other kinds of sessions.
86 Everything ultimately builds on these classes or the concepts they
88 implement. If you're short on time, the things to read besides this
89 are POE::Kernel and POE::Session.
90 Layer 2: Wheels, Filters, and Drivers
92 POE::Wheel objects are dynamic mix-ins for POE::Session instances.
93 These "wheels" perform very common, generic tasks in a highly reusable
94 and customizable way. POE::Wheel::ReadWrite, for example, implements
95 non-blocking buffered I/O. Nearly everybody needs this, so why require
96 people to reinvent it all the time?
97 POE::Filter objects customize wheels in a modular way. Filters act as
99 I/O layers, turning raw streams into structured data, and serializing
100 structures into something suitable for streams. The CPAN also has
101 several of these.
102 Drivers are where the wheels meet the road. In this case, the road is
104 some type of file handle. Drivers do the actual reading and writing in
105 a standard way so wheels don't need to know the difference between
106 send() and syswrite().
107 POE::Driver objects get relatively short shrift because very few are
109 needed. The most common driver, POE::Driver::SysRW is ubiquitous and
110 also the default, so most people will never need to specify one.
111 Layer 3: Components
113 POE::Component classes are essentially Perl classes that use POE to
114 perform tasks in a non-blocking or cooperative way. This is a very
115 broad definition, and POE components are all over the abstraction map.
116 Many components, such as POE::Component::Server::SMTP, encapsulate the
118 generic details of an entire application. Others perform rather narrow
119 tasks, such as POE::Component::DirWatch::Object.
120 POE components are often just plain Perl objects. The previously
122 mentioned POE::Component::DirWatch::Object uses Moose. Other object
123 and meta-object frameworks are compatible.
124 Also of interest is POE::Component::Generic, which allows you to create
126 a POE component from nearly any blocking module.
127 There are quite a lot of components on the CPAN.
129 <http://search.cpan.org/search?query=poe+component&mode=all>
130 Layer 4 and Beyond: Frameworks and Object Metaphors
132 It's possible to abstract POE entirely behind a different framework.
133 In fact we encourage people to write domain-specific abstractions that
134 entirely hide POE if necessary. The nice thing here is that even at
135 these high levels of abstraction, things will continue to interoperate
136 all the way down to layer 1.
137 Two examples of ultra-high level abstraction are Sprocket, a networking
139 framework that does its own thing, and POE::Stage, which is POE's
140 creator's attempt to formalize and standardize POE components.
141 It is also possible to communicate between POE processes. This is
143 called IKC, for Inter-Kernel Communication. There are a few IKC
144 components on the CPAN
145 (<http://search.cpan.org/search?query=IKC&mode=all>), notably
146 POE::Component::IKC and POE::TIKC.
147 Layer 0: POE's Internals
149 POE's layered architecture continues below the surface. POE's guts are
150 broken into specific POE::Loop classes for each event loop it supports.
151 Internals are divided up by type, giving POE::Resource classes for
152 Aliases, Controls, Events, Extrefs, FileHandles, SIDs, Sessions and
153 Signals.
154 POE::Kernel's APIs are extensible through POE::API mix-in classes.
156 Some brave souls have even published new APIs on CPAN, such as
157 POE::API::Peek (which gives you access to some of the internal
158 POE::Resource methods).
159 By design, it's possible to implement new POE::Kernel guts by creating
161 another POE::Resource class. One can then expose the functionality
162 with a new POE::API mix-in.
163
165 You're reading the main POE documentation. It's the general entry
166 point to the world of POE. You already know this, however, so let's
167 talk about something more interesting.
168 Basic Features
170 POE's basic features are documented mainly in POE::Kernel and
171 POE::Session. Methods are documented in the classes that implement
172 them. Broader concepts are covered in the most appropriate class, and
173 sometimes they are divided among classes that share in their
174 implementation.
175 Basic Usage
177 Basic usage, even for POE.pm, is documented in POE::Kernel. That's
178 where most of POE's work is done, and POE.pm is little more than a
179 class loader.
180 @_[KERNEL, HEAP, etc.]
182 Event handler calling conventions, that weird @_[KERNEL, HEAP] stuff,
183 is documented in POE::Session. That's because POE::Session implements
184 the calling convention, and other session types often do it
185 differently.
186 Base Classes Document Common Features
188 The POE::Wheel, POE::Driver, POE::Filter, and POE::Component base
189 classes describe what's common among each class. It's a good idea to
190 at least skim the base class documentation since the subclasses tend
191 not to rehash the common things.
192 POE::Queue, POE::Resource, and POE::Loop document the concepts and
194 sometimes the standard interfaces behind multiple subclasses. You're
195 encouraged to have a look.
196 Helper Classes
198 POE includes some helper classes for portability. POE::Pipe, and its
199 subclasses POE::Pipe::OneWay and POE::Pipe::TwoWay are portable pipes.
200 Event Loop Bridges
202 POE::Loop documents and specifies the interface for all of POE's event
203 loop bridges. The individual classes may document specific details,
204 but generally they adhere to the spec strongly enough that they don't
205 need to.
206 Many of the existing POE::Loop bridges provided in POE's base
208 distribution will move out to separate distributions shortly. The
209 documentation will probably remain the same, however.
210 POE::Queue and POE::Queue::Array
212 POE's event queue is basically a priority heap implemented as an
213 ordered array. POE::Queue documents the standard interface for POE
214 event queues, and POE::Queue::Array implements the ordered array queue.
215 Tony Cook has released POE::XS::Queue::Array, which is a drop-in C
216 replacement for POE::Queue::Array. You might give it a try if you need
217 more performance. POE's event queue is some of the hottest code in the
218 system.
219 This Section Isn't Complete
221 Help organize the documentation. Obviously we can't think of
222 everything. We're well aware of this and welcome audience
223 participation.
224 See SEE ALSO
226 Wherever possible, the SEE ALSO section will cross-reference one module
227 to related ones.
228 Don't Forget the Web
230 Finally, there are many POE resources on the web. The CPAN contains a
231 growing number of POE modules. <http://poe.perl.org/> hosts POE's
232 wiki, which includes tutorials, an extensive set of examples,
233 documentation, and more. Plus it's a wiki, so you can trivially pitch
234 in your two cents.
235
237 POE's basic requirements are rather light. Most are included with
238 modern versions of Perl, and the rest (if any) should be generally
239 portable by now.
240 Time::HiRes is highly recommended, even for older Perls that don't
242 include it. POE will work without it, but alarms and other features
243 will be much more accurate if it's included. POE::Kernel will use
244 Time::HiRes automatically if it's available.
245 POE::Filter::Reference needs a module to serialize data for
247 transporting it across a network. It will use Storable, FreezeThaw,
248 YAML, or some other package with freeze() and thaw() methods. It can
249 also use Compress::Zlib to conserve bandwidth and reduce latency over
250 slow links, but it's not required.
251 If you want to write web servers, you'll need to install libwww-perl,
253 which requires libnet. This is a small world of modules that includes
254 HTTP::Status, HTTP::Request, HTTP::Date, and HTTP::Response. They are
255 generally good to have, and modern versions of Perl even include them.
256 Programs that use POE::Wheel::Curses will of course require the Curses
258 module, which in turn requires some sort of curses library.
259 If you're using POE with Tk, you'll need Tk installed.
261 And other obvious things. Let us know if we've overlooked a non-
263 obvious detail.
264
266 One of POE's design goals is to be as portable as possible. That's why
267 it's written in "Plain Perl". XS versions of POE modules are available
268 as third-party distributions. Parts of POE that require nonstandard
269 libraries are optional, and not having those libraries should not
270 prevent POE from installing.
271 Despite Chris Williams' efforts, we can't test POE everywhere. Please
273 see the GETTING HELP section if you run into a problem.
274 POE is expected to work on most forms of UNIX, including FreeBSD, MacOS
276 X, Linux, Solaris. Maybe even AIX and QNX, but we're not sure.
277 POE is also tested on Windows XP, using the latest version of
279 ActiveState, Strawberry and Cygwin Perl. POE is fully supported with
280 Strawberry Perl, as it's included in the Strawberry distribution.
281 OS/2 and MacOS 9 have been reported to work in the past, but nobody
283 seems to be testing there anymore. Reports and patches are still
284 welcome.
285 Past versions of POE have been tested with Perl versions as far back as
287 5.6.2 and as recent as "blead", today's development build. We can no
288 longer guarantee each release will work everywhere, but we will be
289 happy to work with you if you need special support for a really old
290 system. You can always use older POE releases that works on your
291 version, please check BackPAN
292 <http://backpan.perl.org/authors/id/R/RC/RCAPUTO/>.
293 POE's quality is due in large part to the fine work of Chris Williams
295 and the other CPAN testers. They have dedicated resources towards
296 ensuring CPAN distributions pass their own tests, and we watch their
297 reports religiously. You can, too. The latest POE test reports can be
298 found at <http://cpantesters.org/distro/P/POE.html>.
299 Thanks also go out to Benjamin Smith and the 2006 Google Summer of
301 Code. Ben was awarded a grant to improve POE's test suite, which he
302 did admirably.
303 Windows Issues
305 POE seems to work very nicely with Perl compiled for Cygwin. If you
306 must use ActiveState Perl, please use the absolute latest version.
307 ActiveState Perl's compatibility fluctuates from one build to another,
308 so we tend not to support older releases.
309 Windows and ActiveState Perl are considered an esoteric platform due to
311 the complex interactions between various versions. POE therefore
312 relies on user feedback and support here.
313 A number of people have helped bring POE's Windows support this far,
315 through contributions of time, patches, and other resources. Some of
316 them are: Sean Puckett, Douglas Couch, Andrew Chen, Uhlarik Ondoej,
317 Nick Williams, and Chris Williams (no relation).
318 Linux/Unix Issues
320 pty woes
321 Some distributions chose to not completely setup the pseudo-tty
323 support. This is needed for POE::Wheel::Run to interact with the
324 subprocess. If you see something like this while running "make test"
325 please look at your distribution's documentation on how to fix it. For
326 example, on Debian-based systems the solution was to execute "sudo apt-
327 get install udev".
328 t/30_loops/io_poll/wheel_run.t ..................... 1/99
330 pty_allocate(nonfatal): posix_openpt(): No such file or directory at /usr/local/lib/perl/5.10.0/IO/Pty.pm line 24.
331 ...
332 Cannot open a pty at /home/apoc/poe/blib/lib/POE/Wheel/Run.pm line 251
333 Compilation failed in require at t/30_loops/io_poll/wheel_run.t line 24.
334 # Looks like you planned 99 tests but ran 5.
335 # Looks like your test exited with 22 just after 5.
336 t/30_loops/io_poll/wheel_run.t ..................... Dubious, test returned 22 (wstat 5632, 0x1600)
337 Other Compatibility Issues
339 None currently known. See GETTING HELP below if you've run into
340 something.
341
343 POE's developers take pride in its quality. If you encounter a
344 problem, please let us know.
345 POE's Request Tracker
347 You're welcome to e-mail questions and bug reports to
348 <bug-POE@rt.cpan.org>. This is not a realtime support channel, though.
349 If you need a more immediate response, try one of the methods below.
350 POE's Mailing List
352 POE has a dedicated mailing list where developers and users discuss the
353 software and its use. You're welcome to join us. Send an e-mail to
354 <poe-help@perl.org> for subscription instructions. The subject and
355 message body are ignored.
356 POE's Web Site
358 <http://poe.perl.org> contains recent information, tutorials, and
359 examples. It's also a wiki, so people are invited to share tips and
360 code snippets there as well.
361 POE's Source Code
363 The following command will fetch the most current version of POE into
364 the "poe" subdirectory:
365 svn co https://poe.svn.sourceforge.net/svnroot/poe poe
367 SourceForge
369 http://sourceforge.net/projects/poe/ is POE's project page.
370 Internet Relay Chat (IRC)
372 irc.perl.org channel #poe is an informal place to waste some time and
373 maybe even discuss Perl and POE. Consider an SSH relay if your
374 workplace frowns on IRC. But only if they won't fire you if you're
375 caught.
376 Personal Support
378 Unfortunately we don't have resources to provide free one-on-one
379 personal support anymore. We'll do it for a fee, though. Send Rocco
380 an e-mail via his CPAN address.
381
383 Broken down by abstraction layer.
384 Layer 1
386 POE::Kernel, POE::Session, POE::NFA
387 Layer 2
389 POE::Wheel, POE::Wheel::Curses, POE::Wheel::FollowTail,
390 POE::Wheel::ListenAccept, POE::Wheel::ReadLine, POE::Wheel::ReadWrite,
391 POE::Wheel::Run, POE::Wheel::SocketFactory
392 POE::Driver, POE::Driver::SysRW
394 POE::Filter, POE::Filter::Block, POE::Filter::Grep, POE::Filter::HTTPD,
396 POE::Filter::Line, POE::Filter::Map, POE::Filter::RecordBlock,
397 POE::Filter::Reference, POE::Filter::Stackable, POE::Filter::Stream
398 Layer 3
400 POE::Component, POE::Component::Client::TCP,
401 POE::Component::Server::TCP
402 Layer 0
404 POE::Loop, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
405 POE::Loop::Select, POE::Loop::Tk
406 POE::Queue, POE::Queue::Array
408 POE::Resource, POE::Resource::Aliases, POE::Resource::Events,
410 POE::Resource::Extrefs, POE::Resource::FileHandles,
411 POE::Resource::SIDs, POE::Resource::Sessions, POE::Resource::Signals
412 Helpers
414 POE::Pipe, POE::Pipe::OneWay, POE::Pipe::TwoWay
415 Home Page
417 http://poe.perl.org/
418 Bug Tracker
420 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=POE
421 Repositories and Changes
423 Thanks to the magic of distributed version control, POE is hosted at
424 three locations for redundancy. You can browse the source at any one
425 of:
426 https://github.com/rcaputo/poe
428 https://gitorious.org/poe
430 http://poe.git.sourceforge.net/git/gitweb-index.cgi
432 Complete change logs can also be browsed at those sites. They all
434 provide RSS news feeds for those who want to follow development in
435 near-realtime.
436 Other Resources
438 https://metacpan.org/module/POE
439 http://search.cpan.org/dist/POE
441
443 POE is the combined effort of quite a lot of people. This is an
444 incomplete list of some early contributors. A more complete list can
445 be found in POE's change log.
446 Ann Barcomb
448 Ann Barcomb is <kudra@domaintje.com>, aka "kudra". Ann contributed
449 large portions of POE::Simple and the code that became the ReadWrite
450 support in POE::Component::Server::TCP. Her ideas also inspired
451 Client::TCP component, introduced in version 0.1702.
452 Artur Bergman
454 Artur Bergman is <sky@cpan.org>. He contributed many hours' work
455 into POE and quite a lot of ideas. Years later, I decide he's right
456 and actually implement them.
457 Artur is the author of Filter::HTTPD and Filter::Reference, as well
459 as bits and pieces throughout POE. His feedback, testing, design and
460 inspiration have been instrumental in making POE what it is today.
461 Artur is investing his time heavily into perl 5's iThreads and PONIE
463 at the moment. This project has far-reaching implications for POE's
464 future.
465 Jos Boumans
467 Jos Boumans is <kane@cpan.org>, aka "kane". Jos is a major driving
468 force behind the POE::Simple movement and has helped inspire the
469 POE::Components for TCP clients and servers.
470 Matt Cashner
472 Matt Cashner is <sungo@pobox.com>, aka "sungo". Matt is one of POE's
473 core developers. He's spearheaded the movement to simplify POE for
474 new users, flattening the learning curve and making the system more
475 accessible to everyone. He uses the system in mission critical
476 applications, folding feedback and features back into the
477 distribution for everyone's enjoyment.
478 Andrew Chen
480 Andrew Chen is <achen-poe@micropixel.com>. Andrew is the resident
481 POE/Windows guru. He contributes much needed testing for Solaris on
482 the SPARC and Windows on various Intel platforms.
483 Douglas Couch
485 Douglas Couch is <dscouch@purdue.edu>. Douglas helped port and
486 maintain POE for Windows early on.
487 Jeffrey Goff
489 Jeffrey Goff is <jgoff@blackboard.com>. Jeffrey is the author of
490 several POE modules, including a tokenizing filter and a component
491 for managing user information, PoCo::UserBase. He's also co-author
492 of "A Beginner's Introduction to POE" at www.perl.com.
493 Philip Gwyn
495 Philip Gwyn is <gwynp@artware.qc.ca>. He extended the Wheels I/O
496 abstraction to support hot-swappable filters, and he eventually
497 convinced Rocco that unique session and kernel IDs were a good thing.
498 Philip also enhanced POE::Filter::Reference to support different
500 serialization methods. He has also improved POE's quality by finding
501 and fixing several bugs. He provided POE a much needed code review
502 around version 0.06.
503 Lately, Philip tracked down the race condition in signal handling and
505 fixed it with the signal pipe.
506 Arnar M. Hrafnkelsson
508 Arnar is <addi@umich.edu>. Addi tested POE and POE::Component::IRC
509 on Windows, finding bugs and testing fixes. He appears throughout
510 the Changes file. He has also written "cpoe", which is a POE-like
511 library for C.
512 Dave Paris
514 Dave Paris is <dparis@w3works.com>. Dave tested and benchmarked POE
515 around version 0.05, discovering some subtle (and not so subtle)
516 timing problems. The pre-forking server sample was his idea.
517 Versions 0.06 and later scaled to higher loads because of his work.
518 He has contributed a lot of testing and feedback, much of which is
519 tagged in the Changes file as a-mused. The man is scarily good at
520 testing and troubleshooting.
521 Dieter Pearcey
523 Dieter Pearcey is <dieter@bullfrog.perlhacker.org>. He goes by
524 several Japanese nicknames. Dieter's current area of expertise is in
525 Wheels and Filters. He greatly improved POE::Wheel::FollowTail, and
526 his Filter contributions include the basic Block filter, as well as
527 Stackable, RecordBlock, Grep and Map.
528 Plixer International
530 Plixer International is at <http://plixer.com/>. Their sponsorship
531 has helped POE 1.300 and beyond be significantly more robust using
532 iThreads, especially when using fork() in Windows.
533 Robert Seifer
535 Robert Seifer is <e-mail unknown>. He rotates IRC nicknames
536 regularly.
537 Robert contributed entirely too much time, both his own and his
539 computers, towards the detection and eradication of a memory
540 corruption bug that POE tickled in earlier Perl versions. In the
541 end, his work produced a simple compile-time hack that worked around
542 a problem relating to anonymous subs, scope and @{} processing.
543 Matt Sergeant
545 Matt contributed "POE::Kernel::Poll", a more efficient way to watch
546 multiple files than select(). It's since been moved to
547 POE::Loop::IO_Poll.
548 Richard Soderberg
550 Richard Soderberg is <poe@crystalflame.net>, aka "coral". Richard is
551 a collaborator on several side projects involving POE. His work
552 provides valuable testing and feedback from a user's point of view.
553 Dennis Taylor
555 Dennis Taylor is <dennis@funkplanet.com>. Dennis has been testing,
556 debugging and patching bits here and there, such as Filter::Line
557 which he improved by leaps in 0.1102. He's also the author of
558 POE::Component::IRC, the widely popular POE-based successor to his
559 wildly popular Net::IRC library.
560 David Davis
562 David Davis, aka Xantus is <xantus@cpan.org>. David contributed
563 patches to the HTTPD filter, and added CALLER_STATE to POE::Session.
564 He is the author of Sprocket, a networking framework built on POE.
565 Others?
567 Please contact the author if you've been forgotten and would like to
568 be included here.
569 Author
571 Rocco Caputo
572 Rocco Caputo is <rcaputo@cpan.org>. POE is his brainchild. He
573 wishes to thank you for your interest, and he has more thanks than he
574 can count for all the people who have contributed. POE would not be
575 nearly as cool without you.
576 Except where otherwise noted, POE is Copyright 1998-2013 Rocco
578 Caputo. All rights reserved. POE is free software; you may
579 redistribute it and/or modify it under the same terms as Perl itself.
580 Thank you for reading!
582perl v5.28.1 2015-06-03 POE(3)