view release on metacpan or  search on metacpan

lib/AnyEvent/HTTP/LWP/UserAgent.pm  view on Meta::CPAN

sub request
{
    return shift->request_async(@_)->recv;
}

1;

__END__

=pod

=head1 NAME

AnyEvent::HTTP::LWP::UserAgent - LWP::UserAgent interface but works using AnyEvent::HTTP

=head1 VERSION

version 0.10

=head1 SYNOPSIS

  use AnyEvent::HTTP::LWP::UserAgent;
  use Coro;

  my $ua = AnyEvent::HTTP::LWP::UserAgent->new;
  my @urls = (...);
  my @coro = map {
      my $url = $_;
      async {
          my $r = $ua->get($url);
          print "url $url, content " . $r->content . "\n";
      }
  } @urls;
  $_->join for @coro;

  # Or without Coro
  use AnyEvent::HTTP::LWP::UserAgent;
  use AnyEvent;

  my $ua = AnyEvent::HTTP::LWP::UserAgent->new;
  my @urls = (...);
  my $cv = AE::cv;
  $cv->begin;
  foreach my $url (@urls) {
      $cv->begin;
      $ua->get_async($url)->cb(sub {
          my $r = shift->recv;
          print "url $url, content " . $r->content . "\n";
          $cv->end;
      });
  }
  $cv->end;
  $cv->recv;

=head1 DESCRIPTION

When you use Coro you have a choice: you can use L<Coro::LWP> or L<AnyEvent::HTTP>
(if you want to make asynchronous HTTP requests).
If you use Coro::LWP, some modules may work incorrectly (for example Cache::Memcached)
because of global change of IO::Socket behavior.
AnyEvent::HTTP uses different programming interface, so you must change more of your
old code with LWP::UserAgent (and HTTP::Request and so on), if you want to make
asynchronous code.

AnyEvent::HTTP::LWP::UserAgent uses AnyEvent::HTTP inside but have an interface of
LWP::UserAgent.
You can safely use this module in Coro environment (and possibly in AnyEvent too).

In plain AnyEvent, you may use _async methods.
They don't make blocking wait but return condition variable.
So, you can avoid recursive blocking wait error.

=head1 SOME METHODS

=over

=item $ua->conn_cache

=item $ua->conn_cache($cache_obj)

New versions of C<AnyEvent::HTTP> supports HTTP(S)/1.1 persistent connection, so
you can control it in C<AnyEvent::HTTP::LWP::UserAgent> using C<conn_cache> method.

If you set C<conn_cache> (as C<LWP::ConnCache> object) then
C<Anyevent::HTTP::LWP::UserAgent> makes two things. In first it sets global variable
C<$AnyEvent::HTTP::ACTIVE> as you setted C<total_capacity> for C<conn_cache> (be careful:
this have a global consequences, not local). And in the second C<AnyEvent::HTTP::LWP::UserAgent>
will create persistent connections if your C<$ua> have C<conn_cache> (local propery of C<$ua>).

But you can't use remainder methods of your C<conn_cache>, all connections will
contains in C<AnyEvent::HTTP>. C<$AnyEvent::HTTP::ACTIVE> sets only when you set
C<conn_cache> for C<$ua>. If you just change C<total_capacity> of old C<conn_cache>
it will not change anything.

=back

=head1 ASYNC METHODS

The following methods are async version of corresponding methods w/o _async suffix.
Parameters are identical as originals.
However, return value becomes condition variable.
You can use it in a synchronous way by blocking wait

  $ua->simple_request_async(@args)->recv

or in an asynchronous way, also.

  $ua->simple_request_async(@args)->cb(sub { ... });

=over 4

=item simple_request_async

=item request_async

=item get_async

=item post_async

=item head_async

=item put_async

=item delete_async

=back

=head1 LIMITATIONS AND DETAILS

Some features of LWP::UserAgent can be broken (C<protocols_forbidden> or something else).
Precise documentation and realization of these features will come in the future.

You can use some AnyEvent::HTTP global function and variables.
But use C<agent> of UA instead of C<$AnyEvent::HTTP::USERAGENT> and C<max_redirect>
instead of C<$AnyEvent::HTTP::MAX_RECURSE>.

Content in request can be specified by code reference.
This is the same as L<LWP::UserAgent> but there are some limitations.
L<LWP::UserAgent> uses chunked encoding if Content-Length is not specified,
while this module does NOT use chunked encoding even if Content-Length is not specified.

Content in response can be specified as filename or code reference.
This is the same as L<LWP::UserAgent>.

=head1 SEE ALSO

L<http://github.com/tadam/AnyEvent-HTTP-LWP-UserAgent>
L<Coro::LWP>
L<AnyEvent::HTTP>
L<LWP::Protocol::AnyEvent::http>
L<LWP::Protocol::Coro::http>

=head1 ACKNOWLEDGEMENTS

Yasutaka Atarashi

=head1 AUTHOR

Yury Zavarin <yury.zavarin@gmail.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Yury Zavarin.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut