Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POE::Request::Upward(3User Contributed Perl DocumentatiPOE::Request::Upward(3)

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.

perl v5.32.0			  2009-06-11	       POE::Request::Upward(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC METHODS | BUGS | SEE ALSO | AUTHORS | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Request::Upward&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help