# Perl Object Environment

The Perl Object Environment (POE) is a library of Perl modules written in the Perl programming language by Rocco Caputo et al.
From CPAN:
    "POE originally was developed as the core of a persistent object server and runtime environment. It has evolved into a general purpose multitasking and networking framework, encompassing and providing a consistent interface to other event loops such as Event and the Tk and Gtk toolkits."

## Architecture and layers of abstraction

POE, The Perl Object Environment can be thought of as a tiny modular operating system. One or more POE programs or instances can be run concurrently and are generally well suited for cooperative multitasking. The POE package consists of namespaces and abstractions that guide future development of POE in an open-ended CPAN-style convention.

### The event layer

The informal architecture consists of a set of layers with a kernel on the bottom. This tiny kernel represents the events layer which operates as the main loop of each running POE instance. The first call is to the "event dispatcher" - POE::Kernel.
The POE::Kernel namespace contains a suite of functions which are plugged into the kernel itself. These loop abstractions are designed after POE's standardized event loop bridge interface - POE::Loop. These can be mixed and matched as needed to provide runtime services and a lean facility for interprocess communication. The basic functions are POE::Loop::Event, POE::Loop::Poll and POE::Loop::Select. Also available are POE::Loop::Tk and POE::Loop::Gtk which offer hooks into other loop bridges in the external environment. If that isn't enough, the POE::Loop kernel abstraction provides reusable signal callbacks, time or alarm callbacks, and filehandle activity callbacks as well as administrative functions such as initializing, executing, and finalizing event loops.
There is also a higher level packaging framework - POE::Macro and a debugging utility for testing them called POE::Preprocessor. This framework has yielded POE::Macro::UseBytes.
    NOTE: As the Perl tradition mandates, POE is also a moving target.
Always check CPAN to see what new goodies the community has placed in the archive. (...and remember Perl's Motto: "There's more than one way to do it" per Larry)
The Running Kernel operates through primordial finite-state machines constructed from another set of abstractions ruled by the POE::Session architecture. A POE::Session is almost trivially defined as a map of events to the functions, class methods, and/or object methods that handle them. POE::Session objects also contain a storage space shared by all its event handlers, called a heap. Any way you slice them the states are solidly identified and clearly defined.
A more featureful event handler is a POE::Session subclass called POE::NFA - an event-driven Nondeterministic finite automaton (a smarter finite state machine). This event handler moves from one strictly defined state to another as events, polls, user selections, or other external events require. This state machine acts to encapsulate a wide range of generic event driven threads allowing much tighter tracking along the execution path than the relatively informal POE::Session.

### The I/O layer

The Kernel's next requirement is for Input-Output handlers that exist in a single I/O layer called Wheels. Wheels initiate actions, handle their resulting low-level events, and produce higher-level events for the sessions that use them. Wheels, like Sessions and Loops are built from a uniform set of abstractions - POE::Wheel - that sit on top of the Kernel. There are seven highly specialized and well-defined Wheels in POE's base distribution:
* POE::Wheel::Run - Creates and interacts with child processes using pipe, fork, and sometimes exec. Interaction is done through the child's standard input and output.
* POE::Wheel::SocketFactory - A way to create client and server sockets without blocking to wait for their establishment.
* POE::Wheel::Curses - A handler for non-blocking input from the Curses text interface library. CPAN components such as Curses::UI::POE and Term::Visual build upon it.
* POE::Wheel::FollowTail - Tracks an ever-growing file, such as a log or a collaborative document, by keeping a handle on its tail.
* POE::Wheel::ListenAccept - A subset of POE::Wheel::SocketFactory used for listening on existing server sockets and accepting connections from remote clients.
* POE::Wheel::ReadLine - A non-blocking, event driven analogue to Term::ReadLine.
* POE::Wheel::ReadWrite - A high-performance NBIO file handler for POE that uses POE's drivers and filters to perform buffered read and write on filehandles which draws on the next layer - POE's own little file system.

### The file layers

Drivers do the actual work of reading and writing filehandles. They are built according to the less abstract definitions contained in the POE::Driver module. The main driver implemented at the time of this writing is POE::Driver::SysRW - a universal filehandle reader/writer designed especially for POE::Wheel::ReadWrite.
The next layer, built from POE::Filter and probably the focus of most Perl Obfuscation Efficianados (see POE #POE Humor below), is the POE::Filter set:
* POE::Filter::Block - parses input as fixed-length blocks. On the output side, it merely passes data through unscathed.
* POE::Filter::HTTPD - parses input as HTTP requests and translates them into HTTP::Request objects. On the output side, it takes HTTP::Response objects and turns them into something suitable to be sent to a web client/user-agent.
* POE::Filter::Line - parses incoming streams into lines and turns outgoing lines into streams. It used to be very basic, but recent improvements have added interesting features like newline autodetection.
* POE::Filter::Reference - used to send Perl structures between POE programs or between POE and other Perl programs. On the input side, frozen data (via Storable, FreezeThaw, YAML, or some other serialization mechanism) is thawed into Perl data structures. On output, references given to the filter are frozen. Data may also be compressed on request if Compress::Zlib is installed.
* POE::Filter::Stream - does nothing. It merely passes data through without any change.
see POE at CPAN for the complete list

## Components

Several larger packages have been written in POE according to the POE::Component documentation. These are event-driven modules, many of which act as little daemons that provide services to larger packages to which they belong. Some of them facilitate higher-level communications between modules, especially stand-alone applications that need to remain independent from the main distribution of Perl.
In general, POE Components are ready-made high level procedures that perform specific large tasks. A few examples:
* Component::Server::TCP - a special-purpose TCP servlet
* Component::Client::TCP - a POE-aware TCP client
* POE::Component::IRC - a nearly full-featured IRC client.
* POE::Component::Server::IRC - an RFC 2810 to RFC 2813 compliant IRC server (under development)
* POE::Component::UserBase - a user authentication and data persistence servlet.

## Humor

* The Acme::POE::Knee module on the CPAN.
* A number of silly acronym expansions at the end of What POE Is.