Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 828 lines (564 sloc) 25.108 kB
96ceb8b @rcaputo Initial revision
authored
1 # $Id$
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
2 # Copyrights and documentation are after __END__.
96ceb8b @rcaputo Initial revision
authored
3
4 package POE;
5
6 use strict;
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
7 use Carp;
8
4cdc9c6 @rcaputo macros, optimizations, comments. a lot of changes.
authored
9 use vars qw($VERSION);
824b754 @rcaputo bad newlines in 2 files; document future depreciations
authored
10 $VERSION = '0.1204';
4cdc9c6 @rcaputo macros, optimizations, comments. a lot of changes.
authored
11
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
12 sub import {
13 my $self = shift;
6f253c6 @rcaputo Optimized POE::Preprocessor a bit, and added POE::NFA
authored
14
15 my @sessions = grep(/^(Session|NFA)$/, @_);
16 my @modules = grep(!/^(Kernel|Session|NFA)$/, @_);
17
500fb10 @rcaputo add new tescase for POE::NFA
authored
18 croak "POE::Session and POE::NFA export conflicting constants"
6f253c6 @rcaputo Optimized POE::Preprocessor a bit, and added POE::NFA
authored
19 if grep(/^(Session|NFA)$/, @sessions) > 1;
20
21 # Add Kernel back it, whether anybody wanted it or not.
22 unshift @modules, 'Kernel';
23
24 # If a session was specified, use that. Otherwise use Session.
25 if (@sessions) {
26 unshift @modules, @sessions;
27 }
28 else {
29 unshift @modules, 'Session';
30 }
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
31
8429c0a @rcaputo forward module exports to the package using POE directly
authored
32 my $package = (caller())[0];
33
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
34 my @failed;
35 foreach my $module (@modules) {
8429c0a @rcaputo forward module exports to the package using POE directly
authored
36 my $code = "package $package; use POE::$module;";
37 eval($code);
38 if ($@) {
babfbeb @rcaputo propagate error messages from modules to user
authored
39 warn $@;
40 push(@failed, $module);
41 }
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
42 }
43
44 @failed and croak "could not import qw(" . join(' ', @failed) . ")";
45 }
96ceb8b @rcaputo Initial revision
authored
46
47 #------------------------------------------------------------------------------
48
49 sub new {
50 my $type = shift;
51 croak "$type is not meant to be used directly";
52 }
53
54 #------------------------------------------------------------------------------
55 1;
4cdc9c6 @rcaputo macros, optimizations, comments. a lot of changes.
authored
56
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
57 __END__
58
59 =head1 NAME
60
f77c574 @rcaputo revised documentation
authored
61 POE - perl application kernel with event driven threads
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
62
63 =head1 SYNOPSIS
64
d8788af @rcaputo Big documentation rewrite
authored
65 #!/usr/bin/perl -w
66 use strict;
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
67
d8788af @rcaputo Big documentation rewrite
authored
68 # Use POE!
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
69 use POE;
f77c574 @rcaputo revised documentation
authored
70
71 # Every session must handle a special event, _start. It's used to
72 # tell the session that it has been successfully instantiated.
73 # $_[KERNEL] is a reference to the program's global POE::Kernel
74 # instance; $_[HEAP] is the session's local storage; $_[SESSION] is
75 # a reference to the session itself.
d8788af @rcaputo Big documentation rewrite
authored
76
f77c574 @rcaputo revised documentation
authored
77 sub handler_start {
d8788af @rcaputo Big documentation rewrite
authored
78 my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
79 print "Session ", $session->ID, " has started.\n";
80 $heap->{count} = 0;
81 $kernel->yield('increment');
82 }
83
f77c574 @rcaputo revised documentation
authored
84 sub handler_increment {
d8788af @rcaputo Big documentation rewrite
authored
85 my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
86 print "Session ", $session->ID, " counted to ", ++$heap->{count}, ".\n";
87 $kernel->yield('increment') if $heap->{count} < 10;
88 }
89
f77c574 @rcaputo revised documentation
authored
90 # The _stop event is special but, handling it is not required. It's
91 # used to tell a session that it's about to be destroyed. _stop
92 # handlers perform shutdown things like resource cleanup or
93 # termination logging.
d8788af @rcaputo Big documentation rewrite
authored
94
f77c574 @rcaputo revised documentation
authored
95 sub handler_stop {
d8788af @rcaputo Big documentation rewrite
authored
96 print "Session ", $_[SESSION]->ID, " has stopped.\n";
97 }
98
f77c574 @rcaputo revised documentation
authored
99 # Start ten sessions. POE::Session constructors map event names to
100 # the code that handles them.
d8788af @rcaputo Big documentation rewrite
authored
101
102 for (0..9) {
103 POE::Session->create(
104 inline_states =>
f77c574 @rcaputo revised documentation
authored
105 { _start => \&handler_start,
106 increment => \&handler_increment,
107 _stop => \&handler_stop,
d8788af @rcaputo Big documentation rewrite
authored
108 }
109 );
110 }
111
112 # Start the kernel, which will run as long as there are sessions.
113
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
114 $poe_kernel->run();
115 exit;
116
d8788af @rcaputo Big documentation rewrite
authored
117 =head1 DESCRIPTION
118
f77c574 @rcaputo revised documentation
authored
119 Please see the SEE ALSO section for conceptual summary of all POE's
120 documentation.
121
d8788af @rcaputo Big documentation rewrite
authored
122 POE is an acronym of "Persistent Object Environment". It originally
f77c574 @rcaputo revised documentation
authored
123 was designed as the core of a persistent object server and runtime
124 environment, but it's evolved into a general purpose application (as
125 opposed to system) kernel.
126
127 POE's core contains two types of module. First there's POE::Kernel;
128 this is the main resource manager and event loop. Second are the
129 sessions or state machines which implement the actual threads. The
130 sessions are POE::Session (not quite a proper state machine) and
131 POE::NFA.
132
133 The remainder of this distribution consists of convenience and helper
134 modules, most of which aren't required to begin using POE.
d8788af @rcaputo Big documentation rewrite
authored
135
136 =head1 USING POE
137
f77c574 @rcaputo revised documentation
authored
138 Using POE can be pretty tedious. Consider this example, which pulls
139 in the necessary modules for a line-based TCP server:
d8788af @rcaputo Big documentation rewrite
authored
140
141 use POE::Kernel;
142 use POE::Session;
143 use POE::Wheel::SocketFactory;
144 use POE::Wheel::ReadWrite;
145 use POE::Filter::Line;
146 use POE::Driver::SysRW;
147
f77c574 @rcaputo revised documentation
authored
148 The POE.pm module fixes some of this tedium. When POE.pm is used
149 directly, it automatically includes POE::Kernel and POE::Session. It
150 also includes each of the C<use> statement's parameters, first
151 prepending "POE::" to them. An example is in order:
d8788af @rcaputo Big documentation rewrite
authored
152
f77c574 @rcaputo revised documentation
authored
153 This C<use> statement is equivalent to the previous six.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
154
155 use POE qw( Wheel::SocketFactory Wheel::ReadWrite
d8788af @rcaputo Big documentation rewrite
authored
156 Filter::Line Driver::SysRW
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
157 );
d8788af @rcaputo Big documentation rewrite
authored
158
159 =head1 WRITING POE PROGRAMS
160
f77c574 @rcaputo revised documentation
authored
161 Basic POE programs have four parts.
d8788af @rcaputo Big documentation rewrite
authored
162
163 =over 2
164
f77c574 @rcaputo revised documentation
authored
165 =item Preliminary program setup
d8788af @rcaputo Big documentation rewrite
authored
166
f77c574 @rcaputo revised documentation
authored
167 This is the usual overhead for writing a Perl program: a shebang line,
d8788af @rcaputo Big documentation rewrite
authored
168 perhaps some C<use> statements to import things, and maybe some global
169 variables or configuration constants. It's all pretty standard stuff.
170
171 #!/usr/bin/perl -w
172 use strict;
173 use POE;
174
f77c574 @rcaputo revised documentation
authored
175 =item Define the program's event handlers or states
d8788af @rcaputo Big documentation rewrite
authored
176
f77c574 @rcaputo revised documentation
authored
177 Declare functions which will handle events here. This is deceptive,
178 since the functions can be declared anywhere, including as anonymous
179 subroutines in a session constructor call.
d8788af @rcaputo Big documentation rewrite
authored
180
f77c574 @rcaputo revised documentation
authored
181 sub handler_start {
d8788af @rcaputo Big documentation rewrite
authored
182 ...
183 }
184
f77c574 @rcaputo revised documentation
authored
185 sub handler_increment {
d8788af @rcaputo Big documentation rewrite
authored
186 ...
187 }
188
f77c574 @rcaputo revised documentation
authored
189 sub handler_stop {
d8788af @rcaputo Big documentation rewrite
authored
190 ...
191 }
192
f77c574 @rcaputo revised documentation
authored
193 =item Start initial sessions or machines
d8788af @rcaputo Big documentation rewrite
authored
194
f77c574 @rcaputo revised documentation
authored
195 The Kernel only runs as long as there is something for it to do. It's
196 main loop returns after the last session has stopped. The obvious
197 corolary to this rule is that the main loop will return immediately if
198 nothing is set up when it's called.
d8788af @rcaputo Big documentation rewrite
authored
199
200 for (0..9) {
201 POE::Session->create(
202 inline_states =>
f77c574 @rcaputo revised documentation
authored
203 { _start => \&handler_start,
204 increment => \&handler_increment,
205 _stop => \&handler_stop,
d8788af @rcaputo Big documentation rewrite
authored
206 }
207 );
208 }
209
f77c574 @rcaputo revised documentation
authored
210 =item Start the kernel's main loop
d8788af @rcaputo Big documentation rewrite
authored
211
f77c574 @rcaputo revised documentation
authored
212 _start handlers are invoked immediately when sessions are
213 instantiated. Everything else happens because the kernel makes it so,
214 and the kernel can't do that 'til it's started. Most programs exit
215 afterwards since the kernel only returns after everything is done.
d8788af @rcaputo Big documentation rewrite
authored
216
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
217 $poe_kernel->run();
f77c574 @rcaputo revised documentation
authored
218 exit 0;
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
219
d8788af @rcaputo Big documentation rewrite
authored
220 =back
221
222
223 =head1 POE's ARCHITECTURE
224
f77c574 @rcaputo revised documentation
authored
225 POE is built in separate layers. Each layer requires the ones beneath
226 it, but no low-level layer requires a higher one.
d8788af @rcaputo Big documentation rewrite
authored
227
228 =over 2
229
f77c574 @rcaputo revised documentation
authored
230 =item Events layer
d8788af @rcaputo Big documentation rewrite
authored
231
f77c574 @rcaputo revised documentation
authored
232 The events layer consists of an event dispatcher, POE::Kernel, and the
233 sessions or state machines it runs: POE::Session (a generic event
234 driven thread) and POE::NFA (an event driven nondeterministic finite
235 automaton).
d8788af @rcaputo Big documentation rewrite
authored
236
f77c574 @rcaputo revised documentation
authored
237 =item One or more I/O layers
d8788af @rcaputo Big documentation rewrite
authored
238
f77c574 @rcaputo revised documentation
authored
239 I/O layers are built upon the event layer, and that allows them to
240 coexist in the same program. POE only includes one I/O layer: Wheels.
241 "Wheels" is a whimsical name for interlocking cogs that together make
242 things go. They're also reinvented a lot, and this is no exception.
d8788af @rcaputo Big documentation rewrite
authored
243
f77c574 @rcaputo revised documentation
authored
244 POE comes with four wheels.
d8788af @rcaputo Big documentation rewrite
authored
245
246 =over 2
247
f77c574 @rcaputo revised documentation
authored
248 =item POE::Wheel::FollowTail
d8788af @rcaputo Big documentation rewrite
authored
249
250 FollowTail follows the tail of an ever-growing file. It's useful for
f77c574 @rcaputo revised documentation
authored
251 watching logs and things of that nature.
d8788af @rcaputo Big documentation rewrite
authored
252
f77c574 @rcaputo revised documentation
authored
253 =item POE::Wheel::ListenAccept
d8788af @rcaputo Big documentation rewrite
authored
254
255 ListenAccept performs ye olde non-blocking socket listen and accept.
f77c574 @rcaputo revised documentation
authored
256 It's great for programs that can't use SocketFactory and instead must
257 listen and accept connections from sockets created elsewhere.
d8788af @rcaputo Big documentation rewrite
authored
258
f77c574 @rcaputo revised documentation
authored
259 =item POE::Wheel::ReadWrite
d8788af @rcaputo Big documentation rewrite
authored
260
f77c574 @rcaputo revised documentation
authored
261 ReadWrite is the star of POE's default I/O layer. It performs
262 buffered, flow-controlled I/O on non-blocking, unbuffered filehandles.
263 It almost acts like a Unix stream which can't stack protocol layers,
264 but that may change.
d8788af @rcaputo Big documentation rewrite
authored
265
266 ReadWrite uses two other classes to do its dirty work: Driver and
f77c574 @rcaputo revised documentation
authored
267 Filter. Drivers do the actual work of reading and writing
268 filehandles. Filters translate between raw streams and cooked chunks
269 of tasty dada.
d8788af @rcaputo Big documentation rewrite
authored
270
f77c574 @rcaputo revised documentation
authored
271 D comes before F, so Drivers go first.
d8788af @rcaputo Big documentation rewrite
authored
272
273 =over 2
274
f77c574 @rcaputo revised documentation
authored
275 =item POE::Driver::SysRW
d8788af @rcaputo Big documentation rewrite
authored
276
f77c574 @rcaputo revised documentation
authored
277 Nobody has needed another driver yet, so this is the only one
278 currently available. It performs sysread and syswrite in a generic
279 way so that ReadWrite can use it and future drivers interchangeably.
d8788af @rcaputo Big documentation rewrite
authored
280
f77c574 @rcaputo revised documentation
authored
281 Other drivers will use the same interface, should they ever be
282 written.
d8788af @rcaputo Big documentation rewrite
authored
283
284 =back
285
f77c574 @rcaputo revised documentation
authored
286 Filters next. There are a few.
d8788af @rcaputo Big documentation rewrite
authored
287
288 =over 2
289
f77c574 @rcaputo revised documentation
authored
290 =item POE::Filter::Block
d8788af @rcaputo Big documentation rewrite
authored
291
f77c574 @rcaputo revised documentation
authored
292 This filter parses input as fixed-length blocks. On the output side,
293 it merely passes data through unscathed.
c575666 @rcaputo added Filter::Block and Dieter's FollowTail patches; finishing touche…
authored
294
f77c574 @rcaputo revised documentation
authored
295 =item POE::Filter::HTTPD
c575666 @rcaputo added Filter::Block and Dieter's FollowTail patches; finishing touche…
authored
296
f77c574 @rcaputo revised documentation
authored
297 The HTTPD filter parses input as HTTP requests and translates them
298 into HTTP::Request objects. On the output side, it takes
299 HTTP::Response objects and turns them into something suitable to be
300 sent to a web client/user-agent.
c575666 @rcaputo added Filter::Block and Dieter's FollowTail patches; finishing touche…
authored
301
f77c574 @rcaputo revised documentation
authored
302 =item POE::Filter::Line
d8788af @rcaputo Big documentation rewrite
authored
303
f77c574 @rcaputo revised documentation
authored
304 The Line filter parses incoming streams into lines and turns outgoing
305 lines into streams. It used to be very basic, but recent improvements
306 have added interesting features like newline autodetection.
d8788af @rcaputo Big documentation rewrite
authored
307
f77c574 @rcaputo revised documentation
authored
308 =item POE::Filter::Reference
d8788af @rcaputo Big documentation rewrite
authored
309
f77c574 @rcaputo revised documentation
authored
310 The Reference filter is used to sond Perl structures between POE
311 programs or between POE and other Perl programs. On the input side,
312 frozen data (via Storable, FreezeThaw, or some other data mechanism)
313 is thawed into Perl data structures. On output, references given to
314 the filter are frozen. Data may also be compressed on request if
315 Compress::Zlib is installed.
d8788af @rcaputo Big documentation rewrite
authored
316
f77c574 @rcaputo revised documentation
authored
317 =item POE::Filter::Stream
d8788af @rcaputo Big documentation rewrite
authored
318
f77c574 @rcaputo revised documentation
authored
319 The stream filter does nothing. It merely passes data through without
320 any change.
d8788af @rcaputo Big documentation rewrite
authored
321
322 =back
323
f77c574 @rcaputo revised documentation
authored
324 =item POE::Wheel::SocketFactory
d8788af @rcaputo Big documentation rewrite
authored
325
f77c574 @rcaputo revised documentation
authored
326 SocketFactory creates all manner of connectionless and connected
327 network sockets. It also listens on TCP server sockets, only
328 returning accepted client connections as they arrive.
d8788af @rcaputo Big documentation rewrite
authored
329
330 =back
331
332 =back
333
334 =head1 POE COMPONENTS
335
f77c574 @rcaputo revised documentation
authored
336 Components consist of one or more sessions or state machines that
337 encapsulate a very high level procedure. For example,
d8788af @rcaputo Big documentation rewrite
authored
338 POE::Component::IRC (not included) performs nearly all the functions
f77c574 @rcaputo revised documentation
authored
339 of a full-featured IRC client. POE::Component::UserBase (not
340 included) is a user authentication and data persistence servlet.
d8788af @rcaputo Big documentation rewrite
authored
341
f77c574 @rcaputo revised documentation
authored
342 Components tend to be highly reusable core libraries that handle
343 tedious tasks, freeing programmers to focus on more interesting
344 things. This should be true for any library, though.
d8788af @rcaputo Big documentation rewrite
authored
345
346 =over 2
347
f77c574 @rcaputo revised documentation
authored
348 =item POE::Component::Server::TCP
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
349
f77c574 @rcaputo revised documentation
authored
350 This is a thin wrapper around POE::Wheel::SocketFactory. It provides
351 the core of a very simple TCP server and is customized by giving it
352 coderefs to execute when connections arrive or errors occur.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
353
f77c574 @rcaputo revised documentation
authored
354 =head1 Support Modules
d8788af @rcaputo Big documentation rewrite
authored
355
f77c574 @rcaputo revised documentation
authored
356 Finally, there are some files which POE uses but aren't required
357 elsewhere. These include POE::Preprocessor and the base classes:
358 POE::Component, POE::Driver, POE::Filter and POE::Wheel. There also
359 are some development files in the lib directory.
d8788af @rcaputo Big documentation rewrite
authored
360
361 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
362
f77c574 @rcaputo revised documentation
authored
363 =item POE::Preprocessor
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
364
f77c574 @rcaputo revised documentation
authored
365 This is a macro preprocessor. It also implements plain and enumerated
366 constants. POE::Kernel uses it to inline smaller functions and make
367 the source generally more readable. There seem to be two drawbacks:
368 First, code is more difficult to examine in perl's debugger since it
369 doesn't necessarily look like the original source. Second, programs
370 take longer to start up because every source line must first pass
371 through a perl filter. The compile-time penalty is negligible in
372 long-running programs, and the runtime boost from fewer function calls
373 can make up for it over time.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
374
f77c574 @rcaputo revised documentation
authored
375 POE::Component, POE::Driver and POE::Filter exist to document their
376 classes of objects. POE::Wheel contains some base functions for
377 tracking unique wheel IDs.
d8788af @rcaputo Big documentation rewrite
authored
378
f77c574 @rcaputo revised documentation
authored
379 =head1 OBJECT LAYER
d8788af @rcaputo Big documentation rewrite
authored
380
f77c574 @rcaputo revised documentation
authored
381 The object layer has fallen into disrepair again. In fact, it never
382 really got to a good start. It's scheduled to be removed from this
383 distribution in version 0.1301. When it does return, it will be as a
384 separate component.
d8788af @rcaputo Big documentation rewrite
authored
385
f77c574 @rcaputo revised documentation
authored
386 =head1 SAMPLE PROGRAMS
d8788af @rcaputo Big documentation rewrite
authored
387
f77c574 @rcaputo revised documentation
authored
388 The sample programs are scheduled for removal from this distribution
389 in version 0.1301. They will be moved to a separate distribution and
390 documented better.
d8788af @rcaputo Big documentation rewrite
authored
391
f77c574 @rcaputo revised documentation
authored
392 This distribution contains 28 example and/or tutorial programs in the
393 archive's ./samples directory. Be advised, however, that many of them
394 date from the early days of POE's development and may not exhibit the
395 best coding practices.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
396
f77c574 @rcaputo revised documentation
authored
397 The author's always looking for new example ideas.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
398
d8788af @rcaputo Big documentation rewrite
authored
399 =head1 COMPATIBILITY ISSUES
400
401 POE has tested favorably on as many Perl versions as the author can
402 find or harass people into trying. This includes Linux, FreeBSD, OS/2
f77c574 @rcaputo revised documentation
authored
403 and at least one unspecified version of Windows. As far as anyone can
d8788af @rcaputo Big documentation rewrite
authored
404 tell, nobody ever has tried it on any version of MacOS.
405
406 POE has been tested with Perl versions as far back as 5.004_03 and as
407 recent as 5.6.0. The CPAN testers are a wonderful bunch of people who
408 have dedicated resources to running new modules on a variety of
409 platforms. The latest POE tests are visible at
410 <http://testers.cpan.org/search?request=dist&dist=POE>. Thanks,
411 people!
412
413 Please let the author know of breakage or success that hasn't been
414 covered already. Thanks!
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
415
d8788af @rcaputo Big documentation rewrite
authored
416 Specific issues:
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
417
d8788af @rcaputo Big documentation rewrite
authored
418 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
419
f77c574 @rcaputo revised documentation
authored
420 =item Various Unices
d8788af @rcaputo Big documentation rewrite
authored
421
422 No known problems.
423
f77c574 @rcaputo revised documentation
authored
424 =item OS/2
ad0d40f @rcaputo 0.08_05
authored
425
d8788af @rcaputo Big documentation rewrite
authored
426 No known problems.
ad0d40f @rcaputo 0.08_05
authored
427
f77c574 @rcaputo revised documentation
authored
428 =item Windows
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
429
d8788af @rcaputo Big documentation rewrite
authored
430 Windows support lapsed in version 0.0806 when I took out some code I
f77c574 @rcaputo revised documentation
authored
431 wasn't sure was working. Well, it was working, and removing it broke
432 POE on Windows.
202eb67 @rcaputo Proofed and revised the manpages
authored
433
d8788af @rcaputo Big documentation rewrite
authored
434 Douglas Couch reported that POE worked with the latest stable
435 ActivePerl prior to version 5.6.0-RC1. He said that RC1 supported
436 fork and other Unix compatibilities, but it still seemed like beta
f77c574 @rcaputo revised documentation
authored
437 level code. This seems to have changed with the release of 5.6.0-GA.
d8788af @rcaputo Big documentation rewrite
authored
438
439 Douglas writes:
440
441 I've done some preliminary testing of the 0.0903 version and the
442 re-addition of the Win32 support seems to be a success. I'll do
443 some more intensive testing in the next few days to make sure
444 nothing else is broken that I haven't missed.
445
446 And later:
447
448 After testing out my own program and having no problems with the
449 newest version (with Win32 support), I thought I'd test out some of
450 the samples and relay my results.
451
452 filterchange.perl and preforkedserver.perl both contain fork
453 commands which are still unsupported by ActiveState's port of Perl,
454 so they were both unsuccessful. (this was anticipated for anything
455 containing fork)
456
457 ref-type.perl, refsender.perl, thrash.perl and wheels2.perl all ran
458 up against the same unsupported POSIX macro. According to the error
459 message, my vendor's POSIX doesn't support the macro EINPROGRESS.
460
461 [EINPROGRESS is fixed as of version 0.1003; see the Changes]
462
463 Other than those particular problems all of the other sample scripts
464 ran fine.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
465
f77c574 @rcaputo revised documentation
authored
466 As far as I know, POE works okay on Windows these days.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
467
f77c574 @rcaputo revised documentation
authored
468 =item MacOS
d8788af @rcaputo Big documentation rewrite
authored
469
470 I have heard rumors from MacOS users that POE might work with MacPerl,
471 but so far nobody has stepped forward with an actual status report.
f77c574 @rcaputo revised documentation
authored
472 I'd be happy to hear either way.
d8788af @rcaputo Big documentation rewrite
authored
473
474 =back
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
475
d8788af @rcaputo Big documentation rewrite
authored
476 =head1 SYSTEM REQUIREMENTS
477
f77c574 @rcaputo revised documentation
authored
478 POE's module recommendations have been codified as part of the `make
479 test' procedure. Any missing dependencies will be reported on, and
480 POE will refuse to test itself if critical modules aren't found.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
481
f77c574 @rcaputo revised documentation
authored
482 Some of POE's sample programs use fork(). They won't work wherever
483 fork() isn't available; sorry.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
484
f77c574 @rcaputo revised documentation
authored
485 POE relies heavily on constants in the POSIX module. Some of the
486 constants aren't defined by ActiveState Perl for Windows, but POE
487 defines them itself to work around this.
d8788af @rcaputo Big documentation rewrite
authored
488
f77c574 @rcaputo revised documentation
authored
489 POE::Preprocessor needs Filter::Util::Call version 1.18 or later for
490 source filtering. Everything else relies on POE::Preprocessor.
d8788af @rcaputo Big documentation rewrite
authored
491
f77c574 @rcaputo revised documentation
authored
492 Some of POE's sample programs require a recent IO bundle, but you get
493 that for free with recent versions of Perl.
d8788af @rcaputo Big documentation rewrite
authored
494
f77c574 @rcaputo revised documentation
authored
495 Filter::Reference needs Storable or FreezeThaw or some other data
496 freezer/thawer package. Storable tends to be the fastest, and so it's
497 preferred. Compress::Zlib is needed if you want to compress frozen
498 data.
d8788af @rcaputo Big documentation rewrite
authored
499
f77c574 @rcaputo revised documentation
authored
500 B<Important Filter::Reference note:> If you're using Filter::Reference
501 to pass data to another machine, make sure every machine has the same
502 versions of the same libraries. Subtle differences, even in different
503 versions of modules like Storable, can cause mysterious errors when
504 data is reconstituted at the receiving end. Whe all else fails,
505 upgrade to the latest versions.
d8788af @rcaputo Big documentation rewrite
authored
506
f77c574 @rcaputo revised documentation
authored
507 Filter::HTTPD uses a small world of modules including HTTP::Status;
508 HTTP::Request; HTTP::Date and URI::URL. The httpd.perl sample program
509 uses Filter::HTTPD, which uses all that other stuff.
d8788af @rcaputo Big documentation rewrite
authored
510
f77c574 @rcaputo revised documentation
authored
511 =head1 SUPPORT RESOURCES
d8788af @rcaputo Big documentation rewrite
authored
512
f77c574 @rcaputo revised documentation
authored
513 These are Internet resources where you may find more information about
514 POE.
d8788af @rcaputo Big documentation rewrite
authored
515
f77c574 @rcaputo revised documentation
authored
516 =over 2
517
518 =item The POE Mailing List
519
520 POE has a mailing list at perl.org. You can receive subscription
521 information by sending e-mail:
d8788af @rcaputo Big documentation rewrite
authored
522
f77c574 @rcaputo revised documentation
authored
523 To: poe-help@perl.org
524 Subject: (anything will do)
d8788af @rcaputo Big documentation rewrite
authored
525
f77c574 @rcaputo revised documentation
authored
526 The message body is ignored.
d8788af @rcaputo Big documentation rewrite
authored
527
f77c574 @rcaputo revised documentation
authored
528 All forms of feedback are welcome.
d8788af @rcaputo Big documentation rewrite
authored
529
f77c574 @rcaputo revised documentation
authored
530 =item The POE Web Site
d814423 @rcaputo doc patch and 19_filterchange.t Storable tweak
authored
531
f77c574 @rcaputo revised documentation
authored
532 POE has a web site where the latest development snapshot, along with
533 the Changes file and other stuff may be found: <http://poe.perl.org/>
d8788af @rcaputo Big documentation rewrite
authored
534
f77c574 @rcaputo revised documentation
authored
535 =item SourceForge
d8788af @rcaputo Big documentation rewrite
authored
536
f77c574 @rcaputo revised documentation
authored
537 POE's development has moved to SourceForge as an experiment in project
538 management. You can reach POE's project summary page at
539 <http://sourceforge.net/projects/poe/>.
d8788af @rcaputo Big documentation rewrite
authored
540
541 =back
542
f77c574 @rcaputo revised documentation
authored
543 =head1 SEE ALSO
d8788af @rcaputo Big documentation rewrite
authored
544
f77c574 @rcaputo revised documentation
authored
545 This is a summary of POE's modules and the things documented in each.
d8788af @rcaputo Big documentation rewrite
authored
546
f77c574 @rcaputo revised documentation
authored
547 =head2 Events Layer
d8788af @rcaputo Big documentation rewrite
authored
548
f77c574 @rcaputo revised documentation
authored
549 These are POE's core modules.
d8788af @rcaputo Big documentation rewrite
authored
550
f77c574 @rcaputo revised documentation
authored
551 =over 2
d8788af @rcaputo Big documentation rewrite
authored
552
f77c574 @rcaputo revised documentation
authored
553 =item POE (this document)
d8788af @rcaputo Big documentation rewrite
authored
554
f77c574 @rcaputo revised documentation
authored
555 The POE manpage includes a sample program and walkthrough of its
556 parts, a summary of the modules which comprise this distribution,
557 POE's general system requirements, how to use POE (literally), and
558 where to get help. It also has a table of contents which you're even
559 now reading.
d8788af @rcaputo Big documentation rewrite
authored
560
f77c574 @rcaputo revised documentation
authored
561 =item POE::Kernel
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
562
f77c574 @rcaputo revised documentation
authored
563 The POE::Kernel manpage includes information about debugging traces
564 and assertions; FIFO events; filehandle watchers; Kernel data
565 accessors; posting events from traditional callbacks (postbacks);
566 redefining sessions' states; resource management; session aliases;
567 signal types, handlers, and pitfalls; signal watchers; synchronous
568 vs. asynchronous events; and timed events (alarms and delays).
d8788af @rcaputo Big documentation rewrite
authored
569
f77c574 @rcaputo revised documentation
authored
570 =item POE::NFA
d8788af @rcaputo Big documentation rewrite
authored
571
f77c574 @rcaputo revised documentation
authored
572 The POE::NFA manpage covers this session's additional predefined
573 events, how NFA differs from Session, state changing methods, and the
574 spawn constructor.
63339eb @rcaputo updated documentation
authored
575
f77c574 @rcaputo revised documentation
authored
576 =item POE::Session
577
578 The POE::Session manpage covers different kinds of states (inline
579 coderef, object methods, and package methods); postback mechanics;
580 predefined event names and the parameters included with them; resource
581 management and its effects on sessions; session constructors (new and
582 create); session data accessors; synchronous vs. asynchronous events
583 in more detail; why sessions don't stop by themselves, and how to
584 force them to.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
585
586 =back
587
f77c574 @rcaputo revised documentation
authored
588 =head2 I/O Layer
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
589
f77c574 @rcaputo revised documentation
authored
590 These modules comprise POE's "Wheels" I/O abstraction.
d8788af @rcaputo Big documentation rewrite
authored
591
d69d027 @rcaputo POE::NFA initial revision; fix =over tags and constructor examples
authored
592 =over 2
f77c574 @rcaputo revised documentation
authored
593
594 =item POE::Driver
595
596 The POE::Driver manpage covers drivers in general and their common
597 interface.
598
599 =item POE::Driver::SysRW
600
601 The SysRW driver's manpage describes the sysread/syswrite abstraction
602 and covers parameters which can be used to customize a SysRW driver's
603 operation.
604
605 =item POE::Filter
606
607 The POE::Filter manpage covers filters in general and their common
4ff59be @rcaputo tweak the Preprocessor a little faster... add wheel IDs to ListenAcce…
authored
608 interface. It discusses the pitfalls involved in switching filters
609 on a running wheel.
f77c574 @rcaputo revised documentation
authored
610
611 =item POE::Filter::HTTPD
612
613 The HTTPD filter's manpage covers using POE as a web server.
614
615 =item POE::Filter::Line
616
617 The Line filter's manpage discusses how to read and write data by
618 lines; how to change the newline literal or regular expression; and
619 how to enable newline autodetection when working with strange peers.
620
621 =item POE::Filter::Reference
622
623 The Reference filter's manpage talks about marshalling data and
624 passing it between POE programs; and customizing the way data is
625 frozen, thawed and optionally compressed.
626
627 =item POE::Filter::Stream
628
629 The Stream filter's manpage is pretty empty since it doesn't do much
630 of anything.
631
632 =item POE::Wheel
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
633
f77c574 @rcaputo revised documentation
authored
634 The Wheel's manpage talks about wheels in general and their common
635 interface.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
636
f77c574 @rcaputo revised documentation
authored
637 =item POE::Wheel::FollowTail
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
638
f77c574 @rcaputo revised documentation
authored
639 The FollowTail wheel's manpage discusses how to watch the end of an
640 ever-growing file (not to be confused with that orb tune) and how to
641 change aspects of the wheel's behavior with constructor parameters.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
642
f77c574 @rcaputo revised documentation
authored
643 =item POE::Wheel::ListenAccept
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
644
f77c574 @rcaputo revised documentation
authored
645 The ListenAccept wheel's manpage discusses how to listen and accept
646 connections using sockets created from sources other than
647 SocketFactory.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
648
f77c574 @rcaputo revised documentation
authored
649 =item POE::Wheel::ReadWrite
d8788af @rcaputo Big documentation rewrite
authored
650
f77c574 @rcaputo revised documentation
authored
651 The ReadWrite wheel's manpage covers non-blocking I/O with optional
652 flow control.
d8788af @rcaputo Big documentation rewrite
authored
653
f77c574 @rcaputo revised documentation
authored
654 =item POE::Wheel::SocketFactory
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
655
f77c574 @rcaputo revised documentation
authored
656 The SocketFactory wheel's manpage discusses how socket factories
657 create and manage sockets; the events they emit on connection,
658 acceptance, and failure; and the parameters which govern what they do.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
659
f77c574 @rcaputo revised documentation
authored
660 =back
661
662 =head2 Object Layer
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
663
f77c574 @rcaputo revised documentation
authored
664 These modules comprise the object layer. They will be removed after
665 0.13 and made into a separate component some time after that. I'm not
666 going to bother explaining them since they're doomed.
d8788af @rcaputo Big documentation rewrite
authored
667
668 POE::Curator; POE::Object; POE::Repository; POE::Attribute::Array;
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
669 POE::Runtime
670
f77c574 @rcaputo revised documentation
authored
671 =head2 Standard Components
d8788af @rcaputo Big documentation rewrite
authored
672
f77c574 @rcaputo revised documentation
authored
673 These components are included with POE because they're nearly
674 universally useful.
675
676 =over 2
d8788af @rcaputo Big documentation rewrite
authored
677
f77c574 @rcaputo revised documentation
authored
678 =item POE::Component
d8788af @rcaputo Big documentation rewrite
authored
679
f77c574 @rcaputo revised documentation
authored
680 The POE::Component manpage discusses what components are and why they
681 exist.
d8788af @rcaputo Big documentation rewrite
authored
682
f77c574 @rcaputo revised documentation
authored
683 =item POE::Component::Server::TCP
d8788af @rcaputo Big documentation rewrite
authored
684
f77c574 @rcaputo revised documentation
authored
685 The TCP server component explains how to create TCP servers with a
686 minimum of fuss.
d8788af @rcaputo Big documentation rewrite
authored
687
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
688 =back
689
f77c574 @rcaputo revised documentation
authored
690 =head2 Supporting Cast
691
692 These modules help in the background.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
693
f77c574 @rcaputo revised documentation
authored
694 =over 2
695
6054510 @rcaputo document the pipes and wheel::run
authored
696 =item POE::Pipe::OneWay
697
698 This creates unbuffered one-way pipes. It tries various methods in
699 the hope that one of them will work on any given platform.
700
701 =item POE::Pipe::TwoWay
702
703 This creates unbuffered two-way pipes. It tries various methods in
704 the hope that one of them will work on any given platform. It's
705 preferred over two OneWay pipes because sometimes two-way transports
706 are available and it can save you a couple filehandles.
707
f77c574 @rcaputo revised documentation
authored
708 =item POE::Preprocessor
709
710 POE's preprocessor covers inline constant replacement, enumerated
711 constants, and macro substitutions in perl programs.
712
713 =back
714
715 =head1 BUGS
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
716
f77c574 @rcaputo revised documentation
authored
717 The t/*.t tests only cover about 70% of POE. The latest numbers are
718 in the README file.
ad0d40f @rcaputo 0.08_05
authored
719
d8788af @rcaputo Big documentation rewrite
authored
720 =head1 AUTHORS & COPYRIGHT
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
721
d8788af @rcaputo Big documentation rewrite
authored
722 POE is the combined effort of more people than I can remember
723 sometimes. If I've forgotten someone, please let me know.
724
725 =over 2
726
f77c574 @rcaputo revised documentation
authored
727 =item Arnar M. Hrafnkelsson
d8788af @rcaputo Big documentation rewrite
authored
728
f77c574 @rcaputo revised documentation
authored
729 Arnar is <addi@umich.edu>. Addi tested POE and POE::Component::IRC on
730 Windows, finding bugs and testing fixes. He appears throughout the
731 Changes file.
d8788af @rcaputo Big documentation rewrite
authored
732
f77c574 @rcaputo revised documentation
authored
733 =item Artur Bergman
d8788af @rcaputo Big documentation rewrite
authored
734
f77c574 @rcaputo revised documentation
authored
735 Artur Bergman is <artur@vogon-solutions.com>. He contributed many
736 hours' work into POE and quite a lot of ideas. Years later, I decide
737 he's right and actually implement them.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
738
f77c574 @rcaputo revised documentation
authored
739 Artur is the author of Filter::HTTPD and Filter::Reference, as well as
740 bits and pieces throughout POE. His intangible contributions include
741 feedback, testing, conceptual planning and inspiration. POE would
742 never have come this far without his support.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
743
f77c574 @rcaputo revised documentation
authored
744 =item Douglas Couch
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
745
f77c574 @rcaputo revised documentation
authored
746 Douglas Couch is <dscouch@purdue.edu>. He was the brave soul who
747 stepped forward to offer valuable testing on the Windows platforms.
748 His reports helped get POE working on Win32 and are summarized earlier
749 in this document.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
750
f77c574 @rcaputo revised documentation
authored
751 =item Philip Gwyn
d8788af @rcaputo Big documentation rewrite
authored
752
f77c574 @rcaputo revised documentation
authored
753 Philip Gwyn is <gwynp@artware.qc.ca>. He extended the Wheels I/O
754 abstraction to support hot-swappable filters, and he eventually
755 convinced me of the utility of unique session and kernel IDs. They
756 rock, by the way, and I'm sorry I didn't apply his patches sooner.
d8788af @rcaputo Big documentation rewrite
authored
757
f77c574 @rcaputo revised documentation
authored
758 Philip also enhanced Filter::Reference to support different
759 serialization methods. His intangible contributions include the
760 discovery and/or destruction of several bugs (see the Changes file)
761 and a thorough code review around version 0.06.
d8788af @rcaputo Big documentation rewrite
authored
762
f77c574 @rcaputo revised documentation
authored
763 =item Dave Paris
d8788af @rcaputo Big documentation rewrite
authored
764
f77c574 @rcaputo revised documentation
authored
765 Dave Paris is <dparis@w3works.com>. Dave tested and benchmarked POE
766 around version 0.05, discovering some subtle (and not so subtle)
767 timing problems. The pre-forking server sample was his idea.
768 Versions 0.06 and later should scale to higher loads because of his
769 work. His intangible contributions include lots of testing and
770 feedback, much of which is tagged in the Changes file as a-mused.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
771
761b0d6 @rcaputo speed up kernel; fix bad filehandle in test 4
authored
772 And I do mean *lots* of testing. I go and announce a new development
773 version, and he's, like, "All tests passed!" just a few minutes later.
774 If that wasn't enough, he investigates any bugs that turn up, and
775 often fixes them. The man's scarily good.
776
f77c574 @rcaputo revised documentation
authored
777 =item Dieter Pearcey
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
778
c575666 @rcaputo added Filter::Block and Dieter's FollowTail patches; finishing touche…
authored
779 Dieter Pearcey is <dieter@bullfrog.perlhacker.org>. He goes by
f77c574 @rcaputo revised documentation
authored
780 several Japanese nicknames. Dieter patched Wheel::FollowTail to be
781 more useful and has contributed the basic Filter::Block and its
782 documentation.
c575666 @rcaputo added Filter::Block and Dieter's FollowTail patches; finishing touche…
authored
783
f77c574 @rcaputo revised documentation
authored
784 =item Robert Seifer
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
785
d8788af @rcaputo Big documentation rewrite
authored
786 Robert Seifer is <e-mail unknown>. He rotates IRC nicknames
787 regularly.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
788
d8788af @rcaputo Big documentation rewrite
authored
789 Robert contributed entirely too much time, both his own and his
790 computers, towards the detection and eradication of a memory
791 corruption bug that POE tickled in earlier Perl versions. In the end,
792 his work produced a simple compile-time hack that worked around a
793 problem relating to anonymous subs, scope and @{} processing.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
794
f77c574 @rcaputo revised documentation
authored
795 In short, he squashed a coredump with a reliable work-around.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
796
f77c574 @rcaputo revised documentation
authored
797 =item Dennis Taylor
197063a @rcaputo gutted and rewrote Filter::Line's innards for extra options
authored
798
799 Dennis Taylor is <dennis@funkplanet.com>. Dennis has been testing,
800 debugging and patching bits here and there, such as Filter::Line which
801 he improved by leaps in 0.1102. He's also the author of
802 POE::Component::IRC, which isn't included here but may be found at
f77c574 @rcaputo revised documentation
authored
803 either <http://www.infobot.org/dev/POE/>.
197063a @rcaputo gutted and rewrote Filter::Line's innards for extra options
authored
804
f77c574 @rcaputo revised documentation
authored
805 =item Others?
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
806
f77c574 @rcaputo revised documentation
authored
807 Please contact the author if you've been forgotten.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
808
809 =back
810
811 =head2 Author
812
d8788af @rcaputo Big documentation rewrite
authored
813 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
814
f77c574 @rcaputo revised documentation
authored
815 =item Rocco Caputo
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
816
d8788af @rcaputo Big documentation rewrite
authored
817 Rocco Caputo is <troc+poe@netrus.net>. POE is his brainchild.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
818
d8788af @rcaputo Big documentation rewrite
authored
819 Except where otherwise noted, POE is Copyright 1998-2000 Rocco Caputo.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
820 All rights reserved. POE is free software; you may redistribute it
821 and/or modify it under the same terms as Perl itself.
822
d8788af @rcaputo Big documentation rewrite
authored
823 =back
824
825 Thank you for reading!
826
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
827 =cut
Something went wrong with that request. Please try again.