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.22 by root, Wed Jul 20 21:55:27 2005 UTC vs.
Revision 1.50 by root, Sat Jun 24 16:27:02 2006 UTC

14 aio_unlink "/tmp/file", sub { }; 14 aio_unlink "/tmp/file", sub { };
15 15
16 aio_read $fh, 30000, 1024, $buffer, 0, sub { 16 aio_read $fh, 30000, 1024, $buffer, 0, sub {
17 $_[0] > 0 or die "read error: $!"; 17 $_[0] > 0 or die "read error: $!";
18 }; 18 };
19
20 # AnyEvent
21 open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
22 my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
19 23
20 # Event 24 # Event
21 Event->io (fd => IO::AIO::poll_fileno, 25 Event->io (fd => IO::AIO::poll_fileno,
22 poll => 'r', 26 poll => 'r',
23 cb => \&IO::AIO::poll_cb); 27 cb => \&IO::AIO::poll_cb);
56 60
57=cut 61=cut
58 62
59package IO::AIO; 63package IO::AIO;
60 64
65no warnings;
66
61use base 'Exporter'; 67use base 'Exporter';
62 68
63use Fcntl (); 69use Fcntl ();
64 70
65BEGIN { 71BEGIN {
66 $VERSION = 0.9; 72 $VERSION = '1.8';
67 73
68 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink 74 @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
75 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
69 aio_fsync aio_fdatasync aio_readahead); 76 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move);
70 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 77 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel
78 max_outstanding nreqs);
71 79
72 require XSLoader; 80 require XSLoader;
73 XSLoader::load IO::AIO, $VERSION; 81 XSLoader::load IO::AIO, $VERSION;
74} 82}
75 83
83which must be a code reference. This code reference will get called with 91which must be a code reference. This code reference will get called with
84the syscall return code (e.g. most syscalls return C<-1> on error, unlike 92the syscall return code (e.g. most syscalls return C<-1> on error, unlike
85perl, which usually delivers "false") as it's sole argument when the given 93perl, which usually delivers "false") as it's sole argument when the given
86syscall has been executed asynchronously. 94syscall has been executed asynchronously.
87 95
88All functions that expect a filehandle will also accept a file descriptor. 96All functions expecting a filehandle keep a copy of the filehandle
97internally until the request has finished.
89 98
90The filenames you pass to these routines I<must> be absolute. The reason 99The pathnames you pass to these routines I<must> be absolute and
91for this is that at the time the request is being executed, the current 100encoded in byte form. The reason for the former is that at the time the
92working directory could have changed. Alternatively, you can make sure 101request is being executed, the current working directory could have
93that you never change the current working directory. 102changed. Alternatively, you can make sure that you never change the
103current working directory.
104
105To encode pathnames to byte form, either make sure you either: a)
106always pass in filenames you got from outside (command line, readdir
107etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode
108your pathnames to the locale (or other) encoding in effect in the user
109environment, d) use Glib::filename_from_unicode on unicode filenames or e)
110use something else.
94 111
95=over 4 112=over 4
96 113
97=item aio_open $pathname, $flags, $mode, $callback 114=item aio_open $pathname, $flags, $mode, $callback->($fh)
98 115
99Asynchronously open or create a file and call the callback with a newly 116Asynchronously open or create a file and call the callback with a newly
100created filehandle for the file. 117created filehandle for the file.
101 118
102The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 119The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
119 } else { 136 } else {
120 die "open failed: $!\n"; 137 die "open failed: $!\n";
121 } 138 }
122 }; 139 };
123 140
124=item aio_close $fh, $callback 141=item aio_close $fh, $callback->($status)
125 142
126Asynchronously close a file and call the callback with the result 143Asynchronously close a file and call the callback with the result
127code. I<WARNING:> although accepted, you should not pass in a perl 144code. I<WARNING:> although accepted, you should not pass in a perl
128filehandle here, as perl will likely close the file descriptor another 145filehandle here, as perl will likely close the file descriptor another
129time when the filehandle is destroyed. Normally, you can safely call perls 146time when the filehandle is destroyed. Normally, you can safely call perls
130C<close> or just let filehandles go out of scope. 147C<close> or just let filehandles go out of scope.
131 148
132This is supposed to be a bug in the API, so that might change. It's 149This is supposed to be a bug in the API, so that might change. It's
133therefore best to avoid this function. 150therefore best to avoid this function.
134 151
135=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback 152=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
136 153
137=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback 154=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
138 155
139Reads or writes C<length> bytes from the specified C<fh> and C<offset> 156Reads or writes C<length> bytes from the specified C<fh> and C<offset>
140into the scalar given by C<data> and offset C<dataoffset> and calls the 157into the scalar given by C<data> and offset C<dataoffset> and calls the
141callback without the actual number of bytes read (or -1 on error, just 158callback without the actual number of bytes read (or -1 on error, just
142like the syscall). 159like the syscall).
143 160
161The C<$data> scalar I<MUST NOT> be modified in any way while the request
162is outstanding. Modifying it can result in segfaults or WW3 (if the
163necessary/optional hardware is installed).
164
144Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at 165Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
145offset C<0> within the scalar: 166offset C<0> within the scalar:
146 167
147 aio_read $fh, 7, 15, $buffer, 0, sub { 168 aio_read $fh, 7, 15, $buffer, 0, sub {
148 $_[0] > 0 or die "read error: $!"; 169 $_[0] > 0 or die "read error: $!";
149 print "read $_[0] bytes: <$buffer>\n"; 170 print "read $_[0] bytes: <$buffer>\n";
150 }; 171 };
151 172
173=item aio_move $srcpath, $dstpath, $callback->($status)
174
175[EXPERIMENTAL]
176
177Try to move the I<file> (directories not supported as either source or destination)
178from C<$srcpath> to C<$dstpath> and call the callback with the C<0> (error) or C<-1> ok.
179
180This is a composite request that tries to rename(2) the file first. If
181rename files with C<EXDEV>, it creates the destination file with mode 0200
182and copies the contents of the source file into it using C<aio_sendfile>,
183followed by restoring atime, mtime, access mode and uid/gid, in that
184order, and unlinking the C<$srcpath>.
185
186If an error occurs, the partial destination file will be unlinked, if
187possible, except when setting atime, mtime, access mode and uid/gid, where
188errors are being ignored.
189
190=cut
191
192sub aio_move($$$) {
193 my ($src, $dst, $cb) = @_;
194
195 aio_rename $src, $dst, sub {
196 if ($_[0] && $! == Errno::EXDEV) {
197 aio_open $src, O_RDONLY, 0, sub {
198 if (my $src_fh = $_[0]) {
199 my @stat = stat $src_fh;
200
201 aio_open $dst, O_WRONLY, 0200, sub {
202 if (my $dst_fh = $_[0]) {
203 aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
204 close $src_fh;
205
206 if ($_[0] == $stat[7]) {
207 utime $stat[8], $stat[9], $dst;
208 chmod $stat[2] & 07777, $dst_fh;
209 chown $stat[4], $stat[5], $dst_fh;
210 close $dst_fh;
211
212 aio_unlink $src, sub {
213 $cb->($_[0]);
214 };
215 } else {
216 my $errno = $!;
217 aio_unlink $dst, sub {
218 $! = $errno;
219 $cb->(-1);
220 };
221 }
222 };
223 } else {
224 $cb->(-1);
225 }
226 },
227
228 } else {
229 $cb->(-1);
230 }
231 };
232 } else {
233 $cb->($_[0]);
234 }
235 };
236}
237
238=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
239
240Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
241reading at byte offset C<$in_offset>, and starts writing at the current
242file offset of C<$out_fh>. Because of that, it is not safe to issue more
243than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
244other.
245
246This call tries to make use of a native C<sendfile> syscall to provide
247zero-copy operation. For this to work, C<$out_fh> should refer to a
248socket, and C<$in_fh> should refer to mmap'able file.
249
250If the native sendfile call fails or is not implemented, it will be
251emulated, so you can call C<aio_sendfile> on any type of filehandle
252regardless of the limitations of the operating system.
253
254Please note, however, that C<aio_sendfile> can read more bytes from
255C<$in_fh> than are written, and there is no way to find out how many
256bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
257provides the number of bytes written to C<$out_fh>. Only if the result
258value equals C<$length> one can assume that C<$length> bytes have been
259read.
260
152=item aio_readahead $fh,$offset,$length, $callback 261=item aio_readahead $fh,$offset,$length, $callback->($retval)
153
154Asynchronously reads the specified byte range into the page cache, using
155the C<readahead> syscall. If that syscall doesn't exist (likely if your OS
156isn't Linux) the status will be C<-1> and C<$!> is set to C<ENOSYS>.
157 262
158C<aio_readahead> populates the page cache with data from a file so that 263C<aio_readahead> populates the page cache with data from a file so that
159subsequent reads from that file will not block on disk I/O. The C<$offset> 264subsequent reads from that file will not block on disk I/O. The C<$offset>
160argument specifies the starting point from which data is to be read and 265argument specifies the starting point from which data is to be read and
161C<$length> specifies the number of bytes to be read. I/O is performed in 266C<$length> specifies the number of bytes to be read. I/O is performed in
162whole pages, so that offset is effectively rounded down to a page boundary 267whole pages, so that offset is effectively rounded down to a page boundary
163and bytes are read up to the next page boundary greater than or equal to 268and bytes are read up to the next page boundary greater than or equal to
164(off-set+length). C<aio_readahead> does not read beyond the end of the 269(off-set+length). C<aio_readahead> does not read beyond the end of the
165file. The current file offset of the file is left unchanged. 270file. The current file offset of the file is left unchanged.
166 271
272If that syscall doesn't exist (likely if your OS isn't Linux) it will be
273emulated by simply reading the data, which would have a similar effect.
274
167=item aio_stat $fh_or_path, $callback 275=item aio_stat $fh_or_path, $callback->($status)
168 276
169=item aio_lstat $fh, $callback 277=item aio_lstat $fh, $callback->($status)
170 278
171Works like perl's C<stat> or C<lstat> in void context. The callback will 279Works like perl's C<stat> or C<lstat> in void context. The callback will
172be called after the stat and the results will be available using C<stat _> 280be called after the stat and the results will be available using C<stat _>
173or C<-s _> etc... 281or C<-s _> etc...
174 282
184 aio_stat "/etc/passwd", sub { 292 aio_stat "/etc/passwd", sub {
185 $_[0] and die "stat failed: $!"; 293 $_[0] and die "stat failed: $!";
186 print "size is ", -s _, "\n"; 294 print "size is ", -s _, "\n";
187 }; 295 };
188 296
189=item aio_unlink $pathname, $callback 297=item aio_unlink $pathname, $callback->($status)
190 298
191Asynchronously unlink (delete) a file and call the callback with the 299Asynchronously unlink (delete) a file and call the callback with the
192result code. 300result code.
193 301
302=item aio_link $srcpath, $dstpath, $callback->($status)
303
304Asynchronously create a new link to the existing object at C<$srcpath> at
305the path C<$dstpath> and call the callback with the result code.
306
307=item aio_symlink $srcpath, $dstpath, $callback->($status)
308
309Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
310the path C<$dstpath> and call the callback with the result code.
311
312=item aio_rename $srcpath, $dstpath, $callback->($status)
313
314Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
315rename(2) and call the callback with the result code.
316
317=item aio_rmdir $pathname, $callback->($status)
318
319Asynchronously rmdir (delete) a directory and call the callback with the
320result code.
321
322=item aio_readdir $pathname, $callback->($entries)
323
324Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
325directory (i.e. opendir + readdir + closedir). The entries will not be
326sorted, and will B<NOT> include the C<.> and C<..> entries.
327
328The callback a single argument which is either C<undef> or an array-ref
329with the filenames.
330
331=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
332
333Scans a directory (similar to C<aio_readdir>) and tries to separate the
334entries of directory C<$path> into two sets of names, ones you can recurse
335into (directories), and ones you cannot recurse into (everything else).
336
337C<aio_scandir> is a composite request that consists of many
338aio-primitives. C<$maxreq> specifies the maximum number of outstanding
339aio requests that this function generates. If it is C<< <= 0 >>, then a
340suitable default will be chosen (currently 8).
341
342On error, the callback is called without arguments, otherwise it receives
343two array-refs with path-relative entry names.
344
345Example:
346
347 aio_scandir $dir, 0, sub {
348 my ($dirs, $nondirs) = @_;
349 print "real directories: @$dirs\n";
350 print "everything else: @$nondirs\n";
351 };
352
353Implementation notes.
354
355The C<aio_readdir> cannot be avoided, but C<stat()>'ing every entry can.
356
357After reading the directory, the modification time, size etc. of the
358directory before and after the readdir is checked, and if they match, the
359link count will be used to decide how many entries are directories (if
360>= 2). Otherwise, no knowledge of the number of subdirectories will be
361assumed.
362
363Then entires will be sorted into likely directories (everything without a
364non-initial dot) and likely non-directories (everything else). Then every
365entry + C</.> will be C<stat>'ed, likely directories first. This is often
366faster because filesystems might detect the type of the entry without
367reading the inode data (e.g. ext2fs filetype feature). If that succeeds,
368it assumes that the entry is a directory or a symlink to directory (which
369will be checked seperately).
370
371If the known number of directories has been reached, the rest of the
372entries is assumed to be non-directories.
373
374=cut
375
376sub aio_scandir($$$) {
377 my ($path, $maxreq, $cb) = @_;
378
379 $maxreq = 8 if $maxreq <= 0;
380
381 # stat once
382 aio_stat $path, sub {
383 return $cb->() if $_[0];
384 my $hash1 = join ":", (stat _)[0,1,3,7,9];
385
386 # read the directory entries
387 aio_readdir $path, sub {
388 my $entries = shift
389 or return $cb->();
390
391 # stat the dir another time
392 aio_stat $path, sub {
393 my $hash2 = join ":", (stat _)[0,1,3,7,9];
394
395 my $ndirs;
396
397 # take the slow route if anything looks fishy
398 if ($hash1 ne $hash2) {
399 $ndirs = -1;
400 } else {
401 # if nlink == 2, we are finished
402 # on non-posix-fs's, we rely on nlink < 2
403 $ndirs = (stat _)[3] - 2
404 or return $cb->([], $entries);
405 }
406
407 # sort into likely dirs and likely nondirs
408 # dirs == files without ".", short entries first
409 $entries = [map $_->[0],
410 sort { $b->[1] cmp $a->[1] }
411 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
412 @$entries];
413
414 my (@dirs, @nondirs);
415
416 my ($statcb, $schedcb);
417 my $nreq = 0;
418
419 $schedcb = sub {
420 if (@$entries) {
421 if ($nreq < $maxreq) {
422 my $ent = pop @$entries;
423 $nreq++;
424 aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
425 }
426 } elsif (!$nreq) {
427 # finished
428 undef $statcb;
429 undef $schedcb;
430 $cb->(\@dirs, \@nondirs) if $cb;
431 undef $cb;
432 }
433 };
434 $statcb = sub {
435 my ($status, $entry) = @_;
436
437 if ($status < 0) {
438 $nreq--;
439 push @nondirs, $entry;
440 &$schedcb;
441 } else {
442 # need to check for real directory
443 aio_lstat "$path/$entry", sub {
444 $nreq--;
445
446 if (-d _) {
447 push @dirs, $entry;
448
449 if (!--$ndirs) {
450 push @nondirs, @$entries;
451 $entries = [];
452 }
453 } else {
454 push @nondirs, $entry;
455 }
456
457 &$schedcb;
458 }
459 }
460 };
461
462 &$schedcb while @$entries && $nreq < $maxreq;
463 };
464 };
465 };
466}
467
194=item aio_fsync $fh, $callback 468=item aio_fsync $fh, $callback->($status)
195 469
196Asynchronously call fsync on the given filehandle and call the callback 470Asynchronously call fsync on the given filehandle and call the callback
197with the fsync result code. 471with the fsync result code.
198 472
199=item aio_fdatasync $fh, $callback 473=item aio_fdatasync $fh, $callback->($status)
200 474
201Asynchronously call fdatasync on the given filehandle and call the 475Asynchronously call fdatasync on the given filehandle and call the
202callback with the fdatasync result code. Might set C<$!> to C<ENOSYS> if 476callback with the fdatasync result code.
203C<fdatasync> is not available. 477
478If this call isn't available because your OS lacks it or it couldn't be
479detected, it will be emulated by calling C<fsync> instead.
204 480
205=back 481=back
206 482
207=head2 SUPPORT FUNCTIONS 483=head2 SUPPORT FUNCTIONS
208 484
266 IO::AIO::poll_wait, IO::AIO::poll_cb 542 IO::AIO::poll_wait, IO::AIO::poll_cb
267 if IO::AIO::nreqs; 543 if IO::AIO::nreqs;
268 544
269=item IO::AIO::min_parallel $nthreads 545=item IO::AIO::min_parallel $nthreads
270 546
271Set the minimum number of AIO threads to C<$nthreads>. The default is 547Set the minimum number of AIO threads to C<$nthreads>. The current default
272C<1>, which means a single asynchronous operation can be done at one time 548is C<4>, which means four asynchronous operations can be done at one time
273(the number of outstanding operations, however, is unlimited). 549(the number of outstanding operations, however, is unlimited).
550
551IO::AIO starts threads only on demand, when an AIO request is queued and
552no free thread exists.
274 553
275It is recommended to keep the number of threads low, as some Linux 554It is recommended to keep the number of threads low, as some Linux
276kernel versions will scale negatively with the number of threads (higher 555kernel versions will scale negatively with the number of threads (higher
277parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 556parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
278threads should be fine. 557threads should be fine.
279 558
280Under normal circumstances you don't need to call this function, as this 559Under most circumstances you don't need to call this function, as the
281module automatically starts some threads (the exact number might change, 560module selects a default that is suitable for low to moderate load.
282and is currently 4).
283 561
284=item IO::AIO::max_parallel $nthreads 562=item IO::AIO::max_parallel $nthreads
285 563
286Sets the maximum number of AIO threads to C<$nthreads>. If more than 564Sets the maximum number of AIO threads to C<$nthreads>. If more than the
287the specified number of threads are currently running, kill them. This 565specified number of threads are currently running, this function kills
288function blocks until the limit is reached. 566them. This function blocks until the limit is reached.
567
568While C<$nthreads> are zero, aio requests get queued but not executed
569until the number of threads has been increased again.
289 570
290This module automatically runs C<max_parallel 0> at program end, to ensure 571This module automatically runs C<max_parallel 0> at program end, to ensure
291that all threads are killed and that there are no outstanding requests. 572that all threads are killed and that there are no outstanding requests.
292 573
293Under normal circumstances you don't need to call this function. 574Under normal circumstances you don't need to call this function.
297Sets the maximum number of outstanding requests to C<$nreqs>. If you 578Sets the maximum number of outstanding requests to C<$nreqs>. If you
298try to queue up more than this number of requests, the caller will block until 579try to queue up more than this number of requests, the caller will block until
299some requests have been handled. 580some requests have been handled.
300 581
301The default is very large, so normally there is no practical limit. If you 582The default is very large, so normally there is no practical limit. If you
302queue up many requests in a loop it it often improves speed if you set 583queue up many requests in a loop it often improves speed if you set
303this to a relatively low number, such as C<100>. 584this to a relatively low number, such as C<100>.
304 585
305Under normal circumstances you don't need to call this function. 586Under normal circumstances you don't need to call this function.
306 587
307=back 588=back
310 591
311# support function to convert a fd into a perl filehandle 592# support function to convert a fd into a perl filehandle
312sub _fd2fh { 593sub _fd2fh {
313 return undef if $_[0] < 0; 594 return undef if $_[0] < 0;
314 595
315 # try to be perl5.6-compatible 596 # try to generate nice filehandles
316 local *AIO_FH; 597 my $sym = "IO::AIO::fd#$_[0]";
317 open AIO_FH, "+<&=$_[0]" 598 local *$sym;
599
600 open *$sym, "+<&=$_[0]" # usually works under any unix
601 or open *$sym, "<&=$_[0]" # cygwin needs this
602 or open *$sym, ">&=$_[0]" # or this
318 or return undef; 603 or return undef;
319 604
320 *AIO_FH 605 *$sym
321} 606}
322 607
323min_parallel 4; 608min_parallel 4;
324 609
325END { 610END {
326 max_parallel 0; 611 max_parallel 0;
327} 612}
328 613
3291; 6141;
330 615
616=head2 FORK BEHAVIOUR
617
618Before the fork, IO::AIO enters a quiescent state where no requests
619can be added in other threads and no results will be processed. After
620the fork the parent simply leaves the quiescent state and continues
621request/result processing, while the child clears the request/result
622queue (so the requests started before the fork will only be handled in
623the parent). Threats will be started on demand until the limit ste in the
624parent process has been reached again.
625
331=head1 SEE ALSO 626=head1 SEE ALSO
332 627
333L<Coro>, L<Linux::AIO>. 628L<Coro>, L<Linux::AIO>.
334 629
335=head1 AUTHOR 630=head1 AUTHOR

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines