Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 632 lines (429 sloc) 18.222 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);
10 $VERSION = 0.10_01;
11
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
12 sub import {
13 my $self = shift;
14 my @modules = grep(!/^(Kernel|Session)$/, @_);
15 unshift @modules, qw(Kernel Session);
16
8429c0a @rcaputo forward module exports to the package using POE directly
authored
17 my $package = (caller())[0];
18
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
19 my @failed;
20 foreach my $module (@modules) {
8429c0a @rcaputo forward module exports to the package using POE directly
authored
21 my $code = "package $package; use POE::$module;";
22 eval($code);
23 if ($@) {
babfbeb @rcaputo propagate error messages from modules to user
authored
24 warn $@;
25 push(@failed, $module);
26 }
372c3a1 @rcaputo Tweaking to get Makefile.PL working correctly.
authored
27 }
28
29 @failed and croak "could not import qw(" . join(' ', @failed) . ")";
30 }
96ceb8b @rcaputo Initial revision
authored
31
32 #------------------------------------------------------------------------------
33
34 sub new {
35 my $type = shift;
36 croak "$type is not meant to be used directly";
37 }
38
39 #------------------------------------------------------------------------------
40 1;
4cdc9c6 @rcaputo macros, optimizations, comments. a lot of changes.
authored
41
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
42 __END__
43
44 =head1 NAME
45
46 POE - A Perl Object Environment
47
48 =head1 SYNOPSIS
49
50 # Basic usage:
51
52 use POE;
53 # create initial sessions here
54 $poe_kernel->run();
55 exit;
56
57 # Typical usage:
58
59 use POE qw( Wheel::SocketFactory Wheel::ReadWrite
60 Driver::SysRW Filter::Line
61 );
62 # create initial sessions here
63 $poe_kernel->run();
64 exit;
65
66 =head1 DESCRIPTION
67
68 The POE distribution contains a handful of different modules, each
69 doing something different.
70
71 When a program uses the POE module, the mandatory POE::Kernel and
72 POE::Session classes are included. Other modules may be included in
73 the parameter to ``use POE''. POE.pm will prepend ``POE::'' to the
74 module names for you.
75
76 =head1 CONCEPTUAL OVERVIEW
77
78 POE's features are separated into three major sections. Sections are
79 called "layers" in the documentation because each builds atop others.
80
81 +-----------+ +--------------+
82 | I/O Layer | | Object Layer |
83 +-----------+ +--------------+
84 /|\ /|\ Commands (to events layer)
85 | |
86 | |
87 \|/ \|/ Events (from events layer)
88 +----------------------------+
89 | Events Layer |
90 +----------------------------+
91
92 Events are also used to pass messages between Sessions.
93
94 This is a description of each layer, starting with the lowest and
95 working upwards:
96
97 =head2 Events Layer
98
99 POE's events layer consists of two classes. These classes are always
100 included when a program uses POE. They may also be used separately
101 wherever their exported constants are needed.
102
103 POE::Kernel contains the state transition event queue and functions to
104 manage resources (including events). Later on, these functions will
105 be referred to as "resource commands". The Kernel will generate
106 events to indicate when watched resources (via a resource command)
107 become active.
108
109 POE::Session instances are state machines. They consist of bundles of
110 related states. States may be code references, object methods or
111 package subroutines. States are invoked whenever a queued transition
112 event is dispatched. State transitions may be enqueued by states
113 themselves or by active resources.
114
115 =head2 I/O Layer
116
117 The I/O layer contains one or more libraries that abstract file I/O.
118 Currently there is only one abstraction library, fondly known as
119 "Wheels". The "Wheels" abstraction consists of groups of classes.
120
121 One type of object does only low-level file I/O. These are the Driver
122 objects.
123
124 A second type of object translates between raw octet streams and
125 protocol packets. These are the Filter objects.
126
127 The final type of object provides a functional interface to file I/O,
128 as well as the select logic to glue Drivers and Filters together.
129 These are the Wheel objects.
130
131 Here is a rough picture of the Wheels I/O abstraction:
132
133 +----------------------------------------------------------+
134 | Session |
135 | |
136 | +------------+ +-------+ +--------+ +--------+ |
137 | |States | | | | | | | |
138 | | | | | | | | | |
139 | |Command | | | | Filter | | | |
140 | |events --|->| |<--->| |--->| | |
141 | | | | Wheel | | | | Driver | |
142 | |Functions --|->| | +--------+ | |<--|--> File
143 | | | | | | | |
144 | |Response | | |-> Select Events ->| | |
145 | |events <-|--| | | | |
146 | +------------+ +-------+ +--------+ |
147 | | /|\ | /|\ |
148 | | | | | |
149 +---|----|----------|---|----------------------------------+
150 | | | |
151 | | | | Commands (Session -> Kernel)
152 | | | | & Events (Kernel -> Session)
153 \|/ | \|/ |
154 +----------------------------------------------------------+
155 | |
156 | Kernel |
157 | |
158 +----------------------------------------------------------+
159
160 =head2 Object Layer
161
162 The Object layer consists of one or more libraries that implement
163 code objects. Currently there are two ways code objects can be
164 created.
165
166 First, code may exist as plain Perl subroutines, objects and
167 packages. This is the oldest object layer, and it is often the best
168 for most programming tasks.
169
170 The second object layer is still in its infancy. Right now it
171 consists of four classes:
172
173 Curator. This is the object manager. It embodies inheritance,
174 attribute fetching and storage, method invocation and security.
175
176 Repository. This is the object database. It provides a consistent
177 interface between the Curator and whatever database it hides.
178
179 Object. This is a Perl representation of a Repository object. It
202eb67 @rcaputo Proofed and revised the manpages
authored
180 hides the Curator and Repository behind an interface that resembles a
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
181 plain Perl object.
182
183 Runtime. This is a namespace where Object methods are run. It
184 contains the public functions from Curator, Repository and Object, and
185 it may one day run within a Safe compartment.
186
187 The obligatory ASCII art:
188
189 +--------------------------------------------------+
190 | Runtime |
191 | +----------------+ |
192 | | Object Methods |-------> Public Functions |
193 | +----------------+ |
194 | /|\ | |
195 +----|---------------------------|-----------------+
196 | |
197 | Events | Commands
198 | \|/
199 +--------------------------------------------------+
200 | |
201 | +------------+ Curator |
202 | | | |
203 | | Sessions | +-------------------------------+
204 | | | |
205 | +------------+ | +------------+ +--======--+
206 | /|\ | |<->| Repository |<->| Database |
207 +-----|------|-----+ +------------+ +--======--+
208 | |
209 | | Events & Commands
210 | \|/
211 +--------------------------------------------------+
212 | |
213 | Kernel |
214 | |
215 +--------------------------------------------------+
216
217 =head1 EXAMPLES
218
ad0d40f @rcaputo 0.08_05
authored
219 As of this writing there are 24 sample programs. Each illustrates and
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
220 tests some aspect of POE use. They are included in the POE
221 distribution archive, but they are not installed. If POE was
222 installed via the CPAN shell, then you should be able to find them in
223 your .cpan/build/POE-(version) directory.
224
225 =head2 Events Layer Examples
226
202eb67 @rcaputo Proofed and revised the manpages
authored
227 These sample programs demonstrate and exercise POE's events layer and
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
228 resource management functions.
229
230 =over 4
231
232 =item *
233
234 create.perl
235
236 This program is essentially the same as sessions.perl, but it uses the
237 newer &POE::Session::create constructor rather than the original
238 &POE::Session::new constructor.
239
240 =item *
241
242 forkbomb.perl
243
244 This program is an extensive test of Session construction and
245 destruction in the kernel. Despite the name, it does not use fork(2).
246 By default, this program will stop after about 200 sessions, so it
247 shouldn't run away with machines it's run on.
248
249 Stopping forkbomb.perl with SIGINT is a good way to test signal
250 propagation.
251
252 =item *
253
254 names.perl
255
256 This program demonstrates the use of session aliases as a method of
257 "daemonizing" sessions and communicating between them by name. It
258 also shows how to do non-blocking inter-session communication with
259 callback states.
260
261 =item *
262
992740b @rcaputo Fix update breakage in the sample programs
authored
263 objmaps.perl
264
265 This is a version of objsessions.perl that maps states to differently
266 named object methods.
267
268 =item *
269
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
270 objsessions.perl
271
272 This program is essentially the same as sessions.perl, but it uses
273 object methods as states instead of inline code references.
274
275 =item *
276
277 packagesessions.perl
278
279 This program is essentially the same as sessions.perl, but it uses
280 package functions as states instead of inline code references.
281
282 =item *
283
0dbb97c @rcaputo Prepare for 0.0905
authored
284 poing.perl
f341533 @rcaputo Added pong.perl
authored
285
0dbb97c @rcaputo Prepare for 0.0905
authored
286 This is a quick and dirty multiple-host icmp ping program. Actually,
287 it's getting better as creatures feep; it may be useful enough to be a
288 separate program. It requires a vt100 or ANSI terminal. It needs to
289 be run by root, since it expects to open a raw socket for ICMP
290 pinging.
f341533 @rcaputo Added pong.perl
authored
291
292 I thank Russell Mosemann <mose@ccsn.edu> for the Net::Ping module,
293 which I "borrowed" heavily from. Net::Ping is the route of choice if
294 you don't need parallel ping capability.
295
296 =item *
297
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
298 selects.perl
299
300 This program exercises the POE::Kernel interface to select(2). It
301 creates a simple chargen server, and a simple client to visit it. The
302 client will disconnect after receiving a few lines from the server.
202eb67 @rcaputo Proofed and revised the manpages
authored
303 The server will remain active, and it will accept telnet connections.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
304
305 =item *
306
307 sessions.perl
308
309 This program is a basic test of Session construction, destruction and
310 maintenance in the Kernel. It is much more friendly than
311 forkbomb.perl. People who are new to POE may want to look at this
312 test first.
313
314 =item *
315
316 signals.perl
317
318 This program is a basic test of the POE::Kernel interface to system
319 and Session signals. It creates two sessions that wait for signals
320 and periodically send signals to themselves.
321
322 =back
323
324 =head2 I/O Layer Examples
325
202eb67 @rcaputo Proofed and revised the manpages
authored
326 These sample programs demonstrate and exercise POE's default I/O
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
327 layer.
328
329 =over 4
330
331 =item *
332
333 fakelogin.perl
334
335 This program tests the ability for POE::Wheel instances to change the
a6a0cd0 @rcaputo Tweaked documentation for fakelogin.perl
authored
336 events they emit. The port it listens on can be specified on the
337 command line. Its default listen port is 23.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
338
339 =item *
340
341 filterchange.perl
342
343 This program tests the ability for POE::Wheel instances to change the
344 filters they use to process information.
345
346 =item *
347
348 followtail.perl
349
350 This program tests POE::Wheel::FollowTail, a read-only wheel that
351 follows the end of an ever-growing file.
352
353 It creates 21 sessions: 10 log writers, 10 log followers, and one loop
354 to make sure none of the other 20 are blocking. SIGINT should stop
355 the program and clean up its /tmp files.
356
357 =item *
358
359 httpd.perl
360
361 This program tests POE::Filter::HTTPD by implementing a very basic web
362 server. It will try to bind to port 80 of every available interface,
363 and it will not run if something has already bound to port 80. It
364 will accept a new port number on the command line:
365
366 ./httpd.perl 8080
367
368 =item *
369
370 ref-type.perl
371
372 This program tests the ability for POE::Filter::Reference to use
373 specified serialization methods. It is part of Philip Gwyn's work on
374 XML based RPC.
375
376 =item *
377
378 refsender.perl and refserver.perl
379
380 These two programs test POE::Filter::Reference's ability to pass
381 blessed and unblessed references between processes. The standard
382 Storable caveats (such as the inability to freeze and thaw CODE
383 references) apply.
384
385 To run this test, first start refserver, then run refsender. Check
386 refserver's STDOUT to see if it received some data.
387
388 =item *
389
390 socketfactory.perl
391
392 This program tests POE::Wheel::SocetFactory, a high level wheel that
393 creates listening and connecting sockets. It creates a server and
394 client for each socket type it currently supports. The clients visit
395 the servers and process some sample transactions.
396
397 =item *
398
399 thrash.perl
400
401 This program tests the Wheel abstraction's ability to handle heavy
402 loads. It creates a simple TCP daytime server and a pool of 5 clients
403 within the same process. Each client connects to the server, accepts
404 the current time, and destructs. The client pool creates replacements
405 for destroyed clients, and so it goes.
406
407 This program has been known to exhaust some systems' available
202eb67 @rcaputo Proofed and revised the manpages
authored
408 sockets. On systems that are susceptible to socket exhaustion,
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
409 netstat will report a lot of sockets in various WAIT states, and
410 thrash.perl will show an abnormally low connections/second rate.
411
412 =item *
413
ad0d40f @rcaputo 0.08_05
authored
414 udp.perl
415
416 Udp shows how to use UDP sockets with Kernel::select calls.
417
418 =item *
419
0dbb97c @rcaputo Prepare for 0.0905
authored
420 watermarks.perl
421
422 This program is a cross between wheels.perl (wheel-based server) and
423 selects.perl (chargen service). It creates a chargen service (on port
424 32019) that uses watermark events to pause output when the unflushed
425 write buffer reaches about 512 bytes. It resumes spewing chargen
426 output when the client finally reads what's waiting for it.
427
428 There currently is no program to act as a slow client for it. Telnet
429 or other raw TCP clients may work, especially if the client is running
430 at maximum niceness.
431
432 =item *
433
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
434 wheels.perl
435
436 This program is a basic rot13 server. It is a basic test of the whole
437 premise of wheels.
438
ad0d40f @rcaputo 0.08_05
authored
439 =item *
440
441 wheels2.perl
442
443 Wheels2 shows how to use separate input and output filehandles with
444 wheels. It's a simple raw tcp socket client, piping between a client
445 socket and stdio (in cooked mode).
446
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
447 =back
448
449 =head2 Object Layer Examples
450
451 This program illustrates POE's Object Layer, which is still in early
452 development.
453
454 =over 4
455
456 =item *
457
458 olayer.perl
459
460 This program demonstrates some of the features of the early Object
461 Layer implementation. It's also something of a reference standard, to
462 make sure that the Object Layer is consistent and usable.
463
464 =back
465
466 =head2 Proofs of Concepts
467
468 Proofs of concepts mainly show how to do something with POE. In some
469 cases, they prove that the concept is possible, even though it wasn't
470 considered while POE was being designed.
471
472 =over 4
473
474 =item *
475
ad0d40f @rcaputo 0.08_05
authored
476 poing.perl
477
478 Poing is a ping program that can check multiple hosts at the same
479 time. Historical information scrolls across the screen in a "strip
480 chart" fashion. It's great for listening to the seismology of your
481 local network (no, it's not deliberately a Quake reference).
482
483 Poing's event-driven pinger "borrows" heavily from Net::Ping.
484
485 =item *
486
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
487 preforkedserver.perl
488
489 This program demonstrates a way to write pre-forking servers with POE.
202eb67 @rcaputo Proofed and revised the manpages
authored
490 It tends to dump core after a while. Perl still isn't safe with
491 signals, especially in a long-running daemon process.
492
493 One work-around is to comment out the yield('_stop') calls (there are
494 two). They only exist to cycle the child servers. That idea was
495 borrowed from Apache, which only did it to thwart memory leaks. POE
496 shouldn't leak memory, so churning the children shouldn't be needed.
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
497
498 =item *
499
500 proxy.perl
501
502 This program demonstrates a way to write TCP forwarders with POE.
503
504 =item *
505
506 tutorial-chat.perl
507
508 This program is a heavily commented "chat" program. It contains a
509 running narrative of what's going on and is intended to be both
510 functional and educational.
511
512 =back
513
514 =head1 SEE ALSO
515
516 =over 4
517
518 =item *
519
520 Events Layer
521
522 POE::Kernel; POE::Session
523
524 =item *
525
526 I/O Layer
527
528 POE::Driver; POE::Driver::SysRW POE::Filter; POE::Filter::HTTPD;
529 POE::Filter::Line; POE::Filter::Reference; POE::Filter::Stream;
530 POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept;
531 POE::Wheel::ReadWrite; POE::Wheel::SocketFactory
532
533 =item *
534
535 Object Layer
536
537 POE::Curator; POE::Object; POE::Repository; POE::Repository::Array;
538 POE::Runtime
539
540 =back
541
542 =head1 BUGS
543
544 The Object Layer is still in early design and implementation, so it's
545 not documented yet.
546
ad0d40f @rcaputo 0.08_05
authored
547 There are no automated regression tests.
548
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
549 =head1 AUTHORS & COPYRIGHTS
550
551 POE is brought to you by the following people:
552
553 =head2 Contributors
554
555 All contributions are Copyright 1998-1999 by their respective
556 contributors. All rights reserved. Contributions to POE are free
557 software, and they may be redistributed and/or modified under the same
558 terms as Perl itself.
559
560 =over 4
561
562 =item *
563
564 Artur Bergman
565
566 Artur Bergman is <vogon-solutions.com!artur>.
567
568 He has contributed Filter::HTTPD and Filter::Reference. His
569 intangible contributions include feedback, testing, conceptual
570 planning and inspiration. POE would not be as far along without his
571 support.
572
573 =item *
574
575 Philip Gwyn
576
577 Philip Gwyn is <artware.qc.ca!gwynp>.
578
579 He has extended the Wheels I/O abstraction to allow filters to be
202eb67 @rcaputo Proofed and revised the manpages
authored
580 changed at runtime. He has enhanced Filter::Reference to support
0d6f19d @rcaputo Revised all the manpages. Split the manpages into separate PODs, and
authored
581 different serialization methods. His intangible contributions include
582 feedback and quality assurance (bug finding). A lot of cleanup
583 between 0.06 and 0.07 is a result of his keen eye. His other eye's
584 not so bad either.
585
586 =item *
587
588 Dave Paris
589
590 Dave Paris is <w3works.com!dparis>.
591
592 His contributions include testing and benchmarking. He discovered
593 some subtle (and not so subtle) timing problems in version 0.05. The
594 pre-forking server test was his idea. Versions 0.06 and later should
595 scale to higher loads because of his work.
596
597 =item *
598
599 Robert Seifer
600
601 Robert Seifer is <?!?>.
602
603 He contributed entirely too much time, both his own and his
604 computer's, to the detection and eradication of a memory corruption
605 bug that POE tickled in Perl. In the end, his work produced a patch
606 that circumvents problems found relating to anonymous subs, scope and
607 @{} processing.
608
609 =item *
610
611 Others?
612
613 Have I forgotten someone? Please let me know.
614
615 =back
616
617 =head2 Author
618
619 =over 4
620
621 =item *
622
623 Rocco Caputo
624
625 Rocco Caputo is <netrus.net!troc>. POE is his brainchild.
626
627 Except where otherwise noted, POE is Copyright 1998-1999 Rocco Caputo.
628 All rights reserved. POE is free software; you may redistribute it
629 and/or modify it under the same terms as Perl itself.
630
631 =cut
Something went wrong with that request. Please try again.