GSP
Quick Navigator

Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


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

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



        This module isnt meant to be used directly.



DESCRIPTION

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.

PUBLIC METHODS

These methods are called directly on the class or object.

    new ARGUMENT_PAIRS

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



BUGS

See <http://thirdlobe.com/projects/poe-stage/report/1> for known issues. See <http://thirdlobe.com/projects/poe-stage/newticket> 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.

SEE ALSO

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.

AUTHORS

Rocco Caputo <rcaputo@cpan.org>.

LICENSE

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.