1POE(3) User Contributed Perl Documentation POE(3)
2
6 POE - portable multitasking and networking framework for Perl
7
9 #!/usr/bin/perl -w
10 use strict;
11 # Use POE!
13 use POE;
14 sub handler_start {
16 my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
17 print "Session ", $session->ID, " has started.\n";
18 $heap->{count} = 0;
19 $kernel->yield('increment');
20 }
21 sub handler_increment {
23 my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
24 print "Session ", $session->ID, " counted to ", ++$heap->{count}, ".\n";
25 $kernel->yield('increment') if $heap->{count} < 10;
26 }
27 sub handler_stop {
29 print "Session ", $_[SESSION]->ID, " has stopped.\n";
30 }
31 for (1..10) {
33 POE::Session->create(
34 inline_states => {
35 _start => \&handler_start,
36 increment => \&handler_increment,
37 _stop => \&handler_stop,
38 }
39 );
40 }
41 POE::Kernel->run();
43 exit;
44
46 POE is a framework for cooperative, event driven multitasking in Perl.
47 Other languages have similar frameworks. Python has Twisted. TCL has
48 "the event loop".
49 POE originally was developed as the core of a persistent object server
51 and runtime environment. It has evolved into a general purpose multi‐
52 tasking and networking framework, encompassing and providing a consis‐
53 tent interface to other event loops such as Event and the Tk and Gtk
54 toolkits.
55 POE is written in layers, each building upon previous ones. It's
57 therefore possible to use POE at varying levels of abstraction.
58 The most basic layer is comprised of POE::Kernel and POE::Session. The
60 former class acts as POE's event watcher and dispatcher, while the lat‐
61 ter encapsulates the notion of an event driven task.
62 POE::Wheel classes operate at a slightly higher level. They plug into
64 sessions and perform very common, general tasks. For example,
65 POE::Wheel::ReadWrite performs buffered I/O. Unlike cheese, wheels do
66 not stand alone. They are customized by POE::Driver and POE::Filter
67 classes. Using the appropriate filter, a ReadWrite wheel can read and
68 write streams, lines, fixed-length blocks, HTTP requests and responses,
69 and so on.
70 The highest level of POE programming uses components. They may perform
72 narrowly defined tasks, such as POE::Component::Child (on the CPAN).
73 Often they encapsulate nearly everything necessary for an entire pro‐
74 gram.
75 Every level eventually boils down to the lowest common denomina‐
77 tor---POE::Kernel and POE::Session. Because of this, classes coexist
78 and cooperate at every level of abstraction.
79
81 POE's documentation rewards the methodical reader. Skim everything,
82 and you should have a pretty good idea of what's available and where to
83 find it later.
84 You're reading the main POE document. It's the general entry point to
86 POE's documentation.
87 Documentation for POE's basic features is spread across POE::Kernel and
89 POE::Session in non-intuitive ways. POE turns out to be difficult to
90 document from either module's perspective, so there is a lot of overlap
91 and cross-referencing. We have plans to rewrite them, but that only
92 helps if you want to join in the fun.
93 POE::NFA is a second kind of session---a Non-deterministic Finite Au‐
95 tomaton class, which happens to be driven by events. This is an
96 abstract state machine, which can be either Mealy or Moore (or a little
97 bit of both, or neither) depending on how it's configured.
98 POE::Wheel, POE::Driver, POE::Filter, and POE::Component describe
100 entire classes of modules in broad strokes. Where applicable, they
101 document the features common among their subclasses. This is confus‐
102 ing, since most people are inclined to read POE::Wheel::Foo and assume
103 that something doesn't exist if it's not there.
104 There are also some helper classes. POE::Pipe is the base class for
106 POE::Pipe::OneWay and POE::Pipe::TwoWay. They are portable pipe cre‐
107 ation functions, mainly for POE's test suite. POE::Preprocessor, a
108 macro language implemented as a source filter, has been split off into
109 its own distribution: Filter::Template.
110 POE is a relatively large system. It includes internal classes that
112 allow it to be customized without needing to know too much about the
113 system as a whole. POE::Queue describes POE's event queue interface.
114 POE::Loop covers the commonalities of every event loop POE supports.
115 POE::Resource discusses the notion of system resources, which corre‐
116 spond to event watchers and generators in other systems.
117 The SEE ALSO sections of each major module class will list the sub‐
119 classes beneath it. This document's SEE ALSO lists every module in the
120 distribution.
121 Finally, there are many POE resources on the web. The CPAN contains a
123 growing number of POE modules. POE's wiki, at <http://poe.perl.org/>,
124 includes tutorials, an extensive set of examples, documentation, and
125 more.
126
128 The developers of POE strive to make it as portable as possible. If
129 you discover a problem, please e-mail a report to
130 <bug-POE@rt.cpan.org>. If you can, include error messages, "perl -V"
131 output, and/or test cases. The more information you can provide, the
132 quicker we can turn around a fix. Patches are also welcome, of course.
133 POE is known to work on FreeBSD, MacOS X, Linux, Solaris, and other
135 forms of UNIX. It also works to one extent or another on various ver‐
136 sions of Windows, including 98, ME, NT, 2000, and XP. It should work
137 on OS/2, although we no longer have a developer who uses it. It has
138 been reported to work on MacOS 9, of all things.
139 POE has been tested with Perl versions as far back as 5.004_03 and as
141 recent as 5.8.3.
142 Thanks go out to the CPAN testers, who have dedicated resources to run‐
144 ning new modules on a variety of platforms. The latest POE tests are
145 visible at <http://testers.cpan.org/search?request=dist&dist=POE>.
146 We try to cover all of POE with our test suite, although we only suc‐
148 ceed in exercising about 70% of its code at any given time. A coverage
149 report is online at <http://poe.perl.org/?POE's_test_coverage_report>.
150 Specific issues:
152 Various Unices
154 No known problems.
155 OS/2
157 No known problems. POE has no OS/2 tester as of version 0.1206.
158 Windows
160 POE seems to work very nicely with Perl compiled for Cygwin. If you
161 must use ActiveState Perl, please use the absolute latest version.
162 ActiveState Perl's compatibility fluctuates from one build to
163 another, so we only support the most recent build prior to POE's
164 release.
165 POE's Windows port is current maintained by Rocco Caputo, but he has
167 only limited knowledge of Windows development. Please contact Rocco
168 if you or someone you know would like to accelerate POE's Windows
169 support.
170 A number of people have helped bring POE's Windows support this far,
172 through contributions of time, patches, and other resources. Some of
173 them are: Sean Puckett, Douglas Couch, Andrew Chen, Uhlarik Ondoej,
174 and Nick Williams.
175 TODO: I'm sure there are others. Find them in the changelog and
177 thank them here.
178 MacOS
180 No known problems on MacOS X.
181 Mac Classic (versions 9.x and before) was reported to work at one
183 time, but it seems like a lost cause unless someone would like to
184 step forward and make it happen.
185
187 POE's installer will prompt for required and optional modules. It's
188 important to read the prompts and only install what you will need. You
189 may always reinstall it later, adding new prerequisites as the need
190 arises.
191 Time::HiRes is recommended. POE will work without it, but alarms and
193 other features will be much more accurate with it.
194 POE relies heavily on constants in the POSIX module. Some of the con‐
196 stants aren't defined on some platforms. POE works around this as best
197 it can, but problems occasionally crop up. Please let us know if you
198 run into problems, and we'll work with you to fix them.
199 Filter::Reference needs a module to serialize data for transporting it
201 across a network. It will use Storable, FreezeThaw, YAML, or some
202 other package with freeze() and thaw() methods. It can also use Com‐
203 press::Zlib to conserve bandwidth and reduce latency over slow links,
204 but it's not required.
205 If you want to write web servers, you'll need to install libwww-perl,
207 which requires libnet. This is a small world of modules that includes
208 HTTP::Status, HTTP::Request, HTTP::Date, and HTTP::Response. They are
209 generally good to have, and recent versions of Perl include them.
210 Programs that use Wheel::Curses require the Curses module, which in
212 turn requires some sort of curses library.
213
215 These are Internet resources where you may find more information about
216 POE.
217 POE's Mailing List
219 POE has a mailing list where you can discuss it with the community at
220 large. You can receive subscription information by sending e-mail
221 to:
222 To: poe-help@perl.org
224 Subject: (anything will do)
225 The message body is ignored.
227 POE's Web Site
229 POE's web site contains the latest development snapshot along with
230 examples, tutorials, and other fun stuff. It's at
231 <http://poe.perl.org/>.
232 SourceForge
234 POE is developed at SourceForge. The project is hosted at
235 http://sourceforge.net/projects/poe/
236
238 POE::Kernel, POE::Session, POE::NFA
239 POE::Wheel, POE::Wheel::Curses, POE::Wheel::FollowTail,
241 POE::Wheel::ListenAccept, POE::Wheel::ReadLine, POE::Wheel::ReadWrite,
242 POE::Wheel::Run, POE::Wheel::SocketFactory
243 POE::Driver, POE::Driver::SysRW
245 POE::Filter, POE::Filter::Block, POE::Filter::Grep, POE::Filter::HTTPD,
247 POE::Filter::Line, POE::Filter::Map, POE::Filter::RecordBlock,
248 POE::Filter::Reference, POE::Filter::Stackable, POE::Filter::Stream
249 POE::Component, POE::Component::Client::TCP, POE::Compo‐
251 nent::Server::TCP
252 POE::Loop, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
254 POE::Loop::Select, POE::Loop::Tk
255 POE::Pipe, POE::Pipe::OneWay, POE::Pipe::TwoWay
257 POE::Queue, POE::Queue::Array
259 POE::Resource, POE::Resource::Aliases, POE::Resource::Events,
261 POE::Resource::Extrefs, POE::Resource::FileHandles, POE::Resource::Per‐
262 formance, POE::Resource::SIDs, POE::Resource::Sessions,
263 POE::Resource::Signals
264
266 The tests only cover about 70% of POE.
267 Bug reports, suggestions, and feedback of all kinds should be e-mailed
269 to <bug-POE@rt.cpan.org>. It will be entered into our request queue
270 where it will remain until addressed. If your return address is valid,
271 you will be notified when the status of your request changes.
272 Outstanding issues, including wish list items, are available in POE's
274 RT queue at <http://rt.cpan.org/>.
275
277 POE is the combined effort of several people. Please let us know if
278 someone is missing from this list.
279 TODO: Scour the CHANGES file for credit where it's due.
281 Ann Barcomb
283 Ann Barcomb is <kudra@domaintje.com>, aka "kudra". Ann contributed
284 large portions of POE::Simple and the code that became the ReadWrite
285 support in POE::Component::Server::TCP. Her ideas also inspired
286 Client::TCP component, introduced in version 0.1702.
287 Artur Bergman
289 Artur Bergman is <sky@cpan.org>. He contributed many hours' work
290 into POE and quite a lot of ideas. Years later, I decide he's right
291 and actually implement them.
292 Artur is the author of Filter::HTTPD and Filter::Reference, as well
294 as bits and pieces throughout POE. His feedback, testing, design and
295 inspiration have been instrumental in making POE what it is today.
296 Artur is investing his time heavily into perl 5's iThreads and PONIE
298 at the moment. This project has far-reaching implications for POE's
299 future.
300 Jos Boumans
302 Jos Boumans is <boumans@frg.eur.nl>, aka "Co-Kane". Jos is a major
303 driving force behind the POE::Simple movement and has helped inspire
304 the POE::Components for TCP clients and servers.
305 Matt Cashner
307 Matt Cashner is <sungo@pobox.com>, aka "sungo". Matt is one of POE's
308 core developers. He's spearheaded the movement to simplify POE for
309 new users, flattening the learning curve and making the system more
310 accessible to everyone. He uses the system in mission critical
311 applications, folding feedback and features back into the distribu‐
312 tion for everyone's enjoyment.
313 Andrew Chen
315 Andrew Chen is <achen-poe@micropixel.com>. Andrew is the resident
316 POE/Windows guru. He contributes much needed testing for Solaris on
317 the SPARC and Windows on various Intel platforms.
318 Douglas Couch
320 Douglas Couch is <dscouch@purdue.edu>. Douglas helped port and main‐
321 tain POE for Windows early on.
322 Jeffrey Goff
324 Jeffrey Goff is <jgoff@blackboard.com>. Jeffrey is the author of
325 several POE modules, including a tokenizing filter and a component
326 for managing user information, PoCo::UserBase. He's also co-author
327 of "A Beginner's Introduction to POE" at www.perl.com.
328 Philip Gwyn
330 Philip Gwyn is <gwynp@artware.qc.ca>. He extended the Wheels I/O
331 abstraction to support hot-swappable filters, and he eventually con‐
332 vinced Rocco that unique session and kernel IDs were a good thing.
333 Philip also enhanced Filter::Reference to support different serial‐
335 ization methods. He has also improved POE's quality by finding and
336 fixing several bugs. He provided POE a much needed code review
337 around version 0.06.
338 Arnar M. Hrafnkelsson
340 Arnar is <addi@umich.edu>. Addi tested POE and POE::Component::IRC
341 on Windows, finding bugs and testing fixes. He appears throughout
342 the Changes file. He has also written "cpoe", which is a POE-like
343 library for C.
344 Dave Paris
346 Dave Paris is <dparis@w3works.com>. Dave tested and benchmarked POE
347 around version 0.05, discovering some subtle (and not so subtle) tim‐
348 ing problems. The pre-forking server sample was his idea. Versions
349 0.06 and later scaled to higher loads because of his work. He has
350 contributed a lot of testing and feedback, much of which is tagged in
351 the Changes file as a-mused. The man is scarily good at testing and
352 troubleshooting.
353 Dieter Pearcey
355 Dieter Pearcey is <dieter@bullfrog.perlhacker.org>. He goes by sev‐
356 eral Japanese nicknames. Dieter's current area of expertise is in
357 Wheels and Filters. He greatly improved Wheel::FollowTail, and his
358 Filter contributions include the basic Block filter, as well as
359 Stackable, RecordBlock, Grep and Map.
360 Robert Seifer
362 Robert Seifer is <e-mail unknown>. He rotates IRC nicknames regu‐
363 larly.
364 Robert contributed entirely too much time, both his own and his com‐
366 puters, towards the detection and eradication of a memory corruption
367 bug that POE tickled in earlier Perl versions. In the end, his work
368 produced a simple compile-time hack that worked around a problem
369 relating to anonymous subs, scope and @{} processing.
370 Matt Sergeant
372 Matt contributed POE::Kernel::Poll, a more efficient way to watch
373 multiple files than select(). It's since been moved to
374 POE::Loop::IO_Poll.
375 Richard Soderberg
377 Richard Soderberg is <poe@crystalflame.net>, aka "coral". Richard is
378 a collaborator on several side projects involving POE. His work pro‐
379 vides valuable testing and feedback from a user's point of view.
380 Dennis Taylor
382 Dennis Taylor is <dennis@funkplanet.com>. Dennis has been testing,
383 debugging and patching bits here and there, such as Filter::Line
384 which he improved by leaps in 0.1102. He's also the author of
385 POE::Component::IRC, the widely popular POE-based successor to his
386 wildly popular Net::IRC library.
387 Others?
389 Please contact the author if you've been forgotten.
390 Author
392 Rocco Caputo
394 Rocco Caputo is <rcaputo@cpan.org>. POE is his brainchild.
395 Except where otherwise noted, POE is Copyright 1998-2005 Rocco
397 Caputo. All rights reserved. POE is free software; you may redis‐
398 tribute it and/or modify it under the same terms as Perl itself.
399 Thank you for reading!
401perl v5.8.8 2006-09-01 POE(3)