NAME

UniEvent::HTTP::Pool - HTTP client connections pool

SYNOPSIS

    my $pool = UE::HTTP::Pool->new({
        timeout => 5,
        max_connections => 20,
    });
    
    $pool->request({
        uri => "http://example.com",
        timeout => 3,
        response_callback => sub { ... },
    });
    
    UE::Loop->default->run;

DESCRIPTION

UniEvent::HTTP::Pool manages a number of http connections. Its primary goal is to utilize http keep-alive feature across http requests. It can also limit maximum number of simultaneous http requests to the same server.

When pool makes an http request and request is keep-alive, it doesn't close the connection when request is done. It will keep the connection alive for some time, and if new http request is started to the same destination with the same ssl and proxy settings, it will reuse that connection. If such a connection is idle for timeout time, pool will close it.

Pool may have several connections to the same destination. For example, if you start two keep-alive requests to the same destination simultaneously, it will create two connections and leave them both opened after requests are finished. If later you start three more simultaneous requests to the same destination, it will reuse two opened connections and create third connection. The maximum number of simultaneously opened connections to a certain server can be limited by max_connections parameter. If you start a new http request when max_connections connections to that server are already opened and busy (by other http requests), new request will be queued and executed later when one of the connections become free.

Different pool objects are isolated - they will not reuse connections from each other.

For conveniency, there are singleton global pool objects, one per event loop. They can be accessed directly as UE::HTTP::Pool::instance($loop) or indirectly via http_request(), http_get(), etc... functions which use global pool for provided event loop object. Global pools are created lazily on first use with default config.

When manually created pool object goes out of scope it will close all idle connections immediately. However all busy (active) connections will stay alive and all requests will be finished and their callbacks will be invoked. After that, all connections will be closed.

An http connection is represented by UniEvent::HTTP::Client object.

FUNCTIONS

instance([$loop = default])

Returns singleton pool object for a given UniEvent::Loop. Autocreates pool object if it doesn't already exist for the loop.

METHODS

new(\%config, [$loop = default])

Creates new pool with supplied config for a UniEvent::Loop.

%config includes:

timeout [=60]

Max idle time for a keep-alive connection. After timeout seconds of inactivity, a keep-alive connection will be closed. Can be fractional.

max_connections [=10]

Maximum number of simultaneous active http requests to a certain destination (host & port). If you start more than max_connections http requests to the same server at once, only max_connections of them will get executed immediately and the rest will wait until some of connections get free.

new([$loop = default])

Same as above with default config (config with default values).

loop()

Returns UniEvent::Loop object - the loop this pool runs in.

request($request || \%request_params)

Executes an http request. Argument can be a UniEvent::HTTP::Request object or params to its constructor.

Returns UniEvent::HTTP::Client http connection object which will run this request. However if max_connections for this destination is reached, request will be queued and will not run immediately, so in this case undef will be returned as it's not known at the moment which connection will run the request.

idle_timeout([$timeout])

Get/set keep-alive connection idle timeout. See new() for details.

max_connections([$count])

Get/set maximum number of simultaneous active http requests to a certain destination (host & port). See new() for details.

size()

Returns total number of http connections in the pool.

nbusy()

Returns total number of active(busy) http connections in the pool.

cpanm UniEvent::HTTP

perl -MCPAN -e shell
install UniEvent::HTTP