new ARGUMENT_PAIRS

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;
        $req->return(
                type      => "success",
                args      => {
                        socket  => $socket,
                },
        );

        $req->return(
                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);
        }