NAME

AnyEvent::Curl::Multi - a fast event-driven HTTP client

SYNOPSIS

  use AnyEvent;
  use AnyEvent::Curl::Multi;
  
  my $client = AnyEvent::Curl::Multi->new;
  $client->max_concurrency(10);

  # Method 1: Object::Event pattern
  #
  # Schedule callbacks to be fired when a response is received,
  # or when an error occurs.
  $client->reg_cb(response => sub {
      my ($client, $request, $response, $stats) = @_;
      # $response is an HTTP::Request object
  });
  $client->reg_cb(error => sub {
      my ($client, $request, $errmsg, $stats) = @_;
      # ...
  });
  my $request = HTTP::Request->new(...);
  $client->request($request);

  # Method 2: AnyEvent::CondVar pattern
  # Do not use this pattern in an existing event loop!
  my $handle = $client->request($request);
  eval {
      my ($response, $stats) = $handle->cv->recv;
      # $response is an HTTP::Request object
      # ...
  }; 
  if ($@) {
      my $errmsg = $@;
      # ...
  }
  

DESCRIPTION

This module is an AnyEvent user; you must use and run a supported event loop.

AnyEvent::Curl::Multi is an asynchronous, event-driven HTTP client. You can use it to make multiple HTTP requests in parallel using a single process. It uses libcurl for fast performance.

Initializing the client

 my $client = AnyEvent::Curl::Multi->new;

You can specify the maximum number of concurrent requests by setting max_concurrency, e.g.:

 my $client = AnyEvent::Curl::Multi->new(max_concurrency => 10);

You can also set the maximum concurrency after the client has been created:

 $client->max_concurrency(10);

A value of 0 means no limit will be imposed.

You can also set global default behaviors for requests:

timeout => PERIOD

Specifies a timeout for each request. If your WWW::Curl is linked against libcurl 7.16.2 or later, this value can be specified in fractional seconds (ms resolution). Otherwise, the value must be specified in whole seconds.

proxy => HOST[:PORT]

Specifies a proxy host/port, separated by a colon. (The port number is optional.)

max_redirects => COUNT

Specifies the maximum number of HTTP redirects that will be followed. Set to 0 to disable following redirects.

ipresolve => 4 | 6

Specifies which kind of IP address to select when resolving host names. This is only useful when using host names that resolve to both IPv4 and IPv6 addresses. The allowed values are 4 (IPv4) or 6 (IPv6). The default is to resolve to all addresses.

Issuing requests

To dispatch HTTP requests to the client, use the request() method. request() takes an HTTP::Request object as the first argument, and a list of attribute-value pairs as the remaining arguments:

  $handle = $client->request($request, ...);

The following attributes are accepted:

timeout => PERIOD

Specified a timeout for the request. If your WWW::Curl is linked against libcurl 7.16.2 or later, this value can be specified in fractional seconds (ms resolution). Otherwise, the value must be specified in whole seconds.

proxy => HOST[:PORT]

Specifies a proxy host/port, separated by a colon. (The port number is optional.)

max_redirects => COUNT

Specifies the maximum number of HTTP redirects that will be followed. Set to 0 to disable following redirects.

The request() method returns an object of class AnyEvent::Curl::Multi::Handle. This object can be used later to cancel the request; see "Canceling requests", below.

Calling $handle->cv() will return an AnyEvent condvar that you can use as usual (e.g., recv() or cb()) to retrieve response results, or that will croak if an error occurs. See AnyEvent for details on condvars.

Callbacks

Instead of using condvars, you may register interest in the following events using the client's reg_cb() method (see Object::Event for more details on reg_cb()):

response => $cb->($client, $request, $response, $stats);

Fired when a response is received. (This doesn't imply that the response is HTTP OK, so you should examine the response to determine whether there was an HTTP error of some sort.)

The arguments sent to your callback will be the client object, the original request (untampered with), the response (as an HTTP::Response object), and a hashref containing some interesting statistics.

error => $cb->($client, $request, $errmsg, $stats);

Fired when an error is received.

The arguments sent to your callback will be the client object, the original request (untampered with), the error message, and a hashref containing some interesting statistics. (If the error was other than a timeout, the statistics may be invalid.)

Canceling requests

To cancel a request, use the cancel() method:

  my $handle = $client->request(...);

  # Later...
  $client->cancel($handle);

NOTES

libcurl 7.21 or higher is recommended. There are some bugs in prior versions pertaining to host resolution and accurate timeouts. In addition, subsecond timeouts were not available prior to version 7.16.2.

libcurl should be compiled with c-ares support. Otherwise, the DNS resolution phase that occurs at the beginning of each request will block your program, which could significantly compromise its concurrency. (You can verify whether your libcurl has been built with c-ares support by running curl -V and looking for "AsynchDNS" in the features list.)

libcurl's internal hostname resolution cache is disabled by this module (among other problems, it does not honor DNS TTL values). If you need fast hostname resolution, consider installing and configuring a local DNS cache such as BIND or dnscache (part of djbdns).

SSL peer verification is disabled. If you consider this a serious problem, please contact the author.

SEE ALSO

AnyEvent, AnyEvent::Handle, Object::Event, HTTP::Request, HTTP::Response

AUTHORS AND CONTRIBUTORS

Michael S. Fischer (michael+cpan@dynamine.net) released the original version and is the current maintainer.

COPYRIGHT AND LICENSE

(C) 2010-2011 Michael S. Fischer. (C) 2010-2011 Yahoo! Inc.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm AnyEvent::Curl::Multi

perl -MCPAN -e shell
install AnyEvent::Curl::Multi