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

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 four 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 con-
         nection 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

       allocate
         Allocate a new connection.  Allocate() will return immediately.  The
         allocated connection, however, will be posted back to the requesting
         session.  This happens even if the connection was found in the compo-
         nent's keep-alive cache.

         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 connec-
         tion'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 sev-
         eral 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 suc-
         cessful, 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 imme-
         diately available from the cache.  It will be "deferred" if the con-
         nection 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::Connec-
         tion::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.

       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

BUGS
       http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-Client-Keepalive
       tracks the known issues with this component.  You can add to them by
       sending mail to bug-poe-component-client-keepalive@rt.cpan.org.

LICENSE
       This distribution is copyright 2004 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>

       Special thanks to Rob Bloodgood.
