POE::Stage 0.02_00

POE::Stage is a base Perl class for message-driven objects.

SYNOPSIS

#!/usr/bin/env perl
{
package App;
use POE::Stage::App qw(:base);
sub on_run {
print "hello, ", my $arg_whom, "!n";
}
}
App->new()->run( whom => "world" );
exit;

POE::Stage is a set of base classes for message-driven objects. It cleanly implements standard patterns that have emerged from years of working with POE and POE::Component modules.

As I hope the name implies, POE::Stage objects encapsulate discrete steps, or stages, of a larger task. Eventually they come together to implement programs.
For example, HTTP requests are performed in four or so distinct stages: 1. The servers address is resolved. 2. The client establishes a connection to the server. 3. The client transmits a request. 4. The client receives a response.

By design, POE::Stage promotes the decomposition of tasks into multiple, smaller stages. If these stages are generic enough, new tasks may be handled by reusing them in different configurations.

The hypothetical HTTP client might be a single stage composed of three smaller ones: A DNS resolver stage, which accepts DNS requests and returns DNS responses. A TCP client connection factory, which takes socket endpoint descriptions and other parameters, and eventually returns established connections. Finally, there would be an HTTP protocol stage that uses established connections to send requests and parse responses.

These stages would be encapsulated by a higher-level HTTP client stage. This would accept HTTP requests and return HTTP responses after performing the necessary steps to gather them.

This will sound familiar to anyone working with objects.

These objects are asynchronous and message-driven, however. The base message class, POE::Request, and its subclasses, implement a standard request/response interface between POE::Stage objects. Where possible, these messages attempt to mimic simpler, more direct call/return syntax, albeit asynchronously. POE::Stage also provides a powerful closure-based system for maintaining request and response state, so you dont have to.