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.48;

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";

      _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.87
Committed:	Sun Oct 4 13:10:22 2015 UTC (8 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-6_48
Changes since 1.86:	+1 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.19	Coro::AIO - truly asynchronous file and directory I/O
4	root	1.1
5			=head1 SYNOPSIS
6
7			use Coro::AIO;
8
9	root	1.4	# can now use any of the aio requests your IO::AIO module supports.
10	root	1.1
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	root	1.16	This module is an L<AnyEvent> user, you need to make sure that you use and
21			run a supported event loop.
22
23	root	1.18	This module implements a thin wrapper around L<IO::AIO>. All of
24	root	1.2	the functions that expect a callback are being wrapped by this module.
25	root	1.1
26	root	1.49	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	root	1.3	callback. Everything else, including C<$!> and perls stat cache, are set
31			as expected after these functions return.
32	root	1.1
33			You can mix calls to C<IO::AIO> functions with calls to this module. You
34	root	1.3	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	root	1.18	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	root	1.1
41	root	1.5	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	root	1.30	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	root	1.12
51	root	1.30	For your convenience, here are the changed function signatures for most
52	root	1.5	of the requests, for documentation of these functions please have a look
53	root	1.17	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	root	1.7
56	root	1.1	=over 4
57
58			=cut
59
60			package Coro::AIO;
61
62	root	1.44	use common::sense;
63	root	1.2
64	root	1.22	use IO::AIO 3.1 ();
65			use AnyEvent::AIO ();
66
67	root	1.1	use Coro ();
68	root	1.22	use Coro::AnyEvent ();
69	root	1.1
70			use base Exporter::;
71
72	root	1.87	our $VERSION = 6.48;
73	root	1.20
74	root	1.22	our @EXPORT = (@IO::AIO::EXPORT, qw(aio_wait));
75	root	1.5	our @EXPORT_OK = @IO::AIO::EXPORT_OK;
76			our $AUTOLOAD;
77
78			{
79	root	1.22	my @reqs = @IO::AIO::AIO_REQ ? @IO::AIO::AIO_REQ : @IO::AIO::EXPORT;
80	root	1.5	my %reqs = map +($_ => 1), @reqs;
81
82			eval
83			join "",
84			map "sub $_(" . (prototype "IO::AIO::$_") . ");",
85			grep !$reqs{$_},
86	root	1.22	@IO::AIO::EXPORT, @EXPORT_OK;
87	root	1.1
88	root	1.5	for my $sub (@reqs) {
89			push @EXPORT, $sub;
90	root	1.30
91	root	1.5	my $iosub = "IO::AIO::$sub";
92			my $proto = prototype $iosub;
93	root	1.2
94	root	1.50	$proto =~ s/;//g; # we do not support optional arguments
95	root	1.52	$proto =~ s/^(\$*)\$$/$1/ or die "$iosub($proto): unable to remove callback slot from prototype";
96	root	1.1
97	root	1.30	_register "Coro::AIO::$sub", $proto, \&{$iosub};
98	root	1.5	}
99	root	1.30
100			_register "Coro::AIO::aio_wait", '$', \&IO::AIO::REQ::cb;
101	root	1.1	}
102
103	root	1.5	sub AUTOLOAD {
104			(my $func = $AUTOLOAD) =~ s/^.*:://;
105			*$AUTOLOAD = \&{"IO::AIO::$func"};
106			goto &$AUTOLOAD;
107			}
108	root	1.1
109	root	1.22	=item @results = aio_wait $req
110
111			This is not originally an IO::AIO request: what it does is to wait for
112			C<$req> to finish and return the results. This is most useful with
113			C<aio_group> requests.
114
115	root	1.30	Is currently implemented by replacing the C<$req> callback (and is very
116			much like a wrapper around C<< $req->cb () >>).
117	root	1.22
118	root	1.1	=item $fh = aio_open $pathname, $flags, $mode
119
120			=item $status = aio_close $fh
121
122			=item $retval = aio_read $fh,$offset,$length, $data,$dataoffset
123
124			=item $retval = aio_write $fh,$offset,$length, $data,$dataoffset
125
126			=item $retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length
127
128			=item $retval = aio_readahead $fh,$offset,$length
129
130	root	1.2	=item $status = aio_stat $fh_or_path
131
132			=item $status = aio_lstat $fh
133
134	root	1.1	=item $status = aio_unlink $pathname
135
136			=item $status = aio_rmdir $pathname
137
138	root	1.3	=item $entries = aio_readdir $pathname
139	root	1.1
140			=item ($dirs, $nondirs) = aio_scandir $path, $maxreq
141
142			=item $status = aio_fsync $fh
143
144			=item $status = aio_fdatasync $fh
145
146	root	1.4	=item ... = aio_xxx ...
147
148			Any additional aio requests follow the same scheme: same parameters except
149			you must not specify a callback but instead get the callback arguments as
150			return values.
151
152	root	1.1	=back
153
154	root	1.2	=head1 SEE ALSO
155
156	root	1.4	L<Coro::Socket> and L<Coro::Handle> for non-blocking socket operation.
157	root	1.2
158	root	1.82	=head1 AUTHOR/SUPPORT/CONTACT
159	root	1.1
160	root	1.82	Marc A. Lehmann <schmorp@schmorp.de>
161			http://software.schmorp.de/pkg/Coro.html
162	root	1.1
163			=cut
164
165			1