ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/AIO.pm
(Generate patch)

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.1 by root, Sun Jul 10 17:07:44 2005 UTC vs.
Revision 1.4 by root, Sun Jul 10 20:57:00 2005 UTC

… …
7 use IO::AIO; 7 use IO::AIO;
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11This module implements asynchronous I/O using whatever means your 11This module implements asynchronous I/O using whatever means your
12operating system supports. Currently, it falls back to Linux::AIO if that 12operating system supports.
13module is available, or uses pthreads to emulato aio functionality.
14 13
15Currently, in this module a number of threads are started that execute 14Currently, a number of threads are started that execute your read/writes
16your read/writes and signal their completion. You don't need thread 15and signal their completion. You don't need thread support in your libc or
17support in your libc or perl, and the threads created by this module will 16perl, and the threads created by this module will not be visible to the
18not be visible to the pthreads library. 17pthreads library. In the future, this module might make use of the native
18aio functions available on many operating systems. However, they are often
19not well-supported (Linux doesn't allow them on normal files currently,
20for example), and they would only support aio_read and aio_write, so the
21remaining functionality would have to be implemented using threads anyway.
19 22
20Although the module will work with in the presence of other threads, it is 23Although the module will work with in the presence of other threads, it is
21not reentrant, so use appropriate locking yourself. 24currently not reentrant, so use appropriate locking yourself.
22 25
23=head2 API NOTES 26=head2 API NOTES
24 27
25All the C<aio_*> calls are more or less thin wrappers around the syscall 28All the C<aio_*> calls are more or less thin wrappers around the syscall
26with the same name (sans C<aio_>). The arguments are similar or identical, 29with the same name (sans C<aio_>). The arguments are similar or identical,
… …
43 46
44package IO::AIO; 47package IO::AIO;
45 48
46use base 'Exporter'; 49use base 'Exporter';
47 50
51use Fcntl ();
52
48BEGIN { 53BEGIN {
49 $VERSION = 0.1; 54 $VERSION = 0.2;
50 55
51 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink 56 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
52 aio_fsync aio_fdatasync aio_readahead); 57 aio_fsync aio_fdatasync aio_readahead);
53 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs); 58 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
54 59
55 require XSLoader; 60 require XSLoader;
56 XSLoader::load IO::AIO, $VERSION; 61 XSLoader::load IO::AIO, $VERSION;
57} 62}
58 63
… …
60 65
61Set the minimum number of AIO threads to C<$nthreads>. The default is 66Set the minimum number of AIO threads to C<$nthreads>. The default is
62C<1>, which means a single asynchronous operation can be done at one time 67C<1>, which means a single asynchronous operation can be done at one time
63(the number of outstanding operations, however, is unlimited). 68(the number of outstanding operations, however, is unlimited).
64 69
65It is recommended to keep the number of threads low, as some linux 70It is recommended to keep the number of threads low, as some Linux
66kernel versions will scale negatively with the number of threads (higher 71kernel versions will scale negatively with the number of threads (higher
67parallelity => MUCH higher latency). 72parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
73threads should be fine.
68 74
69Under normal circumstances you don't need to call this function, as this 75Under normal circumstances you don't need to call this function, as this
70module automatically starts a single async thread. 76module automatically starts some threads (the exact number might change,
77and is currently 4).
71 78
72=item IO::AIO::max_parallel $nthreads 79=item IO::AIO::max_parallel $nthreads
73 80
74Sets the maximum number of AIO threads to C<$nthreads>. If more than 81Sets the maximum number of AIO threads to C<$nthreads>. If more than
75the specified number of threads are currently running, kill them. This 82the specified number of threads are currently running, kill them. This
76function blocks until the limit is reached. 83function blocks until the limit is reached.
77 84
78This module automatically runs C<max_parallel 0> at program end, to ensure 85This module automatically runs C<max_parallel 0> at program end, to ensure
79that all threads are killed and that there are no outstanding requests. 86that all threads are killed and that there are no outstanding requests.
87
88Under normal circumstances you don't need to call this function.
89
90=item $oldnreqs = IO::AIO::max_outstanding $nreqs
91
92Sets the maximum number of outstanding requests to C<$nreqs>. If you
93try to queue up more than this number of requests, the caller will block until
94some requests have been handled.
95
96The default is very large, so normally there is no practical limit. If you
97queue up many requests in a loop it it often improves speed if you set
98this to a relatively low number, such as C<100>.
80 99
81Under normal circumstances you don't need to call this function. 100Under normal circumstances you don't need to call this function.
82 101
83=item $fileno = IO::AIO::poll_fileno 102=item $fileno = IO::AIO::poll_fileno
84 103
… …
118 IO::AIO::poll_wait, IO::AIO::poll_cb 137 IO::AIO::poll_wait, IO::AIO::poll_cb
119 while IO::AIO::nreqs; 138 while IO::AIO::nreqs;
120 139
121=item aio_open $pathname, $flags, $mode, $callback 140=item aio_open $pathname, $flags, $mode, $callback
122 141
123Asynchronously open or create a file and call the callback with the 142Asynchronously open or create a file and call the callback with a newly
124filedescriptor (NOT a perl filehandle, sorry for that, but watch out, this 143created filehandle for the file.
125might change in the future).
126 144
127The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 145The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
128for an explanation. 146for an explanation.
129 147
130The C<$mode> argument is a bitmask. See the C<Fcntl> module for a 148The C<$mode> argument is a bitmask. See the C<Fcntl> module for a
131list. They are the same as used in C<sysopen>. 149list. They are the same as used in C<sysopen>.
132 150
133Example: 151Example:
134 152
135 aio_open "/etc/passwd", O_RDONLY, 0, sub { 153 aio_open "/etc/passwd", O_RDONLY, 0, sub {
136 if ($_[0] >= 0) { 154 if ($_[0]) {
137 open my $fh, "<&$_[0]"; # create a copy for perl
138 aio_close $_[0], sub { }; # close the aio handle
139 print "open successful, fh is $fh\n"; 155 print "open successful, fh is $_[0]\n";
140 ... 156 ...
141 } else { 157 } else {
142 die "open failed: $!\n"; 158 die "open failed: $!\n";
143 } 159 }
144 }; 160 };
145 161
146=item aio_close $fh, $callback 162=item aio_close $fh, $callback
147 163
148Asynchronously close a file and call the callback with the result code. 164Asynchronously close a file and call the callback with the result
165code. I<WARNING:> although accepted, you should not pass in a perl
166filehandle here, as perl will likely close the file descriptor itself when
167the filehandle is destroyed. Normally, you can safely call perls C<close>
168or just let filehandles go out of scope.
149 169
150=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback 170=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback
151 171
152=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback 172=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback
153 173
… …
216Asynchronously call fdatasync on the given filehandle and call the 236Asynchronously call fdatasync on the given filehandle and call the
217callback with the fdatasync result code. 237callback with the fdatasync result code.
218 238
219=cut 239=cut
220 240
241# support function to convert a fd into a perl filehandle
242sub _fd2fh {
243 return undef if $_[0] < 0;
244
245 # try to be perl5.6-compatible
246 local *AIO_FH;
247 open AIO_FH, "+<&=$_[0]"
248 or return undef;
249
250 *AIO_FH
251}
252
221min_parallel 4; 253min_parallel 4;
222 254
223END { 255END {
224 max_parallel 0; 256 max_parallel 0;
225} 257}
… …
228 260
229=back 261=back
230 262
231=head1 BUGS 263=head1 BUGS
232 264
233 - aio_open gives a fd, but all other functions expect a perl filehandle. 265 - could be optimized to use more semaphores instead of filehandles.
234 266
235=head1 SEE ALSO 267=head1 SEE ALSO
236 268
237L<Coro>, L<Linux::AIO>. 269L<Coro>, L<Linux::AIO>.
238 270

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines