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);
  
  # 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);
  

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.

The basic usage pattern is to (1) create a client object, (2) declare some callbacks that will be executed when a response is received or an error occurs, and (3) issue HTTP::Request objects to the client.

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

Specified 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.

Callbacks

You may (err, should) 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.)

Issuing requests

Once you've established your callbacks, you can issue your requests via the request() method. request() takes an HTTP::Request object as the first argument, and a list of attribute-value pairs as the remaining arguments:

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

The request() method returns an object that can later be used to cancel the request. See "Canceling requests", below.

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.

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