.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LWP 3pm"
.TH LWP 3pm "2014-09-06" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Coro::LWP \- make LWP non\-blocking \- as much as possible
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Coro::LWP; # afterwards LWP should not block
.Ve
.SH "ALTERNATIVES"
.IX Header "ALTERNATIVES"
Over the years, a number of less-invasive alternatives have popped up,
which you might find more acceptable than this rather invasive and fragile
module. All of them only support \s-1HTTP \s0(and sometimes \s-1HTTPS\s0).
.IP "AnyEvent::HTTP" 4
.IX Item "AnyEvent::HTTP"
Works fine without Coro. Requires using a very different \s-1API\s0 than
\&\s-1LWP.\s0 Probably the best choice \fIiff\fR you can do with a completely
different event-based \s-1API.\s0
.IP "LWP::Protocol::AnyEvent::http" 4
.IX Item "LWP::Protocol::AnyEvent::http"
Makes \s-1LWP\s0 use AnyEvent::HTTP. Does not make \s-1LWP\s0 event-based, but allows
Coro threads to schedule unimpeded through its AnyEvent integration.
.Sp
Let's you use the \s-1LWP API\s0 normally.
.IP "LWP::Protocol::Coro::http" 4
.IX Item "LWP::Protocol::Coro::http"
Basically the same as above, distinction unclear. :)
.IP "AnyEvent::HTTP::LWP::UserAgent" 4
.IX Item "AnyEvent::HTTP::LWP::UserAgent"
A different user agent implementation, not completely transparent to
users, requires Coro.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is an AnyEvent user, you need to make sure that you use and
run a supported event loop.
.PP
This module tries to make \s-1LWP\s0 non-blocking with respect to other
coroutines as much as possible, and with whatever means it takes.
.PP
\&\s-1LWP\s0 really tries very hard to be blocking (and relies on a lot of
undocumented functionality in IO::Socket), so this module had to be very
invasive and must be loaded very early to take the proper effect.
.PP
Note that the module AnyEvent::HTTP might offer an alternative to the
full \s-1LWP\s0 that is designed to be non-blocking.
.PP
Here is what it currently does (future versions of \s-1LWP\s0 might require
different tricks):
.ie n .IP "It loads Coro::Select, overwriting the perl ""select"" builtin \fIglobally\fR." 4
.el .IP "It loads Coro::Select, overwriting the perl \f(CWselect\fR builtin \fIglobally\fR." 4
.IX Item "It loads Coro::Select, overwriting the perl select builtin globally."
This is necessary because \s-1LWP\s0 calls select quite often for timeouts and
who-knows-what.
.Sp
Impact: everybody else uses this (slower) version of select, too. It should be quite
compatible to perls builtin select, though.
.IP "It overwrites Socket::inet_aton with Coro::Util::inet_aton." 4
.IX Item "It overwrites Socket::inet_aton with Coro::Util::inet_aton."
This is necessary because \s-1LWP\s0 might (and does) try to resolve hostnames
this way.
.Sp
Impact: some code might not expect coroutine semantics, for example, when
you fork you might prefer the blocking variant because other coroutines
shouldn't actually run.
.IP "It replaces the base class of Net::HTTP, Net::FTP, Net::NNTP." 4
.IX Item "It replaces the base class of Net::HTTP, Net::FTP, Net::NNTP."
This is necessary because \s-1LWP\s0 does not always use select to see whether
a filehandle can be read/written without blocking, so the base class
\&\f(CW\*(C`IO::Socket::INET\*(C'\fR needs to be replaced by \f(CW\*(C`Coro::Socket\*(C'\fR.
.Sp
Impact: Coro::Socket is not at all compatible to IO::Socket::INET. While
it duplicates some undocumented functionality required by \s-1LWP,\s0 it does not
have all the methods of IO::Socket::INET and might act quite differently
in practise. Also, protocols other than the above mentioned will still block,
at least some of the time.
.PP
All this likely makes other libraries than just \s-1LWP\s0 not block, but thats
just a side effect you cannot rely on.
.PP
Increases parallelism is not supported by all libraries, some might cache
data globally.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\& Marc Lehmann <schmorp@schmorp.de>
\& http://home.schmorp.de/
.Ve