NAME
POE::Stage - a proposed base class for formalized POE components
SYNOPSIS
# Note, this is not a complete program.
# See the distribution's examples directory.
my $stage = POE::Stage::Subclass->new();
my $request = POE::Request->new(
stage => $stage, # Invoke this stage
method => "method_name", # calling this method
args => \%parameter_pairs, # with these parameters.
);DESCRIPTION
POE::Stage is a proposed base class for POE components. Its purpose is to standardize the most common design patterns that have arisen through years of POE::Component development.
Complex programs generally perform their tasks in multiple steps, or stages. For example, fetching a web page requires four or so steps: 1. Look up the host's address. 2. Connect to the remote host. 3. Transmit the request. 4. Receive the response.
POE::Stage promotes the decomposition of multi-step processes into discrete, reusable stages. In this case: POE::Stage::Resolver to resolve host names into addresses. POE::Stage::Connector to establish a socket connection to the remote host. POE::Stage::StreamIO to transmit the request and receive the response.
Stages perform their tasks in response to request messages. They return messages containing the result of each task as it's completed.
If done right, high-level stages will be built from lower-level ones. POE::Stage::HTTPClient would present a simple request/response interface while internally creating and coordinating POE::Stage::Resolver, POE::Stage::Connector, and POE::Stage::StreamIO as necessary.
RESERVED METHODS
As a base class, POE::Stage must reserve a small number of methods for its own.
new PARAMETER_PAIRS
Create and return a new POE::Stage object, optionally passing key/value PAIRS in its init() callback's $args parameter. Unlike in POE, you must save the object POE::Stage->new() returns if you intend to use it.
It is not recommended that subclasses override new. Rather, they should implement init() to initialize themselves after instantiation.
init PARAMETER_PAIRS
init() is a virtual base method used to initialize POE::Stage objects after construction. Subclasses override this to perform their own initialization. The new() constructor will pass its public parameters through to $self->init($key_value_pairs).
USING
TODO - Describe how POE::Stage is used. Outline the general pattern for designing and subclassing.
DESIGN GOALS
Eliminate the need to manage POE::Session objects directly. One common component pattern uses an object as its command interface. Creating the object starts an internal POE::Session. Destroying the command object shuts that session down. POE::Stage takes care of the session management.
Standardize messages between components. POE components sport a wide variety of message-based interfaces, limiting their interoperability. POE::Stage provides a base POE::Message class that can be used by itself or subclassed.
Create a class library for event watchers. POE's Kernel-based watchers divert their ownership away from objects and sessions. POE::Watcher objects wrap and manage POE::Kernel's watchers, providing a clear indicator of their ownership and lifetimes.
Eliminate positional event parameters. POE promotes the use of positional parameters (ARG0, ARG1, etc.) POE::Stage uses named parameters throughout. POE::Watcher objects translate POE::Kernel's ARG0-based values into named parameters. POE::Message objects use named parameters.
Standardize message and event handlers' calling conventions. All POE::Message and POE::Watcher callbacks accept the same two parameters: $self and a hash reference containing named parameters.
Eliminate the need to manage task-specific data. POE components must explicitly create task contexts internally and associate them with requests. As requests finish, components need to ensure their associated contexts are cleaned up or memory leaks ensue. POE::Stage provides special data members, $self->{req} and $self->{rsp}. They are automatically associated with requests being made of an outer stage or being made to an inner or sub-stage, respectively. They are automatically cleaned up when a request is finished.
Standardize the means to shut down stages. POE components implement a variety of shutdown methods. POE::Stage objects are shut down by destroying their objects.
Associate high-level requests with the lower-level requests that are made to complete a task. Interactions between multiple POE components requires very careful state and object management, often explicitly coded by the components' user. POE::Stage combines request-scoped data with object-based requests, watchers, and stages, to automatically clean up all the resources associated with a request.
BUGS
See http://thirdlobe.com/projects/poe-stage/report/1 for known issues. See http://thirdlobe.com/projects/poe-stage/newticket to report one.
SEE ALSO
POE::Request is the class that defines inter-stage messages. POE::Watcher is the base class for event watchers, without which POE::Stage won't run very well.
SEDA is at http://www.eecs.harvard.edu/~mdw/proj/seda/.
AUTHORS
Rocco Caputo <rcaputo@cpan.org>.
LICENSE
POE::Stage is Copyright 2005 by Rocco Caputo. All rights are reserved. You may use, modify, and/or distribute this module under the same terms as Perl itself.