.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "AIO 3pm"
.TH AIO 3pm 2024-01-11 "perl v5.38.2" "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::AIO \- truly asynchronous file and directory I/O
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&   use Coro::AIO;
\&
\&   # can now use any of the aio requests your IO::AIO module supports.
\&
\&   # read 1MB of /etc/passwd, without blocking other coroutines
\&   my $fh = aio_open "/etc/passwd", O_RDONLY, 0
\&      or die "/etc/passwd: $!";
\&   aio_read $fh, 0, 1_000_000, my $buf, 0
\&      or die "aio_read: $!";
\&   aio_close $fh;
.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 a thin wrapper around IO::AIO. All of
the functions that expect a callback are being wrapped by this module.
.PP
The API is exactly the same as that of the corresponding IO::AIO
routines, except that you have to specify \fIall\fR arguments, even the
ones optional in IO::AIO, \fIexcept\fR the callback argument. Instead of
calling a callback, the routines return the values normally passed to the
callback. Everything else, including \f(CW$!\fR and perls stat cache, are set
as expected after these functions return.
.PP
You can mix calls to \f(CW\*(C`IO::AIO\*(C'\fR functions with calls to this module. You
\&\fImust not\fR, however, call these routines from within IO::AIO callbacks,
as this causes a deadlock. Start a coro inside the callback instead.
.PP
This module also loads AnyEvent::AIO to integrate into the event loop
in use, so please refer to its (and AnyEvent's) documentation on how it
selects an appropriate event module.
.PP
All other functions exported by default by IO::AIO (e.g. \f(CW\*(C`aioreq_pri\*(C'\fR)
will be exported by default by Coro::AIO, too.
.PP
Functions that can be optionally imported from IO::AIO can be imported
from Coro::AIO or can be called directly, e.g. \f(CW\*(C`Coro::AIO::nreqs\*(C'\fR.
.PP
You cannot specify priorities with \f(CW\*(C`aioreq_pri\*(C'\fR if your coroutine has a
non-zero priority, as this module overwrites the request priority with the
current coroutine priority in that case.
.PP
For your convenience, here are the changed function signatures for most
of the requests, for documentation of these functions please have a look
at IO::AIO. Note that requests added by newer
versions of IO::AIO will be automatically wrapped as well.
.ie n .IP "@results = aio_wait $req" 4
.el .IP "\f(CW@results\fR = aio_wait \f(CW$req\fR" 4
.IX Item "@results = aio_wait $req"
This is not originally an IO::AIO request: what it does is to wait for
\&\f(CW$req\fR to finish and return the results. This is most useful with
\&\f(CW\*(C`aio_group\*(C'\fR requests.
.Sp
Is currently implemented by replacing the \f(CW$req\fR callback (and is very
much like a wrapper around \f(CW\*(C`$req\->cb ()\*(C'\fR).
.ie n .IP "$fh = aio_open $pathname, $flags, $mode" 4
.el .IP "\f(CW$fh\fR = aio_open \f(CW$pathname\fR, \f(CW$flags\fR, \f(CW$mode\fR" 4
.IX Item "$fh = aio_open $pathname, $flags, $mode"
.PD 0
.ie n .IP "$status = aio_close $fh" 4
.el .IP "\f(CW$status\fR = aio_close \f(CW$fh\fR" 4
.IX Item "$status = aio_close $fh"
.ie n .IP "$retval = aio_read  $fh,$offset,$length, $data,$dataoffset" 4
.el .IP "\f(CW$retval\fR = aio_read  \f(CW$fh\fR,$offset,$length, \f(CW$data\fR,$dataoffset" 4
.IX Item "$retval = aio_read $fh,$offset,$length, $data,$dataoffset"
.ie n .IP "$retval = aio_write $fh,$offset,$length, $data,$dataoffset" 4
.el .IP "\f(CW$retval\fR = aio_write \f(CW$fh\fR,$offset,$length, \f(CW$data\fR,$dataoffset" 4
.IX Item "$retval = aio_write $fh,$offset,$length, $data,$dataoffset"
.ie n .IP "$retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length" 4
.el .IP "\f(CW$retval\fR = aio_sendfile \f(CW$out_fh\fR, \f(CW$in_fh\fR, \f(CW$in_offset\fR, \f(CW$length\fR" 4
.IX Item "$retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length"
.ie n .IP "$retval = aio_readahead $fh,$offset,$length" 4
.el .IP "\f(CW$retval\fR = aio_readahead \f(CW$fh\fR,$offset,$length" 4
.IX Item "$retval = aio_readahead $fh,$offset,$length"
.ie n .IP "$status = aio_stat $fh_or_path" 4
.el .IP "\f(CW$status\fR = aio_stat \f(CW$fh_or_path\fR" 4
.IX Item "$status = aio_stat $fh_or_path"
.ie n .IP "$status = aio_lstat $fh" 4
.el .IP "\f(CW$status\fR = aio_lstat \f(CW$fh\fR" 4
.IX Item "$status = aio_lstat $fh"
.ie n .IP "$status = aio_unlink $pathname" 4
.el .IP "\f(CW$status\fR = aio_unlink \f(CW$pathname\fR" 4
.IX Item "$status = aio_unlink $pathname"
.ie n .IP "$status = aio_rmdir $pathname" 4
.el .IP "\f(CW$status\fR = aio_rmdir \f(CW$pathname\fR" 4
.IX Item "$status = aio_rmdir $pathname"
.ie n .IP "$entries = aio_readdir $pathname" 4
.el .IP "\f(CW$entries\fR = aio_readdir \f(CW$pathname\fR" 4
.IX Item "$entries = aio_readdir $pathname"
.ie n .IP "($dirs, $nondirs) = aio_scandir $path, $maxreq" 4
.el .IP "($dirs, \f(CW$nondirs\fR) = aio_scandir \f(CW$path\fR, \f(CW$maxreq\fR" 4
.IX Item "($dirs, $nondirs) = aio_scandir $path, $maxreq"
.ie n .IP "$status = aio_fsync $fh" 4
.el .IP "\f(CW$status\fR = aio_fsync \f(CW$fh\fR" 4
.IX Item "$status = aio_fsync $fh"
.ie n .IP "$status = aio_fdatasync $fh" 4
.el .IP "\f(CW$status\fR = aio_fdatasync \f(CW$fh\fR" 4
.IX Item "$status = aio_fdatasync $fh"
.IP "... = aio_xxx ..." 4
.IX Item "... = aio_xxx ..."
.PD
Any additional aio requests follow the same scheme: same parameters except
you must not specify a callback but instead get the callback arguments as
return values.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Coro::Socket and Coro::Handle for non-blocking socket operation.
.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