NAME

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

SYNOPSIS

This module isn't meant to be used directly.

DESCRIPTION

POE::Request::Upward is a base class for POE::Request messages that flow up the POE::Stage parent/child tree. These messages are instances of POE::Request::Emit and POE::Request::Return.

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 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 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 through to this constructor.

POE::Request::Upward has one mandatory parameter: "type". This defines the type of response being created. The optional "args" parameter should contain a hashref with response payloads. The contents of "args" are passed unchanged to the respones's handler as its $args parameter.

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.

$self->{req}{foo} = POE::Request->new(
	stage       => $some_stage_object,
	method      => "some_method_name",
	on_success  => "continue_on",
	on_error    => "log_and_stop",
);

How an asynchronous TCP connector might return success and error messages:

$self->{req}->return(
	type      => "success",
	args      => {
		socket  => $socket,
	},
);

$self->{req}->return(
	type        => "error",
	args        => {
		function  => "connect",
		errno     => $!+0,
		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.

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.

AUTHORS

Rocco Caputo <rcaputo@cpan.org>.

LICENSE

POE::Request::Upward 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.