NAME

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;

DESCRIPTION

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 server's 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 don't have to.

RESERVED METHODS

  my $object = POE::Stage::Something->new( foo => 123 );

        package POE::Stage::Something;
        sub init {
                print my $arg_foo, "\n";  # displays "123\n".
        }

        sub some_method :Handler {
                # Lexical magic occurs here.
        }

        sub not_a_handler {
                # No lexical magic happens in this one.
        }

        sub on_event {
                # Lexical magic occurs here.  No :Handler necessary.
        }

        use POE::Stage qw(expose);

        sub do_request :Handler {
                my $req_subrequest = POE::Request->new( ... );
                expose $req_subrequest, my $sub_cookie;
                $sub_cookie = "stored in the subrequest";
        }

USING

DESIGN GOALS

POE::Stage hides nearly all of POE, including the need to create POE::Session objects and explicitly define event names and their handlers. The :Handler subroutine attribute defines which methods handle messages. There's never a need to guess which message types they handle:

        # Handle the "foo" message.
        sub foo :Handler {
                ...
        }

POE::Stage simplifies message passing and response handling in at least three ways. Consider:

        my $request = POE::Request->new(
                stage => $target_stage,
                method => $target_method,
                args => \%arguments,
                on_response_x => "handler_x",
                on_response_y => "handler_y",
                on_response_z => "handler_z",
        );

First, it provides standard message clasess. Developers don't need to roll their own, potentially non-interoperable message-passing schemes. The named \%arguments are supplied and are available to each handler in a standard way, which is described later in the MAGICAL LEXICAL TOUR.

Second, POE::Stage provides request-scoped closures via $req_foo, $rsp_foo, and expose(). Stages use these mechanisms to save and access data in specific request and response contexts, eliminating the need to do it explicitly.

Third, response destinations are tied to the requests themselves. In the above example, responses of type "response_x" will be handled by "handler_x". The logic flow of a complex program is more readily apparent. It gets better, too. See HANDLER NAMING CONVENTIONS.

The mechanisms of message passing and context management become implicit, allowing them to be extended transparently. This will be extended across processes, hopefully with few or no seams.

POE::Stage includes object-oriented classes for low-level event watchers. They simplify and standardize POE::Kernel's interface, and they allow watchers to be extended cleanly through normal OO techniques. The lifespan of each resource is tightly coupled to the lifespan of each object, so ownership and relevance are clearly indicated.

POE::Stage standardizes shutdown semantics for requests and stages. Requests are canceled by destroying their objects, and stages are shut down the same way.

POE::Stage simplifies the cleanup of complex, multi-stage activity. Resources for a particular request should be stored within its closure. Canceling the request triggers destruction of that closure and its contents, which in turn triggers the destruction of the resources allocated to that request. These resources include stages and requests created during the lifetime of the request. They too are canceled and freedm

MAGICAL LEXICAL TOUR

Lexical variable prefixes indicate the data's origin. For example, $arg_name is the "name" argument included with a message:

        my $request = POE::Request->new(
                method => "something",
                args => { name => "ralph" },
                ...,
        );

        sub something :Handler {
                my $arg_name;  # already contains "ralph"
        }

The full list of prefixes and data sources:

HANDLER NAMING CONVENTIONS

        # Handle the "foo" message.
        sub foo :Handler { ... }

        # Handle the "on_foo" and "foo" messages.
        sub on_foo { ... }

The on_foo() method above handles both "on_foo" and "foo" messages. Given both a foo() and an on_foo(), however, on_foo() will take precedence.

Requests include on_* parameters that map response types to response handlers. For example, this request expects two return types, "success" and "failure". On success, the handle_success() method is called. On failure, handle_failure() is called.

        my $req_subrequest = POE::Request->new(
                ...,
                on_success => "handle_success",
                on_failure => "handle_failure",
        );

Response types are specified by the "type" parameter to $req->emit() and $req->return(). "emit" and "return" are the default types for emit() and return(), respectively.

Requests can also have roles, which are usually descriptive of the transaction. For example, consider a DNS request for a web client component:

        my $req_resolve = POE::Request->new(
                ...,
                role => "resolver",
        );

This is the role of the request, not of the stage that will handle it. In this case, there are no on_* parameters. Success and failure come back to methods named "on_" . $request_role . "_" . $response_type. In the previous example, they are:

        sub on_resolver_success { ... }
        sub on_resolver_failure { ... }

When subclassing a POE::Stage class, it's sometimes useful to intercept emit() and return() messages. The subclass may implement handlers directly, or it may override or extend the response. This is done by defining "on_my_" . $response_type methdos in the subclass. For example, a TCP connection stage might emit an "input" event, like so:

        sub on_socket_readable {
                ...;
                $req->emit( type => "input", input => $data );
        }

A subclass might implement the code to handle the input. It can do so by defining on_my_input():

        sub on_my_input {
                # send a response here
        }

Messages intercepted like this will not be rethrown automatically to the caller. If that's desired, on_my_input() will need to emit() or

TODO - Make a better example. Something that can tie all these things together conceptually.

BUGS

BUG TRACKER

REPOSITORY

OTHER RESOURCES

SEE ALSO

<http://thirdlobe.com/projects/poe-stage/> - POE::Stage is hosted here.

<http://www.eecs.harvard.edu/~mdw/proj/seda/> - SEDA, the Staged Event Driven Architecture. It's Java, though.

AUTHORS

LICENSE