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

FreeBSD Manual Pages


home | help
POE::Component::ClientUsereContributed PerPOE::Component::Client::Keepalive(3)

       POE::Component::Client::Keepalive - manage connections, with keep-alive

       version 0.272

	 use warnings;
	 use strict;

	 use POE;
	 use POE::Component::Client::Keepalive;

	   inline_states => {
	     _start    => \&start,
	     got_conn  => \&got_conn,
	     got_error => \&handle_error,
	     got_input => \&handle_input,


	 sub start {
	   $_[HEAP]{ka}	= POE::Component::Client::Keepalive->new();

	     scheme  =>	"http",
	     addr    =>	"",
	     port    =>	9999,
	     event   =>	"got_conn",
	     context =>	"arbitrary data	(even a	reference) here",
	     timeout =>	60,

	   print "Connection is	in progress.\n";

	 sub got_conn {
	   my ($kernel,	$heap, $response) = @_[KERNEL, HEAP, ARG0];

	   my $conn    = $response->{connection};
	   my $context = $response->{context};

	   if (defined $conn) {
	     if	($response->{from_cache}) {
	       print "Connection was established immediately.\n";
	     else {
	       print "Connection was established asynchronously.\n";

	       InputEvent => "got_input",
	       ErrorEvent => "got_error",

	     "Connection could not be established: ",
	     "$response->{function} error $response->{error_num}: ",

	 sub handle_input {
	   my $input = $_[ARG0];
	   print "$input\n";

	 sub handle_error {
	   my $heap = $_[HEAP];
	   delete $heap->{connection};

       POE::Component::Client::Keepalive creates and manages connections for
       other components.  It maintains a cache of kept-alive connections for
       quick reuse.  It	is written specifically	for clients that can benefit
       from kept-alive connections, such as HTTP clients.  Using it for	one-
       shot connections	would probably be silly.

	 Creates a new keepalive connection manager.  A	program	may contain
	 several connection managers.  Each will operate independently of the
	 others.  None will know about the limits set in the others, so	it's
	 possible to overrun your file descriptors for a process if you're not

	 new() takes up	to five	parameters.  All of them are optional.

	 To limit the number of	simultaneous connections to a particular host
	 (defined by a combination of scheme, address and port):

	   max_per_host	=> $max_simultaneous_host_connections, # defaults to 4

	 To limit the overall number of	connections that may be	open at	once,

	   max_open	=> $maximum_open_connections, #	defaults to 128

	 Programs are required to give connections back	to the manager when
	 they are done.	 See the free()	method for how that works.  The
	 connection manager will keep connections alive	for a period of	time
	 before	recycling them.	 The maximum keep-alive	time may be set	with

	   keep_alive	=> $seconds_to_keep_free_conns_alive, #	defaults to 15

	 Programs may not want to wait a long time for a connection to be
	 established.  They can	set the	request	timeout	to alter how long the
	 component holds a request before generating an	error.

	   timeout	=> $seconds_to_process_a_request, # defaults to	120

	 Specify a bind_address	to bind	all client sockets to a	particular
	 local address.	 The value of bind_address will	be passed directly to
	 POE::Wheel::SocketFactory.  See that module's documentation for
	 implementation	details.

	 Allocate a new	connection.  Allocate()	will return a request ID
	 immediately.  The allocated connection, however, will be posted back
	 to the	requesting session.  This happens even if the connection was
	 found in the component's keep-alive cache.  It's a bit	slower,	but
	 the use cases are cleaner that	way.

	 Allocate() requires five parameters and has an	optional sixth.

	 Specify the scheme that will be used to communicate on	the connection
	 (typically http or https).  The scheme	is required, but you're	free
	 to make something up here.  It's used internally to differentiate
	 different types of socket (e.g., ssl vs. cleartext) on	the same
	 address and port.

	   scheme  => $connection_scheme,

	 Request a connection to a particular address and port.	 The address
	 and port must be numeric.  Both the address and port are required.

	   address => $remote_address,
	   port	   => $remote_port,

	 Specify an name of the	event to post when an asynchronous response is
	 ready.	 This is of course required.

	   event   => $return_event,

	 Set the connection timeout, in	seconds.  The connection manager will
	 post back an error message if it can't	establish a connection within
	 the requested time.  This parameter is	optional.  It will default to
	 the master timeout provided to	the connection manager's constructor.

	   timeout => $connect_timeout,

	 Specify additional contextual data.  The context defines the
	 connection's purpose.	It is used to maintain continuity between a
	 call to allocate() and	an asynchronous	response.  A context is
	 extremely handy, but it's optional.

	   context => $context_data,

	 In summary:

	     scheme   => "http",
	     address  => "",
	     port     => 80,
	     event    => "got_a_connection",
	     context  => \%connection_context,

	 The response event ("got_a_connection"	in this	example) contains
	 several fields, passed	as a list of key/value pairs.  The list	may be
	 assigned to a hash for	convenience:

	   sub got_a_connection	{
	     my	%response = @_[ARG0..$#_];

	 Four of the fields exist to echo back your data:

	   $response{address}	 = $your_request_address;
	   $response{context}	 = $your_request_context;
	   $response{port}	 = $your_request_port;
	   $response{scheme}	 = $your_request_scheme;

	 One field returns the connection object if the	connection was
	 successful, or	undef if there was a failure:

	   $response{connection} = $new_socket_handle;

	 On success, another field tells you whether the connection contains
	 all new materials.  That is, whether the connection has been recycled
	 from the component's cache or created anew.

	   $response{from_cache} = $status;

	 The from_cache	status may be "immediate" if the connection was
	 immediately available from the	cache.	It will	be "deferred" if the
	 connection was	reused,	but another user had to	release	it first.
	 Finally, from_cache will be false if the connection had to be created
	 to satisfy allocate().

	 Three other fields return error information if	the connection failed.
	 They are not present if the connection	was successful.

	   $response{function}	 = $name_of_failing_function;
	   $response{error_num}	 = $! as a number;
	   $response{error_str}	 = $! as a string;

	 Free()	notifies the connection	manager	when connections are free to
	 be reused.  Freed connections are entered into	the keep-alive pool
	 and may be returned by	subsequent allocate() calls.


	 For now free()	is called with a socket, not a connection object.
	 This is usually not a problem since
	 POE::Component::Connection::Keepalive objects call free() for you
	 when they are destroyed.

	 Not calling free() will cause a program to leak connections.  This is
	 also not generally a problem, since free() is called automatically
	 whenever connection objects are destroyed.

	 Cancel	a connection that has not yet been established.	 Requires one
	 parameter, the	request	ID returned by allocate().

	 The keep-alive	pool requires connections to be	active internally.
	 This may keep a program active	even when all connections are idle.
	 The shutdown()	method forces the connection manager to	clear its
	 keep-alive pool, allowing a program to	terminate gracefully.


       POE POE::Component::Connection::Keepalive

       This distribution is copyright 2004-2009	by Rocco Caputo.  All rights
       are reserved.  This distribution	is free	software; you may redistribute
       it and/or modify	it under the same terms	as Perl	itself.

       Rocco Caputo <>

       Rob Bloodgood helped out	a lot.	Thank you.

       Joel Bernstein solved some nasty	race conditions.  Portugal Telecom
       <> was kind enough to	support	his contributions.




perl v5.32.0			  2014-07-POE::Component::Client::Keepalive(3)


Want to link to this manual page? Use this URL:

home | help