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
POE::Request::Upward(3) User Contributed Perl Documentation POE::Request::Upward(3)

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

        This module isn't 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;
        $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);
        }

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.

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 <rcaputo@cpan.org>.

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.
2009-06-11 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

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