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

FreeBSD Manual Pages

  
 
  

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

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

VERSION
       version 0.272

SYNOPSIS
	 use warnings;
	 use strict;

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

	 POE::Session->create(
	   inline_states => {
	     _start    => \&start,
	     got_conn  => \&got_conn,
	     got_error => \&handle_error,
	     got_input => \&handle_input,
	   }
	 );

	 POE::Kernel->run();
	 exit;

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

	   $_[HEAP]{ka}->allocate(
	     scheme  =>	"http",
	     addr    =>	"127.0.0.1",
	     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";
	     }

	     $conn->start(
	       InputEvent => "got_input",
	       ErrorEvent => "got_error",
	     );
	     return;
	   }

	   print(
	     "Connection could not be established: ",
	     "$response->{function} error $response->{error_num}: ",
	     "$response->{error_str}\n"
	   );
	 }

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

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

DESCRIPTION
       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.

       new
	 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
	 careful.

	 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,
	 use

	   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
	 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:

	   $mgr->allocate(
	     scheme   => "http",
	     address  => "127.0.0.1",
	     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
	 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.

	   $mgr->free($socket);

	 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.

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

       shutdown
	 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.

	   $mgr->shutdown();

SEE ALSO
       POE POE::Component::Connection::Keepalive

LICENSE
       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.

AUTHOR
       Rocco Caputo <rcaputo@cpan.org>

CONTRIBUTORS
       Rob Bloodgood helped out	a lot.	Thank you.

       Joel Bernstein solved some nasty	race conditions.  Portugal Telecom
       <http://www.sapo.pt/> was kind enough to	support	his contributions.

BUG TRACKER
       https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-Keepalive

REPOSITORY
       http://gitorious.org/poe-component-client-keepalive
       http://github.com/rcaputo/poe-component-client-keepalive

OTHER RESOURCES
       http://search.cpan.org/dist/POE-Component-Client-Keepalive/

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

NAME | VERSION | SYNOPSIS | DESCRIPTION | SEE ALSO | LICENSE | AUTHOR | CONTRIBUTORS | BUG TRACKER | REPOSITORY | OTHER RESOURCES

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

home | help