NAME

SYNOPSIS

        # Note, this is not a complete program.
        # See the distribution's examples directory.

        my $req_subrequest = POE::Request->new(
                method    => "method_name",   # invoke this method
                stage     => $self,           # of this stage
                on_one    => "do_one",        # map a "one" response to method
                args      => {
                        one => 123,         # with this parameter
                        two => "abc",       # and this one
                }
        );

        # Handle a "one" response.
        sub do_one :Handler {
                my ($arg_one, $arg_two);
                print "$arg_one\n";  # 123
                print "$arg_two\n";  # abc
                ...;
                my $req;
                $req->return( type => "one", moo => "retval" );
        }

        # Handle one's return value.
        sub do_one :Handler {
                my $arg_moo;
                print "$arg_moo\n";  # "retval"
        }

DESCRIPTION

POE::Request includes methods that transmit responses when called. These methods internally create instances of POE::Request subclasses. The return() method creates a POE::Stage::Return object, which ends a transaction and returns a final result. There is also an emit() method that creates a POE::Request::Emit object. Emitted messages do not terminate the transactions they're belong to, so they may act as interim responses.

POE::Request::Emit has its own response method, recall(). The recipient of an emitted interim response can recall the session at the other end of the current transaction. emit() and recall() may be used together to extend a two-way dialog within the context of an original request.

Each new POE::Request creates two closures, one for the sender and one for the receiver. Members of the sender's closure can be accessed using POE::Stage's expose() function. For example, to expose a sub-request's "hostname" member as the lexical $subrequest_hostname variable:

        use POE::Session qw(expose);
        my $req_subrequest = POE::Request->new(...);
        expose $req_subrequest, my $subrequest_hostname;
        $subrequest_hostname = "remote.host.name";

The request's destination may have its own "hostname" member, but it will be separate from the caller's. The special $req lexical refers to the POE::Request object that called us, while $req_hostname refers to the "hostname" member in the invocant's end of the request.

        sub on_request {
                my $req_hostname = Sys::Hostname::hostname();
                ...;
                $req->return(
                        type => "success",
                        args => { retval => $something }
                );
        }

When the caller receives a response, either via an invocant's use of emit() or return(), there are special $rsp and $rsp_membername lexicals. $rsp refers to the POE::Request::Emit or ::Return message we're handling. It's usually used to call $rsp->recall(...). Lexicals prefixed by "rsp_", such as $rsp_hostname, refer to values previously stored in the original request via expose(). In our contrived example:

        sub on_resolver_success {
                my $arg_retval;  # contains the value of the "retval" argument
                my $rsp_hostname;  # contains "remote.host.name", assigned above
        }

This lexical magic only works with methods intended to be used as message handlers. They are identified by the :Handler attribute or by method names beginning with "on_".

PUBLIC METHODS

        sub init {
                my ($self, $my_args) = @_;

                # Changing $my_args or $args will alter the same, original
                # argument hash.
        }

        App creates a request for an http client.
                HTTP client creates a request for a socket.
                        Socket factory creates a request for a DNS resolver.

        sub on_http_fetch {
                ...;
                my $req_socket = POE::Request->new(
                        stage => $socket_factory,
                        method => "open_socket",
                );

DESIGN GOALS

Requests may be subclassed, incorporating specific features and defaults to make their use easier.

Future plans:

At some point in the future, request classes may be used as message types rather than "<type =" $type>> parameters. More formal POE::Stage interfaces may take advantage of explicit message typing in the future.

We'd also like to incorporate a standard form of interprocess communication within POE::Request, possibly with the use of proxy stages that represent remote code. In theory, a stage doesn't need to know its peers are off-world.

BUGS

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

Please see POE::Request::Upward for a discussion of response events (emit and return), and how they are mapped to method calls by the requesting stage. POE::Request::Return and POE::Request::Emit are specific kinds of upward-facing response messages.

POE::Request::Return, POE::Request::Recall, POE::Request::Emit, and POE::Request::Upward.

AUTHORS

LICENSE