NAME
POE::Request - a message class for requesting POE::Stage services
SYNOPSIS
# Note, this is not a complete program.
# See the distribution's examples directory.
$self->{req}{do_it} = POE::Request->new(
method => "method_name", # invoke this method
stage => $self->{stage_object}, # of this stage
on_one => "do_one", # map a "one" response to method
args => {
param_1 => 123, # with this parameter
param_2 => "abc", # and this one
}
);
# Handle a "one" response.
sub do_one {
my ($self, $args) = @_;
...;
}DESCRIPTION
POE::Request objects are created to start dialogues between POE::Stage objects. Subclasses of POE::Request are used to continue established dialogues, but they are not created explicitly. Rather, they are created as side effects of calling POE::Request methods.
POE::Request objects (and those of its subclasses) act as data scopes when treated as hash references. Storing data into a POE::Request object transparently stores it in the current POE::Stage object. Data stored in this manner becomes available again when accessing responses to the request.
For example:
$self->{req}{foo} = POE::Request->new( ... );
$self->{req}{foo}{key} = "a sample value";A response to this request is handled at a later point in time:
print "$self->{rsp}{key}\n"; # prints "a sample value".POE::Stage::TiedAttributes and POE::Request::TiedAttributes discuss this in greater detail.
PUBLIC METHODS
Request methods are called directly on the objects themselves.
new PAIRS
Create a new POE::Request object. The request will automatically be sent to its destination. Factors on the local or remote process, or pertaining to the network between them, may prevent the request from being delivered immediately.
POE::Request->new() requires at least two parameters. "stage" contains the POE::Stage object that will receive the request. "method" is the method to call when the remote stage handles the request.
Parameters for the message's destination can be supplied in the optional "args" parameter. These parameters will be passed untouched to the message's destination's $args parameter.
POE::Request->new() returns an object which must be saved. Destroying a request object will cancel the request and free up all data and resources associated with it.
By convention, requests made on behalf of higher-level requests are stored in the higher-level request's data. Therefore, cancelling a request cascades destruction and cancellation through all its sub-requests. Pretty neat, huh?
Instances of POE::Request subclasses, such as those created by $request->return(), do not need to be saved. They are ephemeral responses and re-requests, and their lifespans do not control the duration of an inter-stage dialogue.
init HASHREF
The init() method receives the request's constructor $args before they are processed and stored in the request. Its timing gives it the ability to modify members of $args, add new ones, or remove old ones.
Custom POE::Request subclasses may use init() to verify that parameters are correct. Currently init() must throw an exeception with die() to signal some form of failure.
return PAIRS
Cancels the current POE::Request object, invalidating it for future operations, and creates a POE::Request::Return object. This return message is initialized with the PAIRS of supplied parameters. It is automatically (if not immediately) sent back to the POE::Stage that created the original request.
Please see POE::Request::Return for details about return messages.
emit PAIRS
Creates a POE::Request::Emit object initialized with the PAIRS of supplied parameters. The emitted response will be automatically sent back to the creator of the request being invoked.
emit() is designed to be called multiple times on the same request.
Unlike return(), emit() does not cancel the current request, and emitted messages can be replied.
cancel
Explicitly cancel a request. Normally destroying the request object is sufficient, but a request's destruction cannot be triggered by the stage handing the request. The request's handler can call cancel() however.
As mentioned earlier, canceling a request frees up the data associated with that request. Cancellation and destruction cascade through the tree of requests, freeing up everything associated with the request originally canceled.
A canceled request cannot generate a response. Use return() instead of cancel() if you want to return a response before canceling the request.
DESIGN GOALS
Requests are designed to encapsulate messages passed between stages.
Requests may be subclassed.
At some point in the future, request classes may be used as message types. More formal POE::Stage interfaces may take advantage of explicit message typing in the future.
BUGS
See http://thirdlobe.com/projects/poe-stage/report/1 for known issues. See http://thirdlobe.com/projects/poe-stage/newticket to report one.
SEE ALSO
POE::Request has subclasses that are used internally. While they share the same interface as POE::Request, all its methods are not appropriate in all its subclasses.
Please see POE::Request::Upward for a discussion of response events, 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
Rocco Caputo <rcaputo@cpan.org>.
LICENSE
POE::Request is Copyright 2005 by Rocco Caputo. All rights are reserved. You may use, modify, and/or distribute this module under the same terms as Perl itself.