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 I<except> the callback
argument. Instead 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>, as this module
overwrites the request priority with the current coroutine priority at all
times.

For your convienience, 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 strict qw(subs vars);

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

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

use base Exporter::;

our $VERSION = 4.802;

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/;?\$$// or die "$iosub: unable to remove callback slot from prototype";

      eval qq{
#line 1 "Coro::AIO::$sub($proto)"
         sub $sub($proto) {
            my (\$current, \$state) = \$Coro::current;

            push \@_, sub {
               \$state = _get_state \$current;
            };

            aioreq_pri \$Coro::current->prio;
            &$iosub;

            do { &Coro::schedule } while !\$state;

            _set_state \$state
         }
      };
      die if $@;
   }
}

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.

=cut

sub aio_wait($) {
   my ($current, $state, $cb) = $Coro::current;

   $cb = $_[0]->cb (sub {
      $state = _get_state $current;
      &$cb if $cb;
   });

   do { &Coro::schedule } while !$state;

   _set_state $state
}

=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

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1
Revision:	1.23
Committed:	Thu Oct 30 09:57:00 2008 UTC (15 years, 7 months ago) by root
Branch:	MAIN
CVS Tags:	rel-4_802
Changes since 1.22:	+1 -1 lines
Log Message:	4.802
#	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			The API is exactly the same as that of the corresponding IO::AIO routines,
27			except that you have to specify I<all> arguments I<except> the callback
28			argument. Instead the routines return the values normally passed to the
29	root	1.3	callback. Everything else, including C<$!> and perls stat cache, are set
30			as expected after these functions return.
31	root	1.1
32			You can mix calls to C<IO::AIO> functions with calls to this module. You
33	root	1.3	I<must not>, however, call these routines from within IO::AIO callbacks,
34			as this causes a deadlock. Start a coro inside the callback instead.
35
36	root	1.18	This module also loads L<AnyEvent::AIO> to integrate into the event loop
37			in use, so please refer to its (and L<AnyEvent>'s) documentation on how it
38			selects an appropriate event module.
39	root	1.1
40	root	1.5	All other functions exported by default by IO::AIO (e.g. C<aioreq_pri>)
41			will be exported by default by Coro::AIO, too.
42
43			Functions that can be optionally imported from IO::AIO can be imported
44			from Coro::AIO or can be called directly, e.g. C<Coro::AIO::nreqs>.
45
46	root	1.12	You cannot specify priorities with C<aioreq_pri>, as this module
47			overwrites the request priority with the current coroutine priority at all
48			times.
49
50	root	1.5	For your convienience, here are the changed function signatures for most
51			of the requests, for documentation of these functions please have a look
52	root	1.17	at L<IO::AIO\|the IO::AIO manual>. Note that requests added by newer
53			versions of L<IO::AIO> will be automatically wrapped as well.
54	root	1.7
55	root	1.1	=over 4
56
57			=cut
58
59			package Coro::AIO;
60
61	root	1.8	use strict qw(subs vars);
62	root	1.2
63	root	1.22	use IO::AIO 3.1 ();
64			use AnyEvent::AIO ();
65
66	root	1.1	use Coro ();
67	root	1.22	use Coro::AnyEvent ();
68	root	1.1
69			use base Exporter::;
70
71	root	1.23	our $VERSION = 4.802;
72	root	1.20
73	root	1.22	our @EXPORT = (@IO::AIO::EXPORT, qw(aio_wait));
74	root	1.5	our @EXPORT_OK = @IO::AIO::EXPORT_OK;
75			our $AUTOLOAD;
76
77			{
78	root	1.22	my @reqs = @IO::AIO::AIO_REQ ? @IO::AIO::AIO_REQ : @IO::AIO::EXPORT;
79	root	1.5	my %reqs = map +($_ => 1), @reqs;
80
81			eval
82			join "",
83			map "sub $_(" . (prototype "IO::AIO::$_") . ");",
84			grep !$reqs{$_},
85	root	1.22	@IO::AIO::EXPORT, @EXPORT_OK;
86	root	1.1
87	root	1.5	for my $sub (@reqs) {
88			push @EXPORT, $sub;
89
90			my $iosub = "IO::AIO::$sub";
91			my $proto = prototype $iosub;
92	root	1.2
93	root	1.5	$proto =~ s/;?\$$// or die "$iosub: unable to remove callback slot from prototype";
94	root	1.1
95	root	1.5	eval qq{
96	root	1.3	#line 1 "Coro::AIO::$sub($proto)"
97	root	1.5	sub $sub($proto) {
98	root	1.22	my (\$current, \$state) = \$Coro::current;
99	root	1.5
100			push \@_, sub {
101	root	1.22	\$state = _get_state \$current;
102	root	1.5	};
103
104	root	1.12	aioreq_pri \$Coro::current->prio;
105	root	1.5	&$iosub;
106
107	root	1.22	do { &Coro::schedule } while !\$state;
108	root	1.5
109	root	1.22	_set_state \$state
110	root	1.5	}
111			};
112			die if $@;
113			}
114	root	1.1	}
115
116	root	1.5	sub AUTOLOAD {
117			(my $func = $AUTOLOAD) =~ s/^.*:://;
118			*$AUTOLOAD = \&{"IO::AIO::$func"};
119			goto &$AUTOLOAD;
120			}
121	root	1.1
122	root	1.22	=item @results = aio_wait $req
123
124			This is not originally an IO::AIO request: what it does is to wait for
125			C<$req> to finish and return the results. This is most useful with
126			C<aio_group> requests.
127
128			Is currently implemented by replacing the C<$req> callback.
129
130			=cut
131
132			sub aio_wait($) {
133			my ($current, $state, $cb) = $Coro::current;
134
135			$cb = $_[0]->cb (sub {
136			$state = _get_state $current;
137			&$cb if $cb;
138			});
139
140			do { &Coro::schedule } while !$state;
141
142			_set_state $state
143			}
144
145	root	1.1	=item $fh = aio_open $pathname, $flags, $mode
146
147			=item $status = aio_close $fh
148
149			=item $retval = aio_read $fh,$offset,$length, $data,$dataoffset
150
151			=item $retval = aio_write $fh,$offset,$length, $data,$dataoffset
152
153			=item $retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length
154
155			=item $retval = aio_readahead $fh,$offset,$length
156
157	root	1.2	=item $status = aio_stat $fh_or_path
158
159			=item $status = aio_lstat $fh
160
161	root	1.1	=item $status = aio_unlink $pathname
162
163			=item $status = aio_rmdir $pathname
164
165	root	1.3	=item $entries = aio_readdir $pathname
166	root	1.1
167			=item ($dirs, $nondirs) = aio_scandir $path, $maxreq
168
169			=item $status = aio_fsync $fh
170
171			=item $status = aio_fdatasync $fh
172
173	root	1.4	=item ... = aio_xxx ...
174
175			Any additional aio requests follow the same scheme: same parameters except
176			you must not specify a callback but instead get the callback arguments as
177			return values.
178
179	root	1.1	=back
180
181	root	1.2	=head1 SEE ALSO
182
183	root	1.4	L<Coro::Socket> and L<Coro::Handle> for non-blocking socket operation.
184	root	1.2
185	root	1.1	=head1 AUTHOR
186
187			Marc Lehmann <schmorp@schmorp.de>
188			http://home.schmorp.de/
189
190			=cut
191
192			1