forked from rcaputo/poe
/
POE.pm
527 lines (373 loc) · 17 KB
/
POE.pm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
# $Id$
# Copyrights and documentation are after __END__.
package POE;
use strict;
use Carp;
use vars qw($VERSION $REVISION);
$VERSION = '0.2802';
$REVISION = do {my@r=(q$Revision$=~/\d+/g);sprintf"%d."."%04d"x$#r,@r};
sub import {
my $self = shift;
my @sessions = grep(/^(Session|NFA)$/, @_);
my @modules = grep(!/^(Kernel|Session|NFA)$/, @_);
croak "POE::Session and POE::NFA export conflicting constants"
if grep(/^(Session|NFA)$/, @sessions) > 1;
# If a session was specified, use that. Otherwise use Session.
if (@sessions) {
unshift @modules, @sessions;
}
else {
unshift @modules, 'Session';
}
# Add Kernel back in, whether anybody wanted it or not. Ensure that
# it comes before any sessions, since the sessions need to refer to
# constants defined in Kernel's namespace.
unshift @modules, 'Kernel';
my $package = (caller())[0];
my @failed;
foreach my $module (@modules) {
my $code = "package $package; use POE::$module;";
eval($code);
if ($@) {
warn $@;
push(@failed, $module);
}
}
@failed and croak "could not import qw(" . join(' ', @failed) . ")";
}
#------------------------------------------------------------------------------
sub new {
my $type = shift;
croak "$type is not meant to be used directly";
}
#------------------------------------------------------------------------------
1;
__END__
=head1 NAME
POE - portable multitasking and networking framework for Perl
=head1 SYNOPSIS
#!/usr/bin/perl -w
use strict;
# Use POE!
use POE;
sub handler_start {
my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
print "Session ", $session->ID, " has started.\n";
$heap->{count} = 0;
$kernel->yield('increment');
}
sub handler_increment {
my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
print "Session ", $session->ID, " counted to ", ++$heap->{count}, ".\n";
$kernel->yield('increment') if $heap->{count} < 10;
}
sub handler_stop {
print "Session ", $_[SESSION]->ID, " has stopped.\n";
}
for (1..10) {
POE::Session->create(
inline_states => {
_start => \&handler_start,
increment => \&handler_increment,
_stop => \&handler_stop,
}
);
}
POE::Kernel->run();
exit;
=head1 DESCRIPTION
POE is a framework for cooperative, event driven multitasking in Perl.
Other languages have similar frameworks. Python has Twisted. TCL has
"the event loop".
POE originally was developed as the core of a persistent object server
and runtime environment. It has evolved into a general purpose
multitasking and networking framework, encompassing and providing a
consistent interface to other event loops such as Event and the Tk and
Gtk toolkits.
POE is written in layers, each building upon the previous. It's
therefore possible to use POE at varying levels of abstraction.
The lowest level uses POE::Kernel and POE::Session. The former class
acts as POE's event watcher and dispatcher. The latter encapsulates
the notion of an event driven task.
POE::Wheel classes operate at a slightly higher level. They plug into
sessions and perform very common, general tasks. For example,
POE::Wheel::ReadWrite performs buffered I/O.
Unlike cheese, wheels do not stand alone. They are customized by
POE::Driver and POE::Filter classes. Using the proper filter, a
ReadWrite wheel can read and write streams, lines, fixed-length
blocks, HTTP requests and responses, and so on.
The highest level of POE programming uses components. They may
perform narrowly defined tasks, such as POE::Component::Child (on the
CPAN). Often they encapsulate nearly everything necessary for an
entire program.
Every level eventually boils down to the lowest common
denominator---POE::Kernel and POE::Session. Because of this, classes
coexist and cooperate at every level of abstraction.
=head1 DOCUMENTATION ROADMAP
POE's documentation rewards the methodical reader. Skim everything,
and you should have a pretty good idea of what's available and where
to find it later.
You're reading the main POE document. It's the general entry point to
POE's documentation.
Documentation for POE's basic features is spread across POE::Kernel
and POE::Session in non-intuitive ways. POE turns out to be difficult
to document from either module's perspective, so there is a lot of
overlap and cross-referencing. We have plans to rewrite them, but
that only helps if you want to join in the fun.
POE::NFA is a second kind of session---a Non-deterministic Finite
Automaton class, which happens to be driven by events. This is an
abstract state machine, which can be either Mealy or Moore (or a
little bit of both, or neither) depending on how it's configured.
POE::Wheel, POE::Driver, POE::Filter, and POE::Component describe
entire classes of modules in broad strokes. Where applicable, they
document the features common among their subclasses. This is
confusing, since most people are inclined to read POE::Wheel::Foo and
assume that something doesn't exist if it's not there.
There are also some helper classes. POE::Pipe is the base class for
POE::Pipe::OneWay and POE::Pipe::TwoWay. They are portable pipe
creation functions, mainly for POE's test suite. POE::Preprocessor is
a macro language implemented as a source filter.
POE is a relatively large system. It includes internal classes that
allow it to be customized without needing to know too much about the
system as a whole. POE::Queue describes POE's event queue interface.
POE::Loop covers the commonalities of every event loop POE supports.
POE::Resource discusses the notion of system resources, which
correspond to event watchers and generators in other systems.
The SEE ALSO sections of each major module class will list the
subclasses beneath it. This document's SEE ALSO lists every module in
the distribution.
Finally, there are many POE resources on the web. The CPAN contains a
growing number of POE modules. POE's wiki, at
L<http://poe.perl.org/>, includes tutorials, an extensive set of
examples, documentation, and more.
=head1 COMPATIBILITY ISSUES
The developers of POE strive to make it as portable as possible. If
you discover a problem, please e-mail a report to
<bug-POE@rt.cpan.org>. If you can, include error messages, perl -V
output, and/or test cases. The more information you can provide, the
quicker we can turn around a fix. Patches are also welcome, of
course.
POE is known to work on FreeBSD, MacOS X, Linux, Solaris, and other
forms of UNIX. It also works to one extent or another on various
versions of Windows, including 98, ME, NT, 2000, and XP. It should
work on OS/2, although we no longer have a developer who uses it. It
has been reported to work on MacOS 9, of all things.
POE has been tested with Perl versions as far back as 5.004_03 and as
recent as 5.8.3.
Thanks go out to the CPAN testers, who have dedicated resources to
running new modules on a variety of platforms. The latest POE tests
are visible at <http://testers.cpan.org/search?request=dist&dist=POE>.
We maintain our own test results at <http://eekeek.org/poe-tests/>.
You may participate by running
perl Makefile.PL
make uploadreport
from POE's source directory. A set of tests will be run, and their
results will be uploaded to our test page.
We also try to cover all of POE with our test suite, although we only
succeed in exercising about 70% of its code at any given time. A
coverage report is online at
<http://poe.perl.org/?POE's_test_coverage_report>.
Specific issues:
=over 2
=item Various Unices
No known problems.
=item OS/2
No known problems. POE has no OS/2 tester as of version 0.1206.
=item Windows
POE seems to work very nicely with Perl compiled for CygWin. If you
must use ActiveState Perl, please use build 631 or newer.
POE's Windows port is current maintained by Rocco Caputo, but he has
only limited knowledge of Windows development. Please contact Rocco
if you or someone you know would like to accelerate POE's Windows
support.
Sean Puckett, Douglas Couch, and Andrew Chen have helped to bring
POE's Windows support this far.
TODO: I'm sure there are others. Find them in the changelog and thank
them here.
=item MacOS
No known problems on MacOS X.
Mac Classic (versions 9.x and before) was reported to work at one
time, but it seems like a lost cause unless someone would like to step
forward and make it happen.
=back
=head1 SYSTEM REQUIREMENTS
POE has only one absolute external requirement: Filter::Util::Call
version 1.04 or later. All the other modules are optional, although
people tend to install them anyway.
POE's installer will prompt for required and optional modules. It's
important to read the prompts and only install what you will need.
You may always reinstall it later, adding new prerequisites as the
need arises. B<Note that Tk and Gtk support require very large
dependencies.>
Time::HiRes is recommended. POE will work without it, but alarms and
other features will be much more accurate with it.
POE::Wheel::Run requires a working fork() implementation.
Unfortunately ActivePerl's fork() emulation is not sufficient for it.
CygWin's fork() works just fine however.
POE relies heavily on constants in the POSIX module. Some of the
constants aren't defined on some platforms. POE works around this as
best it can, but problems occasionally crop up. Please let us know if
you run into problems, and we'll work with you to fix them.
Filter::Reference needs a module to serialize data for transporting it
across a network. It will use Storable, FreezeThaw, YAML, or some
other package with freeze() and thaw() methods. It can also use
Compress::Zlib to conserve bandwidth and reduce latency over slow
links, but it's not required.
If you want to write web servers, you'll need to install libwww-perl,
which requires libnet. This is a small world of modules that includes
HTTP::Status, HTTP::Request, HTTP::Date, and HTTP::Response. They are
generally good to have, and recent versions of Perl include them.
Programs that use Wheel::Curses require the Curses module, which in
turn requires some sort of curses library.
=head1 SUPPORT RESOURCES
These are Internet resources where you may find more information about
POE.
=over 2
=item POE's Request Tracker
Bug reports, suggestions, and feedback of all kinds should be e-mailed
to <bug-POE@rt.cpan.org>. It will be entered into our request queue
where it will remain until addressed. If your return address is
valid, you will be notified when the status of your request changes.
=item POE's Mailing List
POE has a mailing list where you can discuss it with the community at
large. You can receive subscription information by sending e-mail:
To: poe-help@perl.org
Subject: (anything will do)
The message body is ignored.
=item POE's Web Site
POE's web site contains the latest development snapshot along with
examples, tutorials, and other fun stuff. It's at
<http://poe.perl.org/>.
=item SourceForge
POE is developed at SourceForge. The project is hosted at
http://sourceforge.net/projects/poe/
=back
=head1 SEE ALSO
POE::Kernel, POE::Session, POE::NFA
POE::Wheel, POE::Wheel::Curses, POE::Wheel::FollowTail,
POE::Wheel::ListenAccept, POE::Wheel::ReadLine, POE::Wheel::ReadWrite,
POE::Wheel::Run, POE::Wheel::SocketFactory
POE::Driver, POE::Driver::SysRW
POE::Filter, POE::Filter::Block, POE::Filter::Grep,
POE::Filter::HTTPD, POE::Filter::Line, POE::Filter::Map,
POE::Filter::RecordBlock, POE::Filter::Reference,
POE::Filter::Stackable, POE::Filter::Stream
POE::Component, POE::Component::Client::TCP,
POE::Component::Server::TCP
POE::Loop, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::Poll,
POE::Loop::Select, POE::Loop::Tk
POE::Pipe, POE::Pipe::OneWay, POE::Pipe::TwoWay
POE::Preprocessor
POE::Queue, POE::Queue::Array
POE::Resource, POE::Resource::Aliases, POE::Resource::Events,
POE::Resource::Extrefs, POE::Resource::FileHandles,
POE::Resource::Performance, POE::Resource::SIDs,
POE::Resource::Sessions, POE::Resource::Signals
=head1 BUGS
The t/*.t tests only cover about 70% of POE.
Outstanding issues, including wish list items, are available in POE's
queue at L<http://rt.cpan.org/>.
=head1 AUTHORS & COPYRIGHT
POE is the combined effort of several people. Please let us know if
someone is missing from this list.
TODO: Scour the CHANGES file for credit where it's due.
=over 2
=item Ann Barcomb
Ann Barcomb is <kudra@domaintje.com>, aka C<kudra>. Ann contributed
large portions of POE::Simple and the code that became the ReadWrite
support in POE::Component::Server::TCP. Her ideas also inspired
Client::TCP component, introduced in version 0.1702.
=item Artur Bergman
Artur Bergman is <sky@cpan.org>. He contributed many hours' work into
POE and quite a lot of ideas. Years later, I decide he's right and
actually implement them.
Artur is the author of Filter::HTTPD and Filter::Reference, as well as
bits and pieces throughout POE. His feedback, testing, design and
inspiration have been instrumental in making POE what it is today.
Artur is investing his time heavily into perl 5's iThreads and PONIE
at the moment. This project has far-reaching implications for POE's
future.
=item Jos Boumans
Jos Boumans is <boumans@frg.eur.nl>, aka C<Co-Kane>. Jos is a major
driving force behind the POE::Simple movement and has helped inspire
the POE::Components for TCP clients and servers.
=item Matt Cashner
Matt Cashner is <eek@eekeek.org>, aka C<sungo>. Matt is one of POE's
core developers. He's spearheaded the movement to simplify POE for
new users, flattening the learning curve and making the system more
accessible to everyone. He uses the system in mission critical
applications, folding feedback and features back into the distribution
for everyone's enjoyment.
=item Andrew Chen
Andrew Chen is <achen-poe@micropixel.com>. Andrew is the resident
POE/Windows guru. He contributes much needed testing for Solaris on
the SPARC and Windows on various Intel platforms.
=item Douglas Couch
Douglas Couch is <dscouch@purdue.edu>. Douglas helped port and
maintain POE for Windows early on.
=item Jeffrey Goff
Jeffrey Goff is <jgoff@blackboard.com>. Jeffrey is the author of
several POE modules, including a tokenizing filter and a component for
managing user information, PoCo::UserBase. He's also co-author of "A
Beginner's Introduction to POE" at www.perl.com.
=item Philip Gwyn
Philip Gwyn is <gwynp@artware.qc.ca>. He extended the Wheels I/O
abstraction to support hot-swappable filters, and he eventually
convinced Rocco that unique session and kernel IDs were a good thing.
Philip also enhanced Filter::Reference to support different
serialization methods. He has also improved POE's quality by finding
and fixing several bugs. He provided POE a much needed code review
around version 0.06.
=item Arnar M. Hrafnkelsson
Arnar is <addi@umich.edu>. Addi tested POE and POE::Component::IRC on
Windows, finding bugs and testing fixes. He appears throughout the
Changes file. He has also written "cpoe", which is a POE-like library
for C.
=item Dave Paris
Dave Paris is <dparis@w3works.com>. Dave tested and benchmarked POE
around version 0.05, discovering some subtle (and not so subtle)
timing problems. The pre-forking server sample was his idea.
Versions 0.06 and later scaled to higher loads because of his work.
He has contributed a lot of testing and feedback, much of which is
tagged in the Changes file as a-mused. The man is scarily good at
testing and troubleshooting.
=item Dieter Pearcey
Dieter Pearcey is <dieter@bullfrog.perlhacker.org>. He goes by
several Japanese nicknames. Dieter's current area of expertise is in
Wheels and Filters. He greatly improved Wheel::FollowTail, and his
Filter contributions include the basic Block filter, as well as
Stackable, RecordBlock, Grep and Map.
=item Robert Seifer
Robert Seifer is <e-mail unknown>. He rotates IRC nicknames
regularly.
Robert contributed entirely too much time, both his own and his
computers, towards the detection and eradication of a memory
corruption bug that POE tickled in earlier Perl versions. In the end,
his work produced a simple compile-time hack that worked around a
problem relating to anonymous subs, scope and @{} processing.
=item Matt Sergeant
Matt contributed POE::Kernel::Poll, a more efficient way to watch
multiple files than select().
=item Richard Soderberg
Richard Soderberg is <poe@crystalflame.net>, aka C<coral>. Richard is
a collaborator on several side projects involving POE. His work
provides valuable testing and feedback from a user's point of view.
=item Dennis Taylor
Dennis Taylor is <dennis@funkplanet.com>. Dennis has been testing,
debugging and patching bits here and there, such as Filter::Line which
he improved by leaps in 0.1102. He's also the author of
POE::Component::IRC, the widely popular POE-based successor to his
wildly popular Net::IRC library.
=item Others?
Please contact the author if you've been forgotten.
=back
=head2 Author
=over 2
=item Rocco Caputo
Rocco Caputo is <rcaputo@cpan.org>. POE is his brainchild.
Except where otherwise noted, POE is Copyright 1998-2004 Rocco Caputo.
All rights reserved. POE is free software; you may redistribute it
and/or modify it under the same terms as Perl itself.
=back
Thank you for reading!
=cut