NAME

POE::Stage::TiedAttributes - internal class for request-scoped storage

SYNOPSIS

This module is not meant to be used directly.

DESCRIPTION

POE::Stage::TiedAttributes implements a large chunk of POE::Stage's magical data scopes.

It manages the special $self->{req} and $self->{rsp} fields. They will always point to the proper POE::Request objects.

It holds request-scoped data, which is really stage-scoped data associated with the request.

It performs necessary cleanup when stages are destroyed or requests are canceled.

It does these things as automatically as possible.

POE::Stage's "req" Data Member

Every POE::Stage object has two read-only data members: req and rsp. The req data member refers to the POE::Request object that the stage is currently handling. Consider this request:

my $req = POE::Request->new(
	stage  => $stage_1,
	method => "handle_it",
);

It will be handled $stage_1's handle_it() method. For the sake of example, handle_it() only prints the request object:

sub handle_it {
	my ($self, $args) = @_;
	print "$self->{req}\n";
}

Actually, it may not be exactly the same as $req, but it will be its moral equivalent. This caveat leaves a loophole through which we can pass requests across process boundaries later.

$self->{req} is also great for responding to requests:

$self->{req}->emit( ... );
$self->{req}->return( ... );

You should see POE::Request for more information about emit() and return().

It should be noted that $self->{req} is valid when responses to our own requests are being handled. This hander cascades a return() from a sub-request to a parent request. It is called in response to some request we have made, and in turn it passes a response parameter back up the request chain.

sub handle_a_response {
	my ($self, $args) = @_;
	$self->{req}->return(
		type      => "done",
		args      => {
			result  => $args->{sub_result},
			cookie  => $self->{req}{cookie},
		},
	);
}

POE::Stage's "rsp" Data Member

The special $self->{rsp} data member refers to responses to requests made by a stage. It's only valid when a response handler is currently executing.

sub handle_sub_response {
	my ($self, $args) = @_;
	$self->{rsp}->recall( ... );
}

When used as a hash, the response in $self->{rsp} refers to the scope of the request that generated it. Therefore you can store data in the original request and automatically have access to it from the response handler.

PUBLIC METHODS

None. This class is used implicitly when POE::Session accesses its data members. It is indirectly used by POE::Request as well.

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::TiedAttributes, which implements the POE::Request side of this magic and discusses the request-scoped namespaces in a little more detail.

AUTHORS

Rocco Caputo <rcaputo@cpan.org>.

LICENSE

POE::Stage::TiedAttributes 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.

cpanm POE::Stage

perl -MCPAN -e shell
install POE::Stage