NAME¶
POE::Component::Client::Keepalive - manage connections, with keep-alive
VERSION¶
version 0.271
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/