Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  POE::REQUEST::UPWARD (3)

.ds Aq ’


POE::Request::Upward - internal base class for POE::Stage response messages



        This module isnt meant to be used directly.


POE::Stage messages are generally asynchronous, which means that multiple calls can be in play at once. To track them, POE::Stage uses a call tree rather than a call stack.

POE::Request::Upward is a base class for POE::Request messages that flow up from sub-stages (closer to leaf nodes) to their parents (closer to the root node). Both POE::Request::Emit and POE::Request::Returns are subclasses of POE::Request::Upward.

The Emit and Return message classes share a lot of common code. That code has been hoisted into this base class.

Upward messages are automatically created and dispatched as a side effect of calling POE::Request’s emit() and return() methods.


These methods are called directly on the class or object.


POE::Request::Upward’s new() constructor is almost always called internally by POE::Request->emit() or POE::Request->return(). Most parameters to emit() and return() are passed directly to this constructor.

POE::Request::Upward has one mandatory parameter: type. This defines the type of response being created. If specified, the optional args parameter must contain a hashref with response payloads. The contents of args are passed unchanged to the response’s handler as lexicals with names prefixed by arg_.

Response types are mapped to methods in the original requester’s stage through POE::Request’s on_$type parameters. In this example, responses of type success are mapped to the requester’s continue_on() method. Likewise error responses are mapped to the requester’s log_and_stop() method.

        my $req_connect = POE::Request->new(
                stage       => $tcp_client,
                method      => "connect",
                on_success  => "continue_on",
                on_error    => "log_and_stop",

How an asynchronous TCP connector might return success and error messages (although we’re not sure yet):

        my $req;
                type      => "success",
                args      => {
                        socket  => $socket,

                type        => "error",
                args        => {
                        function  => "connect",
                        errno     => $!+0,
                        errstr    => "$!",

Optionally, POE::Request objects may contain roles. Responses come back as on_${role}_${type} messages. For example, one stage might call another (a socket factory) to create a TCP client socket. In this example, the call’s role is connect, and the two previous return() calls are used to return a socket on success or error info on failure:

        my $req_connect = POE::Request->new(
                stage       => $tcp_client,
                method      => "connect",
                role        => "connect",

If the factor returns success, the on_connect_success() method will be called upon to handle it:

        sub on_connect_success {
                my $arg_socket;  # contains the "socket" argument

Likewise, on_connect_failure() will be called if the connection failed:

        sub on_connect_failure {
                my ($arg_function, $arg_errno, $arg_errstr);


See <> for known issues. See <> to report one.

POE::Stage is too young for production use. For example, its syntax is still changing. You probably know what you don’t like, or what you need that isn’t included, so consider fixing or adding that, or at least discussing it with the people on POE’s mailing list or IRC channel. Your feedback and contributions will bring POE::Stage closer to usability. We appreciate it.


POE::Request::Upward has two subclasses: POE::Request::Emit for emitting multiple responses to a single request, and POE::Request::Return for sending a final response to end a request.

POE::Request::Upward inherits from POE::Request.


Rocco Caputo <>.


POE::Request::Upward is Copyright 2005-2006 by Rocco Caputo. All rights are reserved. You may use, modify, and/or distribute this module under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 POE::REQUEST::UPWARD (3) 2009-06-11

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.