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
   # aio_sendfile aio_read aio_write aio_open aio_close aio_stat aio_lstat
   # aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink aio_fsync
   # aio_fdatasync aio_readahead

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

For your convienience, here are the changed function signatures, for
documentation of these functions please have a look at L<IO::AIO|the
IO::AIO manual>.

=over 4

=cut

package Coro::AIO;

use strict;

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 => sub { IO::AIO::poll_cb });

our @EXPORT;

sub wrap($) {
   my ($sub) = @_;

   no strict 'refs';
   
   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 \$stat;
         my \@res;

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

         &$iosub;

         Coro::schedule while \$current;

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

wrap $_ for qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
               aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir
               aio_symlink aio_fsync aio_fdatasync aio_readahead);

=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

=back

=head1 SEE ALSO

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

=head1 AUTHOR

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

=cut

1
Revision:	1.3
Committed:	Mon Dec 26 21:54:44 2005 UTC (20 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-1_9, rel-1_7
Changes since 1.2:	+32 -21 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.2	# can now use any of
10			# aio_sendfile aio_read aio_write aio_open aio_close aio_stat aio_lstat
11	root	1.1	# aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink aio_fsync
12			# aio_fdatasync aio_readahead
13
14			# read 1MB of /etc/passwd, without blocking other coroutines
15			my $fh = aio_open "/etc/passwd", O_RDONLY, 0
16			or die "/etc/passwd: $!";
17			aio_read $fh, 0, 1_000_000, my $buf, 0
18			or die "aio_read: $!";
19			aio_close $fh;
20
21			=head1 DESCRIPTION
22
23			This module implements a thin wrapper around L<IO::AIO\|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			You also can, but do not need to, call C<IO::AIO::poll_cb>, as this
37			module automatically installs an event watcher for the C<IO::AIO> file
38	root	1.1	descriptor. It uses the L<AnyEvent\|AnyEvent> module for this, so please
39			refer to its documentation on how it selects an appropriate Event module.
40
41			For your convienience, here are the changed function signatures, for
42			documentation of these functions please have a look at L<IO::AIO\|the
43			IO::AIO manual>.
44
45			=over 4
46
47			=cut
48
49			package Coro::AIO;
50
51	root	1.2	use strict;
52
53	root	1.1	use Coro ();
54			use AnyEvent;
55			use IO::AIO ();
56
57			use base Exporter::;
58
59			our $FH; open $FH, "<&=" . IO::AIO::poll_fileno;
60			our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => sub { IO::AIO::poll_cb });
61
62			our @EXPORT;
63
64			sub wrap($) {
65			my ($sub) = @_;
66	root	1.2
67			no strict 'refs';
68	root	1.1
69			push @EXPORT, $sub;
70
71			my $iosub = "IO::AIO::$sub";
72	root	1.3	my $proto = prototype $iosub;
73	root	1.1
74	root	1.3	$proto =~ s/;?\$$// or die "$iosub: unable to remove callback slot from prototype";
75	root	1.1
76	root	1.3	eval qq{
77			#line 1 "Coro::AIO::$sub($proto)"
78			sub $sub($proto) {
79			my \$current = \$Coro::current;
80			my \$stat;
81			my \@res;
82
83			push \@_, sub {
84			\$stat = Coro::_aio_get_state;
85			\@res = \@_;
86			\$current->ready;
87			undef \$current;
88			};
89
90			&$iosub;
91
92			Coro::schedule while \$current;
93
94			Coro::_aio_set_state \$stat;
95			wantarray ? \@res : \$res[0]
96			}
97	root	1.1	};
98	root	1.3	die if $@;
99	root	1.1	}
100
101	root	1.2	wrap $_ for qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
102			aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir
103			aio_symlink aio_fsync aio_fdatasync aio_readahead);
104	root	1.1
105			=item $fh = aio_open $pathname, $flags, $mode
106
107			=item $status = aio_close $fh
108
109			=item $retval = aio_read $fh,$offset,$length, $data,$dataoffset
110
111			=item $retval = aio_write $fh,$offset,$length, $data,$dataoffset
112
113			=item $retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length
114
115			=item $retval = aio_readahead $fh,$offset,$length
116
117	root	1.2	=item $status = aio_stat $fh_or_path
118
119			=item $status = aio_lstat $fh
120
121	root	1.1	=item $status = aio_unlink $pathname
122
123			=item $status = aio_rmdir $pathname
124
125	root	1.3	=item $entries = aio_readdir $pathname
126	root	1.1
127			=item ($dirs, $nondirs) = aio_scandir $path, $maxreq
128
129			=item $status = aio_fsync $fh
130
131			=item $status = aio_fdatasync $fh
132
133			=back
134
135	root	1.2	=head1 SEE ALSO
136
137			L<Coro::Socket> and L<Coro::Handle> for non-blocking file operation.
138
139	root	1.1	=head1 AUTHOR
140
141			Marc Lehmann <schmorp@schmorp.de>
142			http://home.schmorp.de/
143
144			=cut
145
146			1