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

VERSION
    version 0.269

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-Keepali
    ve

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/

