Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 1086 lines (723 sloc) 29.862 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);
c5f1cec @rcaputo move kernel structures to lexicals
authored
10 $VERSION = '0.1201';
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
18 croak "Can't load both POE::Session and POE::NFA at once"
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
6aa1e61 @rcaputo fix SIGCHLD tests
authored
61 POE - event driven state machines
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;
d8788af @rcaputo Big documentation rewrite
authored
70
71 # Every machine is required to have a special state, _start, which
72 # is used to the machine it has been successfully instantiated.
73 # $_[KERNEL] is a reference to the process' global POE::Kernel
74 # instance; $_[HEAP] is the session instance's local storage;
75 # $_[SESSION] is a reference to the session instance itself.
76
77 sub state_start {
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
84 sub state_increment {
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
90 # The _stop state is special but not required. POE uses it to tell
91 # a session instance that it is about to be destroyed. Stop states
92 # contain last-minute resource cleanup, which often isn't necessary
93 # since POE destroys $_[HEAP], and resource destruction cascades
94 # down from there.
95
96 sub state_stop {
97 print "Session ", $_[SESSION]->ID, " has stopped.\n";
98 }
99
100 # Start ten instances of a session. POE::Session constructors map
101 # state names to the code that handles them.
102
103 for (0..9) {
104 POE::Session->create(
105 inline_states =>
106 { _start => \&state_start,
107 increment => \&state_increment,
108 _stop => \&state_stop,
109 }
110 );
111 }
112
113 # Start the kernel, which will run as long as there are sessions.
114
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
115 $poe_kernel->run();
116 exit;
117
d8788af @rcaputo Big documentation rewrite
authored
118 =head1 DESCRIPTION
119
120 POE is an acronym of "Persistent Object Environment". It originally
121 was designed as the core of a persistent object server where clients
122 and autonomous objects could interact in a sort of "agent space". It
123 was, in this regard, very much like a MUD. Evolution, however, seems
124 to have other plans.
125
126 POE's heart is a framework for event driven state machines. This
127 heart has two chambers: an event dispatcher and state machines that
128 are driven by dispatched events. The modules are, respectively,
129 POE::Kernel and POE::Session.
130
131 The remainder of POE consists of modules that help perform high-level
132 functions. For example, POE::Wheel::ReadWrite encapsulates the logic
133 for select-based I/O. Module dependencies always point towards lower
134 level code. POE::Kernel and POE::Session, being at the lowest level,
135 need none of the others. Since they are always required, they will be
136 used whenever POE itself is.
137
138 =head1 USING POE
139
140 Using POE modules can be pretty tedious. Consider this example, which
141 pulls in the necessary modules for a line-based TCP server:
142
143 use POE::Kernel;
144 use POE::Session;
145 use POE::Wheel::SocketFactory;
146 use POE::Wheel::ReadWrite;
147 use POE::Filter::Line;
148 use POE::Driver::SysRW;
149
150 Using POE directly optimizes this for laziness in two ways. First, it
151 brings in POE::Kernel and POE::Session for you. Second, subsequent
152 modules can be passed as parameters to the POE module without the
153 "POE::" prefix.
154
155 The preceding example can then be written as:
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
156
157 use POE qw( Wheel::SocketFactory Wheel::ReadWrite
d8788af @rcaputo Big documentation rewrite
authored
158 Filter::Line Driver::SysRW
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
159 );
d8788af @rcaputo Big documentation rewrite
authored
160
161 =head1 WRITING POE PROGRAMS
162
163 Basic POE programs consist of four parts.
164
165 =over 2
166
167 =item *
168
169 Preliminary program setup
170
171 This is the usual overhead for writing a Perl program: a C<#!> line,
172 perhaps some C<use> statements to import things, and maybe some global
173 variables or configuration constants. It's all pretty standard stuff.
174
175 #!/usr/bin/perl -w
176 use strict;
177 use POE;
178
179 =item *
180
181 Define the program's states
182
183 Here's where the code for each state is defined. In a procedural
184 program, it would be where subroutines are defined. This part is
185 optional in smaller programs, since states may be defined as inline
186 anonymous coderefs when machines are instantiated.
187
188 sub state_start {
189 ...
190 }
191
192 sub state_increment {
193 ...
194 }
195
196 sub state_stop {
197 ...
198 }
199
200 =item *
201
202 Instantiate initial machines
203
204 POE's kernel stops when there are no more sessions to generate or
205 receive transition events. A corolary to this rule: The kernel won't
206 even begin unless a session first has been created. The SYNOPSIS
207 example starts ten state machines to illustrate how POE may simulate
208 threads through cooperative timeslicing. In other words, several
209 things may be run "concurrently" by taking a little care in their
210 design.
211
212 for (0..9) {
213 POE::Session->create(
214 inline_states =>
215 { _start => \&state_start,
216 increment => \&state_increment,
217 _stop => \&state_stop,
218 }
219 );
220 }
221
222 =item *
223
224 Start the kernel
225
226 Almost nothing will happen until the event dispatcher starts. A
227 corolary to this rule: Nothing of much consequence will happen until
228 the kernel is started. As was previously mentioned, the kernel won't
229 return until everything is finished. This usually (but not
230 necessarily) means the entire program is done, so it's common to exit
231 or otherwise let the program end afterwards.
232
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
233 $poe_kernel->run();
234 exit;
235
d8788af @rcaputo Big documentation rewrite
authored
236 =back
237
238
239 =head1 POE's ARCHITECTURE
240
241 POE is built in distinct strata: Each layer requires the ones beneath
242 it but not the ones above it, allowing programs to use as much code as
243 they need but no more. The layers are:
244
245 =over 2
246
247 =item *
248
249 Events layer
250
251 This was already discussed earlier. It consists of an event
6f253c6 @rcaputo Optimized POE::Preprocessor a bit, and added POE::NFA
authored
252 dispatcher, POE::Kernel; POE::Session, which is a generic state
253 machine; and POE::NFA, which is a non-deterministic finite automaton.
d8788af @rcaputo Big documentation rewrite
authored
254
255 =item *
256
257 The "Wheels" I/O abstraction
258
259 POE::Wheel is conceptually similar to a virus. When one is
260 instantiated, it injects its code into the host session. The code
261 consists of some unspecified states that perform a particular job.
262 Unlike viruses, wheels remove their code when destroyed.
263
264 POE comes with four wheels so far:
265
266 =over 2
267
268 =item *
269
270 POE::Wheel::FollowTail
271
272 FollowTail follows the tail of an ever-growing file. It's useful for
273 watching logs or pipes.
274
275 =item *
276
277 POE::Wheel::ListenAccept
278
279 ListenAccept performs ye olde non-blocking socket listen and accept.
280 It's depreciated by SocketFactory, which does all that and more.
281
282 =item *
283
284 POE::Wheel::ReadWrite
285
286 ReadWrite is the star of the POE::Wheel family. It performs buffered
287 I/O on unbuffered, non-blocking filehandles. It almost acts like a
288 Unix stream, only the line disciplines don't yet support push and pop.
289
290 ReadWrite uses two other classes to do its dirty work: Driver and
291 Filter. Drivers do all the work, reading and/or writing from
292 filehandles. Filters do all the other work, translating serialized
293 raw streams to and from logical data chunks.
294
295 Drivers first:
296
297 =over 2
298
299 =item *
300
301 POE::Driver::SysRW
302
303 This is the only driver currently available. It performs sysread and
304 syswrite on behalf of Wheel::ReadWrite. Other drivers, such as
305 SendRecv, are possible, but so far there hasn't been a need for them.
306
307 =back
308
309 Filters next:
310
311 =over 2
312
313 =item *
314
c575666 @rcaputo added Filter::Block and Dieter's FollowTail patches; finishing touche…
authored
315 POE::Filter::Block
316
317 This filter parses input as fixed-length blocks. The output side
318 merely passes data through unscathed.
319
320 =item *
321
d8788af @rcaputo Big documentation rewrite
authored
322 POE::Filter::HTTPD
323
324 This filter parses input as HTTP requests, translating them into
325 HTTP::Request objects. It accepts responses from the program as
326 HTTP::Response objects, serializing them back into streamable HTTP
327 responses.
328
329 =item *
330
331 POE::Filter::Line
332
333 The Line filter parses incoming streams into lines and serializes
334 outgoing lines into streams. It's very basic.
335
336 =item *
337
338 POE::Filter::Reference
339
340 The Reference filter is used for sending Perl structures between POE
341 programs. The sender provides references to structures, and
342 Filter::Reference serializes them with Storable, FreezeThaw, or a
343 serializer of your choice. Data may optionally be compressed if Zlib
344 is installed.
345
346 The receiving side of this filter takes serialized data and thaws it
347 back into perl data structures. It returns a reference to the
348 reconstituted data.
349
350 =item *
351
352 POE::Filter::Stream
353
354 Filter::Stream does nothing of consequence. It passes data through
355 without any change.
356
357 =back
358
359 =item *
360
361 POE::Wheel::SocketFactory
362
363 SocketFactory creates sockets. When creating connectionless sockets,
364 such as UDP, it returns a fully formed socket right away. For
365 connecting sockets which may take some time to establish, it returns
366 when a connection finally is made. Listening socket factories may
367 return several sockets, one for each successfully accepted incoming
368 connection.
369
370 =back
371
372 =back
373
374 =head1 POE COMPONENTS
375
376 A POE component consists of one or more state machines that
377 encapsulates a very high level procedure. For example,
378 POE::Component::IRC (not included) performs nearly all the functions
379 of a fully featured IRC client. This frees programmers from the
380 tedium of working directly with the protocol, instead letting them
381 focus on what the client will actually do.
382
383 POE comes with only one core component, POE::Component::Server::TCP.
384 It is a thin wrapper around POE::Wheel::SocketFactory, providing the
385 wheel with some common default states. This reduces the overhoad
386 needed to create TCP servers to its barest minimum.
387
388 To-do: Publish a POE component SDK, which should amonut to little more
389 than some recommended design guidelines and MakeMaker templates for
390 CPAN publication.
391
392 =head1 Support Modules
393
394 Finally, there are some modules which aren't directly used but come
395 with POE. These include POE::Preprocessor and the virtual base
396 classes: POE::Component, POE::Driver, POE::Filter and POE::Wheel.
397
398 POE::Preprocessor is a macro processor. POE::Kernel and POE::Session
399 use it to inline common code, making the modules faster and easier to
400 maintain. There seem to be two drawbacks, however: Code is more
401 difficult to examine from the Perl debugger, and programs take a
402 little longer to start. The compile-time penalty is negligible in the
403 types of long-running programs POE excels at, however.
404
405 POE::Component exists merely to explain the POE::Component subclasses,
406 as do POE::Driver, POE::Filter and POE::Wheel. Their manpages also
407 discuss options and methods which are common across all their
408 subclasses.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
409
d8788af @rcaputo Big documentation rewrite
authored
410 =head1 ASCII ART
411
412 The ASCII art is gone. If you want pretty pictures, contact the
413 author. He's been looking for excuses to sit down with a graphics
414 program.
415
416 =head1 OBJECT LAYER
417
418 The object layer has fallen into disrepair again, and the author is
419 considering splitting it out as a separate Component. If you've been
420 looking forward to it, let him know so he'll have an excuse to
421 continue with it.
422
423 =head1 SAMPLE PROGRAMS
424
e0749fa @rcaputo Removed $kernel->fork(); added new tests to atone
authored
425 The POE contains 28 sample programs as of this writing. Please be
426 advised that some of them date from the early days of POE's
427 development and may not exhibit the best coding practices.
d8788af @rcaputo Big documentation rewrite
authored
428
e0749fa @rcaputo Removed $kernel->fork(); added new tests to atone
authored
429 The samples reside in the archive's ./samples directory. The author
430 is considering moving them to a separate distribution to cut back on
431 the archive's size, but please contact him anyway if you'd like to see
432 something that isn't there.
d8788af @rcaputo Big documentation rewrite
authored
433
434 =head2 Tutorials
435
436 POE's documentation is merely a reference. It may not explain why
437 things happen or how to do things with POE. The tutorial samples are
438 meant to compensate for this in some small ways.
439
440 =over 2
441
442 =item *
443
444 tutorial-chat.perl
445
446 This is the first and only tutorial to date. It implements a simple
447 chat server (not web chat) with rambling narrative comments.
448
449 =back
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
450
451 =head2 Events Layer Examples
452
d8788af @rcaputo Big documentation rewrite
authored
453 These examples started life as test programs, but the t/*.t type tests
454 are thousands of times terrificer. Now the examples exist mainly as
455 just examples.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
456
d8788af @rcaputo Big documentation rewrite
authored
457 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
458
459 =item *
460
461 create.perl
462
463 This program is essentially the same as sessions.perl, but it uses the
d8788af @rcaputo Big documentation rewrite
authored
464 newer POE::Session->create constructor rather than the original
465 POE::Session->new one.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
466
467 =item *
468
469 forkbomb.perl
470
d8788af @rcaputo Big documentation rewrite
authored
471 The "forkbomb" test doesn't really use fork, but it applies the
472 fork-til-you-puke concept to POE's sessions. Every session starts two
473 more and exits. It has a 200 session limit to keep it from eating
474 resources forever.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
475
476 =item *
477
478 names.perl
479
d8788af @rcaputo Big documentation rewrite
authored
480 The "names" test demonstrates two concepts: how to reference sessions
481 by name, and how to communicate between sessions with an asynchronous
482 ENQ/ACK protocol.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
483
484 =item *
485
992740b @rcaputo Fix update breakage in the sample programs
authored
486 objmaps.perl
487
488 This is a version of objsessions.perl that maps states to differently
489 named object methods.
490
491 =item *
492
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
493 objsessions.perl
494
495 This program is essentially the same as sessions.perl, but it uses
d8788af @rcaputo Big documentation rewrite
authored
496 object methods as states instead of inline coderefs.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
497
498 =item *
499
500 packagesessions.perl
501
502 This program is essentially the same as sessions.perl, but it uses
d8788af @rcaputo Big documentation rewrite
authored
503 package methods as states instead of inline coderefs.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
504
505 =item *
506
d8788af @rcaputo Big documentation rewrite
authored
507 queue.perl
f341533 @rcaputo Added pong.perl
authored
508
d8788af @rcaputo Big documentation rewrite
authored
509 In this example, a single session is created to manage others beneath
510 it. The main session keeps a pool of children to perform asynchronous
511 tasks. Children stop as their tasks are completed, so the job queue
512 controller spawns new ones to continue the work. The pool size is
513 limited to constrain the example's resource use.
f341533 @rcaputo Added pong.perl
authored
514
515 =item *
516
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
517 selects.perl
518
d8788af @rcaputo Big documentation rewrite
authored
519 The "selects" example shows how to use POE's interface to select(2).
520 It creates a simple chargen server and a client to visit it. The
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
521 client will disconnect after receiving a few lines from the server.
d8788af @rcaputo Big documentation rewrite
authored
522 The server will remain active until it receives SIGINT, and it will
523 accept further socket connections.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
524
525 =item *
526
527 sessions.perl
528
d8788af @rcaputo Big documentation rewrite
authored
529 This program is a basic example of Session construction, destruction
530 and maintenance. It's much more system friendly than forkbomb.perl.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
531
532 =item *
533
534 signals.perl
535
d8788af @rcaputo Big documentation rewrite
authored
536 The "signals" example shows how sessions can watch for signals. It
537 creates two sessions that wait for signals and periodically post soft
538 signals to themselves. Soft signals avoid the underlying operating
539 system, posting signal events directly through POE. This also allows
540 simulated and fictitious signals.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
541
542 =back
543
544 =head2 I/O Layer Examples
545
d8788af @rcaputo Big documentation rewrite
authored
546 These examples show how to use the Wheels abstraction.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
547
d8788af @rcaputo Big documentation rewrite
authored
548 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
549
550 =item *
551
552 fakelogin.perl
553
d8788af @rcaputo Big documentation rewrite
authored
554 The "fakelogin" example tests Wheels' ability to change the events
555 they emit. The port it listens on can be specified on the command
556 line, and it listens on port 23 by default.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
557
558 =item *
559
560 filterchange.perl
561
d8788af @rcaputo Big documentation rewrite
authored
562 This example tests POE::Wheel::ReadWrite's ability to change the
563 filter it's using while it runs.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
564
565 =item *
566
567 followtail.perl
568
d8788af @rcaputo Big documentation rewrite
authored
569 This program shows how to use POE::Wheel::FollowTail, a read-only
570 wheel that follows the end of an ever-growing file.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
571
d8788af @rcaputo Big documentation rewrite
authored
572 It creates 21 sessions: 10 that generate fictitious log files, 10 that
573 follow the ends of these logs, and one timer loop to make sure none of
574 the other 20 are blocking. SIGINT will cause the program to clean up
575 its /tmp files and stop.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
576
577 =item *
578
579 httpd.perl
580
d8788af @rcaputo Big documentation rewrite
authored
581 This is a test of the nifty POE::Filter::HTTPD module. The author can
582 say it's nifty because he didn't write it. The sample will try
583 binding to port 80 of INADDR_ANY, but it can be given a new port on
584 the command line.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
585
586 =item *
587
d8788af @rcaputo Big documentation rewrite
authored
588 proxy.perl
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
589
d8788af @rcaputo Big documentation rewrite
authored
590 This is a simple TCP port forwarder.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
591
592 =item *
593
d8788af @rcaputo Big documentation rewrite
authored
594 ref-type.perl
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
595
d8788af @rcaputo Big documentation rewrite
authored
596 The "ref-type" sample shows how POE::Filter::Reference can use
597 specified serialization methods. It's part of Philip Gwyn's work on
598 POE::Component::IKC, an XML based RPC package.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
599
600 =item *
601
d8788af @rcaputo Big documentation rewrite
authored
602 refsender.perl and refserver.perl
603
604 These samples use POE::Filter::Reference to pass copies of blessed and
605 unblessed data between processes. The standard Storable caveats (such
606 as its inability to freeze and thaw coderefs) apply.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
607
d8788af @rcaputo Big documentation rewrite
authored
608 refserver.perl should be run first, then refsender. Check refserver's
609 STDOUT to see what it received.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
610
611 =item *
612
613 thrash.perl
614
d8788af @rcaputo Big documentation rewrite
authored
615 This is a harsh wheel test. It sets up a simple TCP daytime server
616 and a pool of clients within the same process. The clients
617 continually visit the server, creating and destroying several sockets
618 a second. The test will run faster (and thus be harsher on the
619 system) if it is split into two processes.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
620
621 =item *
622
ad0d40f @rcaputo 0.08_05
authored
623 udp.perl
624
d8788af @rcaputo Big documentation rewrite
authored
625 The "udp" sample shows how to create UDP sockets with IO::Socket and
626 use them in POE. It was a proof of concept for the SocketFactory
627 wheel's UDP support.
ad0d40f @rcaputo 0.08_05
authored
628
629 =item *
630
0dbb97c @rcaputo Prepare for 0.0905
authored
631 watermarks.perl
632
d8788af @rcaputo Big documentation rewrite
authored
633 High and low watermarks are a recent addition to the ReadWrite wheel.
634 This program revisits the author's good friend, the chargen server,
635 this time implementing flow control.
0dbb97c @rcaputo Prepare for 0.0905
authored
636
d8788af @rcaputo Big documentation rewrite
authored
637 Seeing it in action requires a slow client. Telnet or other raw TCP
638 clients may work, especially if they are running at maximum niceness.
0dbb97c @rcaputo Prepare for 0.0905
authored
639
640 =item *
641
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
642 wheels.perl
643
d8788af @rcaputo Big documentation rewrite
authored
644 This program is a basic rot13 server. It was used as an early test
645 program for the whole Wheel abstraction's premise.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
646
ad0d40f @rcaputo 0.08_05
authored
647 =item *
648
649 wheels2.perl
650
d8788af @rcaputo Big documentation rewrite
authored
651 The "wheels2" sample shows how to use separate input and output
652 filehandles with a wheel. It's a simple tcp socket client, piping
653 betwene a socket and stdio. Stdio is in cooked mode, with all its
654 caveats.
ad0d40f @rcaputo 0.08_05
authored
655
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
656 =back
657
658 =head2 Object Layer Examples
659
d8788af @rcaputo Big documentation rewrite
authored
660 As was previously said, the object layer has fallen once again into
661 disrepair. However, the olayer.perl sample program illustrates its
662 current state.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
663
d8788af @rcaputo Big documentation rewrite
authored
664 =head2 Proofs of Concepts
665
666 These programs are prototypes for strange and wonderful concepts.
667 They push POE's growth by stretching its capabilities to extrems and
668 seeing where it hurts.
669
670 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
671
672 =item *
673
d8788af @rcaputo Big documentation rewrite
authored
674 preforkedserver.perl
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
675
d8788af @rcaputo Big documentation rewrite
authored
676 This example shows how to write pre-forking servers with POE. It
677 tends to dump core after a while, however, due signal issues in Perl,
678 so it's not recommended as an example of a long running server.
679
680 One work-around is to comment out the yield('_stop') calls (there are
681 two). These were added to cycle child servers. The idea was borrowed
682 from Apache, which only did this to thwart runaway children. POE
683 shouldn't leak memory, so churning the children shouldn't be needed.
684
685 Still, it is a good test for one of POE's weaknesses. This thorn in
686 the author's side will remain enabled.
687
688 =item *
689
690 tk.perl
691
692 The "tk" example is a prototype of POE's Tk support. It sets up a Tk
693 main window populated with some buttons and status displays. The
694 buttons and displays demonstrate FIFO, alarm and file events in the Tk
695 environment.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
696
697 =back
698
d8788af @rcaputo Big documentation rewrite
authored
699 =head1 COMPATIBILITY ISSUES
700
701 POE has tested favorably on as many Perl versions as the author can
702 find or harass people into trying. This includes Linux, FreeBSD, OS/2
703 and at least one unspecified version of Windows. As far as I can
704 tell, nobody ever has tried it on any version of MacOS.
705
706 POE has been tested with Perl versions as far back as 5.004_03 and as
707 recent as 5.6.0. The CPAN testers are a wonderful bunch of people who
708 have dedicated resources to running new modules on a variety of
709 platforms. The latest POE tests are visible at
710 <http://testers.cpan.org/search?request=dist&dist=POE>. Thanks,
711 people!
712
713 Please let the author know of breakage or success that hasn't been
714 covered already. Thanks!
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
715
d8788af @rcaputo Big documentation rewrite
authored
716 Specific issues:
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
717
d8788af @rcaputo Big documentation rewrite
authored
718 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
719
720 =item *
721
d8788af @rcaputo Big documentation rewrite
authored
722 Various Unices
723
724 No known problems.
725
726 =item *
ad0d40f @rcaputo 0.08_05
authored
727
d8788af @rcaputo Big documentation rewrite
authored
728 OS/2
ad0d40f @rcaputo 0.08_05
authored
729
d8788af @rcaputo Big documentation rewrite
authored
730 No known problems.
ad0d40f @rcaputo 0.08_05
authored
731
732 =item *
733
d8788af @rcaputo Big documentation rewrite
authored
734 Windows
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
735
d8788af @rcaputo Big documentation rewrite
authored
736 Windows support lapsed in version 0.0806 when I took out some code I
737 wasn't sure was working. Well, it was, and removing it broke POE on
738 Windows.
202eb67 @rcaputo Proofed and revised the manpages
authored
739
d8788af @rcaputo Big documentation rewrite
authored
740 Douglas Couch reported that POE worked with the latest stable
741 ActivePerl prior to version 5.6.0-RC1. He said that RC1 supported
742 fork and other Unix compatibilities, but it still seemed like beta
743 level code. I hope this changed with the release of 5.6.0-GA.
744
745 Douglas writes:
746
747 I've done some preliminary testing of the 0.0903 version and the
748 re-addition of the Win32 support seems to be a success. I'll do
749 some more intensive testing in the next few days to make sure
750 nothing else is broken that I haven't missed.
751
752 And later:
753
754 After testing out my own program and having no problems with the
755 newest version (with Win32 support), I thought I'd test out some of
756 the samples and relay my results.
757
758 filterchange.perl and preforkedserver.perl both contain fork
759 commands which are still unsupported by ActiveState's port of Perl,
760 so they were both unsuccessful. (this was anticipated for anything
761 containing fork)
762
763 ref-type.perl, refsender.perl, thrash.perl and wheels2.perl all ran
764 up against the same unsupported POSIX macro. According to the error
765 message, my vendor's POSIX doesn't support the macro EINPROGRESS.
766
767 [EINPROGRESS is fixed as of version 0.1003; see the Changes]
768
769 Other than those particular problems all of the other sample scripts
770 ran fine.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
771
772 =item *
773
d8788af @rcaputo Big documentation rewrite
authored
774 MacOS
775
776 I have heard rumors from MacOS users that POE might work with MacPerl,
777 but so far nobody has stepped forward with an actual status report.
778
779 =back
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
780
d8788af @rcaputo Big documentation rewrite
authored
781 =head1 SYSTEM REQUIREMENTS
782
783 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
784
785 =item *
786
d8788af @rcaputo Big documentation rewrite
authored
787 Recommendations
788
789 POE would like to see certain functions, but it doesn't strictly
790 require them. For example, the sample programs use fork() in a few
791 places, but POE doesn't require it to run.
792
793 If Time::HiRes is present, POE will use it to achieve better accuracy
794 in its select timeouts. This makes alarms and delays more accurate,
795 but POE is designed to work without it as well.
796
797 POE includes no XS, and therefore it doesn't require a C compiler. It
798 should work wherever a sufficiently complete version of Perl does.
799
800 =item *
801
802 Hard Requirements
803
804 POE requires Filter::Call::Util starting with version 0.1001. This is
805 part of the source filter package, Filter, version 1.18 or later. The
806 dependency is coded into Makefile.PL, and the CPAN shell can fetch and
807 install this automatically for you.
808
809 POE uses POSIX system calls and constants for portability. There
810 should be no problems using it on systems that have sufficient POSIX
811 support.
812
813 Some of POE's sample programs require a recent IO bundle, but you get
814 that for free with recent versions of Perl.
815
816 =item *
817
818 Optional Requirements
819
820 If you intend to use Filter::Reference, then you will need either the
821 Storable or FreezeThaw module, or some other freeze/thaw package.
822 Storable tends to be the fastest, and it's checked first.
823 Filter::Reference can also use Compress::Zlib upon request, but it's
824 not required.
825
d814423 @rcaputo doc patch and 19_filterchange.t Storable tweak
authored
826 B<If you intend to pass reference across machines, such as with Philip
827 Gwyn's POE::Component::IKC, then be sure that both ends of the
828 connection use the same version of the same libraries. Subtle
829 differences in libraries, or even between different versions of the
830 same library, can cause mysterious errors when data is reconstituted
831 on the receiving end. When all else fails, upgrade to the latest
832 version; this has been known to fix problems between Filter::Reference
833 and Storable, for example.>
834
d8788af @rcaputo Big documentation rewrite
authored
835 Filter::HTTPD requires a small world of modules, including
836 HTTP::Status; HTTP::Request; HTTP::Date and URI::URL. The httpd.perl
837 sample program uses Filter::HTTPD, which uses all that other stuff.
838
839 The preforkedserver.perl sample program uses POE::Kernel::fork(),
840 which in turn requires the fork() built-in function. This may or may
841 not be available on your planet.
842
843 Other sample programs may require other modules, but the required
844 modules aren't required if you don't require those specific modules.
845
846 =back
847
848 =head1 SUPPORT RESOURCES
849
850 These are Internet resources where you may find more information about
851 POE.
852
853 =over 2
854
855 =item *
856
857 The POE Mailing List
858
63339eb @rcaputo updated documentation
authored
859 POE has a mailing list at perl.org. You may subscribe to it by
860 sending e-mail:
d8788af @rcaputo Big documentation rewrite
authored
861
63339eb @rcaputo updated documentation
authored
862 To: poe-help@perl.org
d8788af @rcaputo Big documentation rewrite
authored
863 Subject: (anything will do)
864
865 Anything will do for the message body.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
866
d8788af @rcaputo Big documentation rewrite
authored
867 All forms of feedback are welcome.
868
869 =item *
870
63339eb @rcaputo updated documentation
authored
871 The POE Web Site
872
873 POE has a web site where the latest development snapshot, along with
874 the Changes file and other stuff may be found: <http://poe.perl.org/>
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
875
876 =back
877
878 =head1 SEE ALSO
879
d8788af @rcaputo Big documentation rewrite
authored
880 This is a summary of POE's modules.
881
882 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
883
884 =item *
885
886 Events Layer
887
6f253c6 @rcaputo Optimized POE::Preprocessor a bit, and added POE::NFA
authored
888 POE::Kernel; POE::NFA; POE::Session
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
889
890 =item *
891
892 I/O Layer
893
d8788af @rcaputo Big documentation rewrite
authored
894 POE::Driver; POE::Driver::SysRW
895
896 POE::Filter; POE::Filter::HTTPD; POE::Filter::Line;
897 POE::Filter::Reference; POE::Filter::Stream
898
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
899 POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept;
900 POE::Wheel::ReadWrite; POE::Wheel::SocketFactory
901
902 =item *
903
904 Object Layer
905
d8788af @rcaputo Big documentation rewrite
authored
906 These modules are in limbo at the moment.
907
908 POE::Curator; POE::Object; POE::Repository; POE::Attribute::Array;
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
909 POE::Runtime
910
d8788af @rcaputo Big documentation rewrite
authored
911 =item *
912
913 Components
914
915 POE::Component; POE::Component::Server::TCP
916
917 =item *
918
919 Supporting cast
920
921 POE::Preprocessor
922
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
923 =back
924
925 =head1 BUGS
926
d8788af @rcaputo Big documentation rewrite
authored
927 The Object Layer is still in early design, so it's not documented yet.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
928
d8788af @rcaputo Big documentation rewrite
authored
929 There need to be more automated regression tests in the t/*.t
930 directory. Please suggest tests; the author is short on ideas here.
ad0d40f @rcaputo 0.08_05
authored
931
d8788af @rcaputo Big documentation rewrite
authored
932 The documentation is in the process of another revision. Here is a
933 progress report:
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
934
d8788af @rcaputo Big documentation rewrite
authored
935 POE rewritten 2000.05.15
936 README rewritten 2000.05.16
937 POE::Kernel rewritten 2000.05.19
938 POE::Session rewritten 2000.05.21
9573d8c @rcaputo Initial Event support; new Tk test; more manpage revisions
authored
939 POE::Wheel rewritten 2000.05.22
1db9198 @rcaputo lots of testing changes and additions
authored
940 POE::Preprocessor revised 2000.05.23
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
941
d8788af @rcaputo Big documentation rewrite
authored
942 POE::Component queued
943 POE::Component::Server::TCP queued
944 POE::Driver queued
945 POE::Driver::SysRW queued
946 POE::Filter queued
d3851cd @rcaputo added Filter::Block to the documentation rewrite queue
authored
947 POE::Filter::Block queued
d8788af @rcaputo Big documentation rewrite
authored
948 POE::Filter::HTTPD queued
949 POE::Filter::Line queued
950 POE::Filter::Reference queued
951 POE::Filter::Stream queued
952 POE::Wheel::FollowTail queued
953 POE::Wheel::ListenAccept queued
954 POE::Wheel::ReadWrite queued
955 POE::Wheel::SocketFactory queued
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
956
d8788af @rcaputo Big documentation rewrite
authored
957 =head1 AUTHORS & COPYRIGHT
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
958
d8788af @rcaputo Big documentation rewrite
authored
959 POE is the combined effort of more people than I can remember
960 sometimes. If I've forgotten someone, please let me know.
961
962 =over 2
963
964 =item *
965
966 Addi
967
968 Addi is <e-mail unknown>.
969
970 Addi has tested POE and POE::Component::IRC on the Windows platform,
971 finding bugs and testing fixes. You'll see his name sprinkled
972 throughout the Changes file.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
973
974 =item *
975
976 Artur Bergman
977
d8788af @rcaputo Big documentation rewrite
authored
978 Artur Bergman is <artur@vogon-solutions.com>.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
979
d8788af @rcaputo Big documentation rewrite
authored
980 Artur has contributed many hours and ideas. He's also the author of
981 Filter::HTTPD and Filter::Reference, as well as bits and pieces
982 throughout POE. His intangible contributions include feedback,
983 testing, conceptual planning and inspiration. POE would never have
984 come this far without his support.
985
986 =item *
987
988 Douglas Couch
989
990 Douglas Couch is <dscouch@purdue.edu>
991
992 Douglas was the brave soul who stepped forward to offer valuable
993 testing on the Windows platforms. His reports helped get POE working
994 on Win32 and are summarized earlier in this document.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
995
996 =item *
997
998 Philip Gwyn
999
d8788af @rcaputo Big documentation rewrite
authored
1000 Philip Gwyn is <gwynp@artware.qc.ca>.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1001
d8788af @rcaputo Big documentation rewrite
authored
1002 Philip extended the Wheels I/O abstraction to allow filters to be
1003 changed at runtime and provided patches to add the eminently cool
1004 Kernel and Session IDs. He also enhanced Filter::Reference to support
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1005 different serialization methods. His intangible contributions include
d8788af @rcaputo Big documentation rewrite
authored
1006 the discovery and/or destruction of several bugs (see the Changes
1007 file) and a thorough code review around version 0.06.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1008
1009 =item *
1010
1011 Dave Paris
1012
d8788af @rcaputo Big documentation rewrite
authored
1013 Dave Paris is <dparis@w3works.com>. He often goes by the nickname
1014 "a-mused".
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1015
d8788af @rcaputo Big documentation rewrite
authored
1016 Dave tested and benchmarked POE around version 0.05, discovering some
1017 subtle (and not so subtle) timing problems. The pre-forking server
1018 was his idea. Versions 0.06 and later should scale to higher loads
1019 because of his work. His intangible contributions include lots of
1020 testing and feedback, some of which is visible in the Changes file.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1021
761b0d6 @rcaputo speed up kernel; fix bad filehandle in test 4
authored
1022 And I do mean *lots* of testing. I go and announce a new development
1023 version, and he's, like, "All tests passed!" just a few minutes later.
1024 If that wasn't enough, he investigates any bugs that turn up, and
1025 often fixes them. The man's scarily good.
1026
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1027 =item *
1028
c575666 @rcaputo added Filter::Block and Dieter's FollowTail patches; finishing touche…
authored
1029 Dieter Pearcey is <dieter@bullfrog.perlhacker.org>. He goes by
1030 several Japanese nicknames.
1031
1032 Dieter patched Wheel::FollowTail to be more useful and has contributed
1033 the basic Filter::Block, along with documentation!
1034
1035 =item *
1036
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1037 Robert Seifer
1038
d8788af @rcaputo Big documentation rewrite
authored
1039 Robert Seifer is <e-mail unknown>. He rotates IRC nicknames
1040 regularly.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1041
d8788af @rcaputo Big documentation rewrite
authored
1042 Robert contributed entirely too much time, both his own and his
1043 computers, towards the detection and eradication of a memory
1044 corruption bug that POE tickled in earlier Perl versions. In the end,
1045 his work produced a simple compile-time hack that worked around a
1046 problem relating to anonymous subs, scope and @{} processing.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1047
1048 =item *
1049
197063a @rcaputo gutted and rewrote Filter::Line's innards for extra options
authored
1050 Dennis Taylor
1051
1052 Dennis Taylor is <dennis@funkplanet.com>. Dennis has been testing,
1053 debugging and patching bits here and there, such as Filter::Line which
1054 he improved by leaps in 0.1102. He's also the author of
1055 POE::Component::IRC, which isn't included here but may be found at
1056 either <http://www.infobot.org/dev/POE/> or
1057 <http://www.funkplanet.com/POE/>.
1058
1059 =item *
1060
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1061 Others?
1062
197063a @rcaputo gutted and rewrote Filter::Line's innards for extra options
authored
1063 Anyone who has been forgotten, please contact the author.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1064
1065 =back
1066
1067 =head2 Author
1068
d8788af @rcaputo Big documentation rewrite
authored
1069 =over 2
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1070
1071 =item *
1072
1073 Rocco Caputo
1074
d8788af @rcaputo Big documentation rewrite
authored
1075 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
1076
d8788af @rcaputo Big documentation rewrite
authored
1077 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
1078 All rights reserved. POE is free software; you may redistribute it
1079 and/or modify it under the same terms as Perl itself.
1080
d8788af @rcaputo Big documentation rewrite
authored
1081 =back
1082
1083 Thank you for reading!
1084
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
1085 =cut
Something went wrong with that request. Please try again.