.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Handle 3pm"
.TH Handle 3pm "2020-11-09" "perl v5.32.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::Handle \- non\-blocking I/O with a blocking interface.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Coro::Handle;
.Ve
.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 implements IO-handles in a coroutine-compatible way, that is,
other coroutines can run while reads or writes block on the handle.
.PP
It does so by using AnyEvent to wait for readable/writable
data, allowing other coroutines to run while one coroutine waits for I/O.
.PP
Coro::Handle does \s-1NOT\s0 inherit from IO::Handle but uses tied objects.
.PP
If at all possible, you should \fIalways\fR prefer method calls on the handle object over invoking
tied methods, i.e.:
.PP
.Vb 2
\&   $fh\->print ($str);         # NOT print $fh $str;
\&   my $line = $fh\->readline;  # NOT my $line = <$fh>;
.Ve
.PP
The reason is that perl recurses within the interpreter when invoking tie
magic, forcing the (temporary) allocation of a (big) stack. If you have
lots of socket connections and they happen to wait in e.g. <$fh>, then
they would all have a costly C coroutine associated with them.
.ie n .IP "$fh = new_from_fh Coro::Handle $fhandle [, arg => value...]" 4
.el .IP "\f(CW$fh\fR = new_from_fh Coro::Handle \f(CW$fhandle\fR [, arg => value...]" 4
.IX Item "$fh = new_from_fh Coro::Handle $fhandle [, arg => value...]"
Create a new non-blocking io-handle using the given
perl-filehandle. Returns \f(CW\*(C`undef\*(C'\fR if no filehandle is given. The only
other supported argument is \*(L"timeout\*(R", which sets a timeout for each
operation.
.ie n .IP "$fh = unblock $fh" 4
.el .IP "\f(CW$fh\fR = unblock \f(CW$fh\fR" 4
.IX Item "$fh = unblock $fh"
This is a convenience function that just calls \f(CW\*(C`new_from_fh\*(C'\fR on the
given filehandle. Use it to replace a normal perl filehandle by a
non\-(coroutine\-)blocking equivalent.
.ie n .IP "$fh\->writable, $fh\->readable" 4
.el .IP "\f(CW$fh\fR\->writable, \f(CW$fh\fR\->readable" 4
.IX Item "$fh->writable, $fh->readable"
Wait until the filehandle is readable or writable (and return true) or
until an error condition happens (and return false).
.ie n .IP "$fh\->readline ([$terminator])" 4
.el .IP "\f(CW$fh\fR\->readline ([$terminator])" 4
.IX Item "$fh->readline ([$terminator])"
Similar to the builtin of the same name, but allows you to specify the
input record separator in a coroutine-safe manner (i.e. not using a global
variable). Paragraph mode is not supported, use \*(L"\en\en\*(R" to achieve the same
effect.
.ie n .IP "$fh\->autoflush ([...])" 4
.el .IP "\f(CW$fh\fR\->autoflush ([...])" 4
.IX Item "$fh->autoflush ([...])"
Always returns true, arguments are being ignored (exists for compatibility
only). Might change in the future.
.ie n .IP "$fh\->fileno, $fh\->close, $fh\->read, $fh\->sysread, $fh\->syswrite, $fh\->print, $fh\->printf" 4
.el .IP "\f(CW$fh\fR\->fileno, \f(CW$fh\fR\->close, \f(CW$fh\fR\->read, \f(CW$fh\fR\->sysread, \f(CW$fh\fR\->syswrite, \f(CW$fh\fR\->print, \f(CW$fh\fR\->printf" 4
.IX Item "$fh->fileno, $fh->close, $fh->read, $fh->sysread, $fh->syswrite, $fh->print, $fh->printf"
Work like their function equivalents (except read, which works like
sysread. You should not use the read function with Coro::Handle's, it will
work but it's not efficient).
.IP "connect, listen, bind, getsockopt, setsockopt, send, recv, peername, sockname, shutdown, peerport, peerhost" 4
.IX Item "connect, listen, bind, getsockopt, setsockopt, send, recv, peername, sockname, shutdown, peerport, peerhost"
Do the same thing as the perl builtins or IO::Socket methods (but return
true on \s-1EINPROGRESS\s0). Remember that these must be method calls.
.IP "peeraddr, peerhost, peerport" 4
.IX Item "peeraddr, peerhost, peerport"
Return the peer host (as numericla \s-1IP\s0 address) and peer port (as integer).
.ie n .IP "($fh, $peername) = $listen_fh\->accept" 4
.el .IP "($fh, \f(CW$peername\fR) = \f(CW$listen_fh\fR\->accept" 4
.IX Item "($fh, $peername) = $listen_fh->accept"
In scalar context, returns the newly accepted socket (or undef) and in
list context return the ($fh, \f(CW$peername\fR) pair (or nothing).
.ie n .IP "$fh\->timeout ([...])" 4
.el .IP "\f(CW$fh\fR\->timeout ([...])" 4
.IX Item "$fh->timeout ([...])"
The optional argument sets the new timeout (in seconds) for this
handle. Returns the current (new) value.
.Sp
\&\f(CW0\fR is a valid timeout, use \f(CW\*(C`undef\*(C'\fR to disable the timeout.
.ie n .IP "$fh\->fh" 4
.el .IP "\f(CW$fh\fR\->fh" 4
.IX Item "$fh->fh"
Returns the \*(L"real\*(R" (non-blocking) filehandle. Use this if you want to
do operations on the file handle you cannot do using the Coro::Handle
interface.
.ie n .IP "$fh\->rbuf" 4
.el .IP "\f(CW$fh\fR\->rbuf" 4
.IX Item "$fh->rbuf"
Returns the current contents of the read buffer (this is an lvalue, so you
can change the read buffer if you like).
.Sp
You can use this function to implement your own optimized reader when neither
readline nor sysread are viable candidates, like this:
.Sp
.Vb 4
\&  # first get the _real_ non\-blocking filehandle
\&  # and fetch a reference to the read buffer
\&  my $nb_fh = $fh\->fh;
\&  my $buf = \e$fh\->rbuf;
\&
\&  while () {
\&     # now use buffer contents, modifying
\&     # if necessary to reflect the removed data
\&
\&     last if $$buf ne ""; # we have leftover data
\&
\&     # read another buffer full of data
\&     $fh\->readable or die "end of file";
\&     sysread $nb_fh, $$buf, 8192;
\&  }
.Ve
.SH "BUGS"
.IX Header "BUGS"
.Vb 1
\& \- Perl\*(Aqs IO\-Handle model is THE bug.
.Ve
.SH "AUTHOR/SUPPORT/CONTACT"
.IX Header "AUTHOR/SUPPORT/CONTACT"
.Vb 2
\&   Marc A. Lehmann <schmorp@schmorp.de>
\&   http://software.schmorp.de/pkg/Coro.html
.Ve