Coro/Coro/AIO.pm

=head1 NAME

Coro::AIO - truly asynchronous file and directory I/O

=head1 SYNOPSIS

   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;

=head1 DESCRIPTION

This module is an L<AnyEvent> user, you need to make sure that you use and
run a supported event loop.

This module implements a thin wrapper around L<IO::AIO>. All of
the functions that expect a callback are being wrapped by this module.

The API is exactly the same as that of the corresponding IO::AIO
routines, except that you have to specify I<all> arguments, even the
ones optional in IO::AIO, I<except> the callback argument. Instead of
calling a callback, the routines return the values normally passed to the
callback. Everything else, including C<$!> and perls stat cache, are set
as expected after these functions return.

You can mix calls to C<IO::AIO> functions with calls to this module. You
I<must not>, however, call these routines from within IO::AIO callbacks,
as this causes a deadlock. Start a coro inside the callback instead.

This module also loads L<AnyEvent::AIO> to integrate into the event loop
in use, so please refer to its (and L<AnyEvent>'s) documentation on how it
selects an appropriate event module.

All other functions exported by default by IO::AIO (e.g. C<aioreq_pri>)
will be exported by default by Coro::AIO, too.

Functions that can be optionally imported from IO::AIO can be imported
from Coro::AIO or can be called directly, e.g. C<Coro::AIO::nreqs>.

You cannot specify priorities with C<aioreq_pri> if your coroutine has a
non-zero priority, as this module overwrites the request priority with the
current coroutine priority in that case.

For your convenience, here are the changed function signatures for most
of the requests, for documentation of these functions please have a look
at L<IO::AIO|the IO::AIO manual>. Note that requests added by newer
versions of L<IO::AIO> will be automatically wrapped as well.

=over 4

=cut

package Coro::AIO;

use common::sense;

use IO::AIO 3.1 ();
use AnyEvent::AIO ();

use Coro ();
use Coro::AnyEvent ();

use base Exporter::;

our $VERSION = 6.57;

our @EXPORT    = (@IO::AIO::EXPORT, qw(aio_wait));
our @EXPORT_OK = @IO::AIO::EXPORT_OK;
our $AUTOLOAD;

{
   my @reqs = @IO::AIO::AIO_REQ ? @IO::AIO::AIO_REQ : @IO::AIO::EXPORT;
   my %reqs = map +($_ => 1), @reqs;

   eval
      join "",
         map "sub $_(" . (prototype "IO::AIO::$_") . ");",
            grep !$reqs{$_},
                @IO::AIO::EXPORT, @EXPORT_OK;

   for my $sub (@reqs) {
      push @EXPORT, $sub;

      my $iosub = "IO::AIO::$sub";
      my $proto = prototype $iosub;

      $proto =~ s/;//g; # we do not support optional arguments
      $proto =~ s/^(\$*)\$$/$1/ or die "$iosub($proto): unable to remove callback slot from prototype";

      # we add ; to avoid generating "$" which is specialcased to mean named unary function
      # without this, Coro::AIO::aio_mlockall IO::AIO::MCL_CURRENT | IO::AIO::MCL_FUTURE
      # is parsed as (Coro::AIO::aio_mlockall IO::AIO::MCL_CURRENT) | IO::AIO::MCL_FUTURE.
      $proto .= ";";

      _register "Coro::AIO::$sub", $proto, \&{$iosub};
   }

   _register "Coro::AIO::aio_wait", '$', \&IO::AIO::REQ::cb;
}

sub AUTOLOAD {
   (my $func = $AUTOLOAD) =~ s/^.*:://;
   *$AUTOLOAD = \&{"IO::AIO::$func"};
   goto &$AUTOLOAD;
}

=item @results = aio_wait $req

This is not originally an IO::AIO request: what it does is to wait for
C<$req> to finish and return the results. This is most useful with
C<aio_group> requests.

Is currently implemented by replacing the C<$req> callback (and is very
much like a wrapper around C<< $req->cb () >>).

=item $fh = aio_open $pathname, $flags, $mode

=item $status = aio_close $fh

=item $retval = aio_read  $fh,$offset,$length, $data,$dataoffset

=item $retval = aio_write $fh,$offset,$length, $data,$dataoffset

=item $retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length

=item $retval = aio_readahead $fh,$offset,$length

=item $status = aio_stat $fh_or_path
      
=item $status = aio_lstat $fh

=item $status = aio_unlink $pathname

=item $status = aio_rmdir $pathname

=item $entries = aio_readdir $pathname

=item ($dirs, $nondirs) = aio_scandir $path, $maxreq

=item $status = aio_fsync $fh

=item $status = aio_fdatasync $fh

=item ... = aio_xxx ...

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.

=back

=head1 SEE ALSO

L<Coro::Socket> and L<Coro::Handle> for non-blocking socket operation.

=head1 AUTHOR/SUPPORT/CONTACT

   Marc A. Lehmann <schmorp@schmorp.de>
   http://software.schmorp.de/pkg/Coro.html

=cut

1
Revision:	1.102
Committed:	Mon Mar 16 11:12:52 2020 UTC (4 years, 2 months ago) by root
Branch:	MAIN
CVS Tags:	rel-6_57, HEAD
Changes since 1.101:	+1 -1 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	Coro::AIO - truly asynchronous file and directory I/O
4
5	=head1 SYNOPSIS
6
7	use Coro::AIO;
8
9	# can now use any of the aio requests your IO::AIO module supports.
10
11	# read 1MB of /etc/passwd, without blocking other coroutines
12	my $fh = aio_open "/etc/passwd", O_RDONLY, 0
13	or die "/etc/passwd: $!";
14	aio_read $fh, 0, 1_000_000, my $buf, 0
15	or die "aio_read: $!";
16	aio_close $fh;
17
18	=head1 DESCRIPTION
19
20	This module is an L<AnyEvent> user, you need to make sure that you use and
21	run a supported event loop.
22
23	This module implements a thin wrapper around L<IO::AIO>. All of
24	the functions that expect a callback are being wrapped by this module.
25
26	The API is exactly the same as that of the corresponding IO::AIO
27	routines, except that you have to specify I<all> arguments, even the
28	ones optional in IO::AIO, I<except> the callback argument. Instead of
29	calling a callback, the routines return the values normally passed to the
30	callback. Everything else, including C<$!> and perls stat cache, are set
31	as expected after these functions return.
32
33	You can mix calls to C<IO::AIO> functions with calls to this module. You
34	I<must not>, however, call these routines from within IO::AIO callbacks,
35	as this causes a deadlock. Start a coro inside the callback instead.
36
37	This module also loads L<AnyEvent::AIO> to integrate into the event loop
38	in use, so please refer to its (and L<AnyEvent>'s) documentation on how it
39	selects an appropriate event module.
40
41	All other functions exported by default by IO::AIO (e.g. C<aioreq_pri>)
42	will be exported by default by Coro::AIO, too.
43
44	Functions that can be optionally imported from IO::AIO can be imported
45	from Coro::AIO or can be called directly, e.g. C<Coro::AIO::nreqs>.
46
47	You cannot specify priorities with C<aioreq_pri> if your coroutine has a
48	non-zero priority, as this module overwrites the request priority with the
49	current coroutine priority in that case.
50
51	For your convenience, here are the changed function signatures for most
52	of the requests, for documentation of these functions please have a look
53	at L<IO::AIO\|the IO::AIO manual>. Note that requests added by newer
54	versions of L<IO::AIO> will be automatically wrapped as well.
55
56	=over 4
57
58	=cut
59
60	package Coro::AIO;
61
62	use common::sense;
63
64	use IO::AIO 3.1 ();
65	use AnyEvent::AIO ();
66
67	use Coro ();
68	use Coro::AnyEvent ();
69
70	use base Exporter::;
71
72	our $VERSION = 6.57;
73
74	our @EXPORT = (@IO::AIO::EXPORT, qw(aio_wait));
75	our @EXPORT_OK = @IO::AIO::EXPORT_OK;
76	our $AUTOLOAD;
77
78	{
79	my @reqs = @IO::AIO::AIO_REQ ? @IO::AIO::AIO_REQ : @IO::AIO::EXPORT;
80	my %reqs = map +($_ => 1), @reqs;
81
82	eval
83	join "",
84	map "sub $_(" . (prototype "IO::AIO::$_") . ");",
85	grep !$reqs{$_},
86	@IO::AIO::EXPORT, @EXPORT_OK;
87
88	for my $sub (@reqs) {
89	push @EXPORT, $sub;
90
91	my $iosub = "IO::AIO::$sub";
92	my $proto = prototype $iosub;
93
94	$proto =~ s/;//g; # we do not support optional arguments
95	$proto =~ s/^(\$*)\$$/$1/ or die "$iosub($proto): unable to remove callback slot from prototype";
96
97	# we add ; to avoid generating "$" which is specialcased to mean named unary function
98	# without this, Coro::AIO::aio_mlockall IO::AIO::MCL_CURRENT \| IO::AIO::MCL_FUTURE
99	# is parsed as (Coro::AIO::aio_mlockall IO::AIO::MCL_CURRENT) \| IO::AIO::MCL_FUTURE.
100	$proto .= ";";
101
102	_register "Coro::AIO::$sub", $proto, \&{$iosub};
103	}
104
105	_register "Coro::AIO::aio_wait", '$', \&IO::AIO::REQ::cb;
106	}
107
108	sub AUTOLOAD {
109	(my $func = $AUTOLOAD) =~ s/^.*:://;
110	*$AUTOLOAD = \&{"IO::AIO::$func"};
111	goto &$AUTOLOAD;
112	}
113
114	=item @results = aio_wait $req
115
116	This is not originally an IO::AIO request: what it does is to wait for
117	C<$req> to finish and return the results. This is most useful with
118	C<aio_group> requests.
119
120	Is currently implemented by replacing the C<$req> callback (and is very
121	much like a wrapper around C<< $req->cb () >>).
122
123	=item $fh = aio_open $pathname, $flags, $mode
124
125	=item $status = aio_close $fh
126
127	=item $retval = aio_read $fh,$offset,$length, $data,$dataoffset
128
129	=item $retval = aio_write $fh,$offset,$length, $data,$dataoffset
130
131	=item $retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length
132
133	=item $retval = aio_readahead $fh,$offset,$length
134
135	=item $status = aio_stat $fh_or_path
136
137	=item $status = aio_lstat $fh
138
139	=item $status = aio_unlink $pathname
140
141	=item $status = aio_rmdir $pathname
142
143	=item $entries = aio_readdir $pathname
144
145	=item ($dirs, $nondirs) = aio_scandir $path, $maxreq
146
147	=item $status = aio_fsync $fh
148
149	=item $status = aio_fdatasync $fh
150
151	=item ... = aio_xxx ...
152
153	Any additional aio requests follow the same scheme: same parameters except
154	you must not specify a callback but instead get the callback arguments as
155	return values.
156
157	=back
158
159	=head1 SEE ALSO
160
161	L<Coro::Socket> and L<Coro::Handle> for non-blocking socket operation.
162
163	=head1 AUTHOR/SUPPORT/CONTACT
164
165	Marc A. Lehmann <schmorp@schmorp.de>
166	http://software.schmorp.de/pkg/Coro.html
167
168	=cut
169
170	1