Coro/Coro/AIO.pm

=head1 NAME

Coro::AIO - truly asynchronous file and directrory 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 implements a thin wrapper around L<IO::AIO|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.

You also can, but do not need to, call C<IO::AIO::poll_cb>, as this
module automatically installs an event watcher for the C<IO::AIO> file
descriptor. It uses the L<AnyEvent|AnyEvent> module for this, so please
refer to its 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>.

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

The AnyEvent watcher can be disabled by executing C<undef
$Coro::AIO::WATCHER>. Please notify the author of when and why you think
this was necessary.

=over 4

=cut

package Coro::AIO;

use strict qw(subs vars);

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

use base Exporter::;

our $FH; open $FH, "<&=" . IO::AIO::poll_fileno;
our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => \&IO::AIO::poll_cb);

our @EXPORT    = @IO::AIO::EXPORT;
our @EXPORT_OK = @IO::AIO::EXPORT_OK;
our $AUTOLOAD;

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

   eval
      join "",
         map "sub $_(" . (prototype "IO::AIO::$_") . ");",
            grep !$reqs{$_},
                @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 = \$Coro::current;
            my \$state;
            my \@res;

            push \@_, sub {
               \$state = Coro::_aio_get_state;
               \@res = \@_;
               \$current->ready;
            };

            &$iosub;

            Coro::schedule;
            Coro::schedule while !\$state;

            Coro::_aio_set_state \$state;
            wantarray ? \@res : \$res[0]
         }
      };
      die if $@;
   }
}

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

=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.9
Committed:	Mon Nov 20 22:41:44 2006 UTC (17 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	stack_sharing
Changes since 1.8:	+1 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.2	Coro::AIO - truly asynchronous file and directrory 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			This module implements a thin wrapper around L<IO::AIO\|IO::AIO>. All of
21	root	1.2	the functions that expect a callback are being wrapped by this module.
22	root	1.1
23			The API is exactly the same as that of the corresponding IO::AIO routines,
24			except that you have to specify I<all> arguments I<except> the callback
25			argument. Instead the routines return the values normally passed to the
26	root	1.3	callback. Everything else, including C<$!> and perls stat cache, are set
27			as expected after these functions return.
28	root	1.1
29			You can mix calls to C<IO::AIO> functions with calls to this module. You
30	root	1.3	I<must not>, however, call these routines from within IO::AIO callbacks,
31			as this causes a deadlock. Start a coro inside the callback instead.
32
33			You also can, but do not need to, call C<IO::AIO::poll_cb>, as this
34			module automatically installs an event watcher for the C<IO::AIO> file
35	root	1.1	descriptor. It uses the L<AnyEvent\|AnyEvent> module for this, so please
36			refer to its documentation on how it selects an appropriate Event module.
37
38	root	1.5	All other functions exported by default by IO::AIO (e.g. C<aioreq_pri>)
39			will be exported by default by Coro::AIO, too.
40
41			Functions that can be optionally imported from IO::AIO can be imported
42			from Coro::AIO or can be called directly, e.g. C<Coro::AIO::nreqs>.
43
44			For your convienience, here are the changed function signatures for most
45			of the requests, for documentation of these functions please have a look
46			at L<IO::AIO\|the IO::AIO manual>.
47	root	1.1
48	root	1.7	The AnyEvent watcher can be disabled by executing C<undef
49			$Coro::AIO::WATCHER>. Please notify the author of when and why you think
50			this was necessary.
51
52	root	1.1	=over 4
53
54			=cut
55
56			package Coro::AIO;
57
58	root	1.8	use strict qw(subs vars);
59	root	1.2
60	root	1.1	use Coro ();
61			use AnyEvent;
62			use IO::AIO ();
63
64			use base Exporter::;
65
66			our $FH; open $FH, "<&=" . IO::AIO::poll_fileno;
67	root	1.7	our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => \&IO::AIO::poll_cb);
68	root	1.1
69	root	1.5	our @EXPORT = @IO::AIO::EXPORT;
70			our @EXPORT_OK = @IO::AIO::EXPORT_OK;
71			our $AUTOLOAD;
72
73			{
74			my @reqs = @IO::AIO::AIO_REQ ? @IO::AIO::AIO_REQ : @EXPORT;
75			my %reqs = map +($_ => 1), @reqs;
76
77			eval
78			join "",
79			map "sub $_(" . (prototype "IO::AIO::$_") . ");",
80			grep !$reqs{$_},
81			@EXPORT, @EXPORT_OK;
82	root	1.1
83	root	1.5	for my $sub (@reqs) {
84			push @EXPORT, $sub;
85
86			my $iosub = "IO::AIO::$sub";
87			my $proto = prototype $iosub;
88	root	1.2
89	root	1.5	$proto =~ s/;?\$$// or die "$iosub: unable to remove callback slot from prototype";
90	root	1.1
91	root	1.5	eval qq{
92	root	1.3	#line 1 "Coro::AIO::$sub($proto)"
93	root	1.5	sub $sub($proto) {
94			my \$current = \$Coro::current;
95	root	1.6	my \$state;
96	root	1.5	my \@res;
97
98			push \@_, sub {
99	root	1.8	\$state = Coro::_aio_get_state;
100	root	1.5	\@res = \@_;
101			\$current->ready;
102			};
103
104			&$iosub;
105
106	root	1.9	Coro::schedule;
107	root	1.6	Coro::schedule while !\$state;
108	root	1.5
109	root	1.6	Coro::_aio_set_state \$state;
110	root	1.5	wantarray ? \@res : \$res[0]
111			}
112			};
113			die if $@;
114			}
115	root	1.1	}
116
117	root	1.5	sub AUTOLOAD {
118			(my $func = $AUTOLOAD) =~ s/^.*:://;
119			*$AUTOLOAD = \&{"IO::AIO::$func"};
120			goto &$AUTOLOAD;
121			}
122	root	1.1
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	root	1.2	=item $status = aio_stat $fh_or_path
136
137			=item $status = aio_lstat $fh
138
139	root	1.1	=item $status = aio_unlink $pathname
140
141			=item $status = aio_rmdir $pathname
142
143	root	1.3	=item $entries = aio_readdir $pathname
144	root	1.1
145			=item ($dirs, $nondirs) = aio_scandir $path, $maxreq
146
147			=item $status = aio_fsync $fh
148
149			=item $status = aio_fdatasync $fh
150
151	root	1.4	=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	root	1.1	=back
158
159	root	1.2	=head1 SEE ALSO
160
161	root	1.4	L<Coro::Socket> and L<Coro::Handle> for non-blocking socket operation.
162	root	1.2
163	root	1.1	=head1 AUTHOR
164
165			Marc Lehmann <schmorp@schmorp.de>
166			http://home.schmorp.de/
167
168			=cut
169
170			1