Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Mid-sized documenation update

  • Loading branch information...
commit 2c3758b94d149cf69d9e0fe441881bca9bb185ca 1 parent d530068
Philip Gwyn authored
Showing with 110 additions and 100 deletions.
  1. +110 −100 lib/POE.pm
View
210 lib/POE.pm
@@ -122,8 +122,9 @@ and runtime environment. It has since evolved into something much
more generic and widely useful.
POE provides a unified interface for several other event loops,
-including select(), IO::Poll, Glib, Gtk, Tk, wx, Gtk2, and so on.
-Check CPAN for the full list of POE::Loop modules.
+including select(), L<IO::Poll>, L<Glib>, L<Gtk>, L<Tk>, L<Wx>,
+L<Gtk2>, and so on.
+Check the CPAN for the full list of L<POE::Loop> modules.
POE is designed in layers, each building atop the lower level ones.
Programs are free to use POE at any level of abstraction, and
@@ -131,7 +132,7 @@ different levels can be mixed and matched seamlessly within a single
program.
POE's bundled abstraction layers are the tip of a growing iceberg.
-Sprocket, POE::Stage, and other CPAN distributions build upon this
+L<Sprocket>, L<POE::Stage>, and other CPAN distributions build upon this
work. You're encouraged to look around.
No matter how high you go, though, it all boils down to calls to
@@ -140,17 +141,17 @@ stratospheric systems.
=head2 Layer 1: Kernel and Sessions
-The lowest public layer is comprised of POE::Kernel, POE::Session, and
+The lowest public layer is comprised of L<POE::Kernel>, L<POE::Session>, and
other session types.
-POE::Kernel does most of the heavy lifting. It provides a portable
+L<POE::Kernel> does most of the heavy lifting. It provides a portable
interface for filehandle activity detection, multiple alarms and other
timers, signal handling, and other less-common features.
-POE::Session and derived classes encapsulate the notion of an event
+L<POE::Session> and derived classes encapsulate the notion of an event
driven task. They also customize event dispatch to a particular
-calling convention. POE::NFA, for example, is more of a proper state
-machine. CPAN has several other kinds of sessions.
+calling convention. L<POE::NFA>, for example, is more of a proper state
+machine. The CPAN has several other kinds of sessions.
Everything ultimately builds on these classes or the concepts they
implement. If you're short on time, the things to read besides this
@@ -160,39 +161,43 @@ are L<POE::Kernel> and L<POE::Session>.
POE::Wheel objects are dynamic mix-ins for POE::Session instances.
These "wheels" perform very common, generic tasks in a highly reusable
-and customizable way. POE::Wheel::ReadWrite, for example, implements
+and customizable way. L<POE::Wheel::ReadWrite>, for example, implements
non-blocking buffered I/O. Nearly everybody needs this, so why
require people to reinvent it all the time?
-POE::Filter objects customize wheels in a modular way. Filters act as
+L<POE::Filter> objects customize wheels in a modular way. Filters act as
I/O layers, turning raw streams into structured data, and serializing
-structures into something suitable for streams. CPAN also has several
+structures into something suitable for streams. The CPAN also has several
of these.
-POE::Driver objects get relatively short shrift because very few are
-needed. The most common driver, POE::Driver::SysRW is ubiquitous and
-also the default, so most people will never need to specify one.
-
-But drivers are where wheels meet the road. In this case, the road is
+Drivers are where the wheels meet the road. In this case, the road is
some type of file handle. Drivers do the actual reading and writing
in a standard way so wheels don't need to know the difference between
send() and syswrite().
+L<POE::Driver> objects get relatively short shrift because very few are
+needed. The most common driver, L<POE::Driver::SysRW> is ubiquitous and
+also the default, so most people will never need to specify one.
+
=head2 Layer 3: Components
-POE::Component classes are essentially Perl classes that use POE to
+L<POE::Component> classes are essentially Perl classes that use POE to
perform tasks in a non-blocking or cooperative way. This is a very
broad definition, and POE components are all over the abstraction map.
-Many components, such as POE::Component::Server::SMTP, encapsulate the
+Many components, such as L<POE::Component::Server::SMTP>, encapsulate the
generic details of an entire application. Others perform rather
-narrow tasks, such as POE::Component::DirWatch::Object.
+narrow tasks, such as L<POE::Component::DirWatch::Object>.
POE components are often just plain Perl objects. The previously
-mentioned POE::Component::DirWatch::Object uses Moose. Other object
+mentioned L<POE::Component::DirWatch::Object> uses L<Moose>. Other object
and meta-object frameworks are compatible.
-CPAN's got quite a lot of components.
+Also of interest is L<POE::Component::Generic>, which is allows you to create
+a POE component from nearly nearly any blocking module.
+
+There are quite a lot of components on the CPAN.
+L<http://search.cpan.org/search?query=poe+component&mode=all>
=head2 Layer 4 and Beyond: Frameworks and Object Metaphors
@@ -202,26 +207,31 @@ entirely hide POE if necessary. The nice thing here is that even at
these high levels of abstraction, things will continue to interoperate
all the way down to layer 1.
-Two examples of ultra-high level abstraction are Sprocket, a
-networking framework that does its own thing, and POE::Stage, which is
-POE's creator's attempt to formalize and standardize POE components.
+Two examples of ultra-high level abstraction are L<Sprocket>, a networking
+framework that does its own thing, and L<POE::Stage>, which is POE's
+creator's attempt to formalize and standardize POE components.
+
+It is also possible to communicate between POE processes. This is called
+IKC, for I<Inter-Kernel Communication>. There are a few IKC components on
+the CPAN (L<http://search.cpan.org/search?query=IKC&mode=all>), notably
+L<POE::Component::IKC>, L<POE::TIKC> and L<POE::Component::Lightspeed>.
=head2 Layer 0: POE's Internals
-POE's layered architecture doesn't stop below the surface. POE's guts
-are broken into specific POE::Loop classes for each event loop it
-supports. Internals are divided up by type, giving POE::Resource
-classes for Aliases, Controls, Events, Extrefs, FileHandles, SIDs,
-Sessions, Signals, and Statistics.
+POE's layered architecture continues below the surface. POE's guts are
+broken into specific L<POE::Loop> classes for each event loop it supports.
+Internals are divided up by type, giving L<POE::Resource> classes for
+Aliases, Controls, Events, Extrefs, FileHandles, SIDs, Sessions, Signals,
+and Statistics.
POE::Kernel's APIs are extensible through POE::API mix-in classes.
Some brave souls have even published new APIs on CPAN, such as
-POE::API::Peek (which gives you access to some of the internal
-POE::Resource methods).
+L<POE::API::Peek> (which gives you access to some of the internal
+L<POE::Resource> methods).
-By design, it's possible to implement new POE::Kernel guts by creating
-another POE::Resource class. One can then expose the functionality
-with a new POE::API mix-in.
+By design, it's possible to implement new L<POE::Kernel> guts by creating
+another L<POE::Resource> class. One can then expose the functionality with
+a new POE::API mix-in.
=head1 DOCUMENTATION ROADMAP
@@ -231,59 +241,59 @@ talk about something more interesting.
=head2 Basic Features
-POE's basic features are documented mainly in POE::Kernel and
-POE::Session. Methods are documented in the classes that implement
+POE's basic features are documented mainly in L<POE::Kernel> and
+L<POE::Session>. Methods are documented in the classes that implement
them. Broader concepts are covered in the most appropriate class, and
sometimes they are divided among classes that share in their
implementation.
=head2 Basic Usage
-Basic usage, even for POE.pm, is documented in POE::Kernel. That's
+Basic usage, even for POE.pm, is documented in L<POE::Kernel>. That's
where most of POE's work is done, and POE.pm is little more than a
class loader.
=head2 @_[KERNEL, HEAP, etc.]
Event handler calling conventions, that weird C<@_[KERNEL, HEAP]>
-stuff, is documented in POE::Session. That's because POE::Session
+stuff, is documented in L<POE::Session>. That's because POE::Session
implements the calling convention, and other session types often do it
differently.
=head2 Base Classes Document Common Features
-The POE::Wheel, POE::Driver, POE::Filter, and POE::Component base
-clasess describe what's common among each class. It's a good idea to
-at least skim the base class documentation since the subclasses tend
-not to rehash the common things.
+The L<POE::Wheel>, L<POE::Driver>, L<POE::Filter>, and L<POE::Component>
+base classes describe what's common among each class. It's a good idea to
+at least skim the base class documentation since the subclasses tend not to
+rehash the common things.
-POE::Queue, POE::Resource, POE::Loop, and POE::API document the
+L<POE::Queue>, L<POE::Resource>, L<POE::Loop>, and L<POE::API> document the
concepts and sometimes the standard interfaces behind multiple
subclasess. You're encouraged to have a look.
=head2 Helper Classes
-POE includes some helper classes for portability. POE::Pipe, and its
-subclasses POE::Pipe::OneWay and POE::Pipe::TwoWay are portable pipes.
+POE includes some helper classes for portability. L<POE::Pipe>, and its
+subclasses L<POE::Pipe::OneWay> and L<POE::Pipe::TwoWay> are portable pipes.
=head2 Event Loop Bridges
-POE::Loop documents and specifies the interface for all of POE's event
+L<POE::Loop> documents and specifies the interface for all of POE's event
loop bridges. The individual classes may document specific details,
but generally they adhere to the spec strongly enough that they don't
need to.
-Many of the existing POE::Loop bridges provided in POE's base
+Many of the existing L<POE::Loop> bridges provided in POE's base
distribution will move out to separate distributions shortly. The
documentation will probably remain the same, however.
=head2 POE::Queue and POE::Queue::Array
POE's event queue is basically a priority heap implemented as an
-ordered array. POE::Queue documents the standard interface for POE
-event queues, and POE::Queue::Array implements the ordered array
-queue. Tony Cook has released POE::XS::Queue::Array, which is a
-drop-in C replacement for POE::Queue::Array. You might give it a try
+ordered array. L<POE::Queue> documents the standard interface for POE
+event queues, and L<POE::Queue::Array> implements the ordered array
+queue. Tony Cook has released L<POE::XS::Queue::Array>, which is a
+drop-in C replacement for L<POE::Queue::Array>. You might give it a try
if you need more performance. POE's event queue is some of the
hottest code in the system.
@@ -312,26 +322,27 @@ POE's basic requirements are rather light. Most are included with
modern versions of Perl, and the rest (if any) should be generally
portable by now.
-Time::HiRes is recommended, even for older Perls that don't include
-it. POE will work without it, but alarms and other features will be
-much more accurate if it's included. POE::Kernel will use Time::HiRes
+L<Time::HiRes> is highly recommended, even for older Perls that don't
+include it. POE will work without it, but alarms and other features will be
+much more accurate if it's included. L<POE::Kernel> will use Time::HiRes
automatically if it's available.
-Filter::Reference needs a module to serialize data for transporting it
-across a network. It will use Storable, FreezeThaw, YAML, or some
-other package with freeze() and thaw() methods. It can also use
-Compress::Zlib to conserve bandwidth and reduce latency over slow
-links, but it's not required.
+L<POE::Filter::Reference> needs a module to serialize data for transporting
+it across a network. It will use L<Storable>, L<FreezeThaw>, L<YAML>, or
+some other package with freeze() and thaw() methods. It can also use
+L<Compress::Zlib> to conserve bandwidth and reduce latency over slow links, but
+it's not required.
-If you want to write web servers, you'll need to install libwww-perl,
-which requires libnet. This is a small world of modules that includes
-HTTP::Status, HTTP::Request, HTTP::Date, and HTTP::Response. They are
-generally good to have, and modern versions of Perl even include them.
+If you want to write web servers, you'll need to install libwww-perl, which
+requires libnet. This is a small world of modules that includes
+L<HTTP::Status>, L<HTTP::Request>, L<HTTP::Date>, and L<HTTP::Response>.
+They are generally good to have, and modern versions of Perl even include
+them.
-Programs that use POE::Wheel::Curses require the Curses module, which
-in turn requires some sort of curses library.
+Programs that use L<POE::Wheel::Curses> will of course require the L<Curses>
+module, which in turn requires some sort of curses library.
-If you're using POE with Tk, you'll need Tk installed.
+If you're using POE with Tk, you'll need L<Tk> installed.
And other obvious things. Let us know if we've overlooked a
non-obvious detail.
@@ -446,41 +457,41 @@ TODO - Verify this is complete.
=head2 Layer 1
-POE::Kernel, POE::Session, POE::NFA
+L<POE::Kernel>, L<POE::Session>, L<POE::NFA>
=head2 Layer 2
-POE::Wheel, POE::Wheel::Curses, POE::Wheel::FollowTail,
-POE::Wheel::ListenAccept, POE::Wheel::ReadLine, POE::Wheel::ReadWrite,
-POE::Wheel::Run, POE::Wheel::SocketFactory
+L<POE::Wheel>, L<POE::Wheel::Curses>, L<POE::Wheel::FollowTail>,
+L<POE::Wheel::ListenAccept>, L<POE::Wheel::ReadLine>, L<POE::Wheel::ReadWrite>,
+L<POE::Wheel::Run>, L<POE::Wheel::SocketFactory>
-POE::Driver, POE::Driver::SysRW
+L<POE::Driver>, L<POE::Driver::SysRW>
-POE::Filter, POE::Filter::Block, POE::Filter::Grep,
-POE::Filter::HTTPD, POE::Filter::Line, POE::Filter::Map,
-POE::Filter::RecordBlock, POE::Filter::Reference,
-POE::Filter::Stackable, POE::Filter::Stream
+L<POE::Filter>, L<POE::Filter::Block>, L<POE::Filter::Grep>,
+L<POE::Filter::HTTPD>, L<POE::Filter::Line>, L<POE::Filter::Map>,
+L<POE::Filter::RecordBlock>, L<POE::Filter::Reference>,
+L<POE::Filter::Stackable>, L<POE::Filter::Stream>
=head2 Layer 3
-POE::Component, POE::Component::Client::TCP,
-POE::Component::Server::TCP
+L<POE::Component>, L<POE::Component::Client::TCP>,
+L<POE::Component::Server::TCP>
=head2 Layer 0
-POE::Loop, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
-POE::Loop::Select, POE::Loop::Tk
+L<POE::Loop>, L<POE::Loop::Event>, L<POE::Loop::Gtk>, L<POE::Loop::IO_Poll>,
+L<POE::Loop::Select>, L<POE::Loop::Tk>
-POE::Queue, POE::Queue::Array
+L<POE::Queue>, L<POE::Queue::Array>
-POE::Resource, POE::Resource::Aliases, POE::Resource::Events,
-POE::Resource::Extrefs, POE::Resource::FileHandles,
-POE::Resource::Performance, POE::Resource::SIDs,
-POE::Resource::Sessions, POE::Resource::Signals
+L<POE::Resource>, L<POE::Resource::Aliases>, L<POE::Resource::Events>,
+L<POE::Resource::Extrefs>, L<POE::Resource::FileHandles>,
+L<POE::Resource::Performance>, L<POE::Resource::SIDs>,
+L<POE::Resource::Sessions>, L<POE::Resource::Signals>
=head2 Helpers
-POE::Pipe, POE::Pipe::OneWay, POE::Pipe::TwoWay
+L<POE::Pipe>, L<POE::Pipe::OneWay>, L<POE::Pipe::TwoWay>
=head1 BUGS
@@ -563,17 +574,16 @@ Philip Gwyn is <gwynp@artware.qc.ca>. He extended the Wheels I/O
abstraction to support hot-swappable filters, and he eventually
convinced Rocco that unique session and kernel IDs were a good thing.
-Philip also enhanced Filter::Reference to support different
+Philip also enhanced L<POE::Filter::Reference> to support different
serialization methods. He has also improved POE's quality by finding
and fixing several bugs. He provided POE a much needed code review
around version 0.06.
=item Arnar M. Hrafnkelsson
-Arnar is <addi@umich.edu>. Addi tested POE and POE::Component::IRC on
-Windows, finding bugs and testing fixes. He appears throughout the
-Changes file. He has also written "cpoe", which is a POE-like library
-for C.
+Arnar is <addi@umich.edu>. Addi tested POE and L<POE::Component::IRC> on
+Windows, finding bugs and testing fixes. He appears throughout the Changes
+file. He has also written "cpoe", which is a POE-like library for C.
=item Dave Paris
@@ -587,11 +597,11 @@ testing and troubleshooting.
=item Dieter Pearcey
-Dieter Pearcey is <dieter@bullfrog.perlhacker.org>. He goes by
-several Japanese nicknames. Dieter's current area of expertise is in
-Wheels and Filters. He greatly improved Wheel::FollowTail, and his
-Filter contributions include the basic Block filter, as well as
-Stackable, RecordBlock, Grep and Map.
+Dieter Pearcey is <dieter@bullfrog.perlhacker.org>. He goes by several
+Japanese nicknames. Dieter's current area of expertise is in Wheels and
+Filters. He greatly improved L<POE::Wheel::FollowTail>, and his Filter
+contributions include the basic Block filter, as well as Stackable,
+RecordBlock, Grep and Map.
=item Robert Seifer
@@ -606,9 +616,9 @@ problem relating to anonymous subs, scope and @{} processing.
=item Matt Sergeant
-Matt contributed POE::Kernel::Poll, a more efficient way to watch
+Matt contributed L<POE::Kernel::Poll>, a more efficient way to watch
multiple files than select(). It's since been moved to
-POE::Loop::IO_Poll.
+L<POE::Loop::IO_Poll>.
=item Richard Soderberg
@@ -621,13 +631,13 @@ provides valuable testing and feedback from a user's point of view.
Dennis Taylor is <dennis@funkplanet.com>. Dennis has been testing,
debugging and patching bits here and there, such as Filter::Line which
he improved by leaps in 0.1102. He's also the author of
-POE::Component::IRC, the widely popular POE-based successor to his
-wildly popular Net::IRC library.
+L<POE::Component::IRC>, the widely popular POE-based successor to his
+wildly popular L<Net::IRC> library.
=item David Davis
David Davis, aka Xantus is <xantus@cpan.org>. David contributed patches
-to the HTTPD filter, and added CALLER_STATE to POE::Session. He is the
+to the HTTPD filter, and added CALLER_STATE to L<POE::Session>. He is the
author of L<Sprocket>, a networking framework built on POE.
=item Others?
Please sign in to comment.
Something went wrong with that request. Please try again.