NAME

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

SYNOPSIS

This module isn't 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.

cpanm POE::Stage

perl -MCPAN -e shell
install POE::Stage