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

Comparing IO-AIO/README (file contents):
Revision 1.31 by root, Thu May 29 03:35:03 2008 UTC vs.
Revision 1.35 by root, Tue Apr 21 20:06:05 2009 UTC

… …
175 All the "aio_*" calls are more or less thin wrappers around the syscall 175 All the "aio_*" calls are more or less thin wrappers around the syscall
176 with the same name (sans "aio_"). The arguments are similar or 176 with the same name (sans "aio_"). The arguments are similar or
177 identical, and they all accept an additional (and optional) $callback 177 identical, and they all accept an additional (and optional) $callback
178 argument which must be a code reference. This code reference will get 178 argument which must be a code reference. This code reference will get
179 called with the syscall return code (e.g. most syscalls return -1 on 179 called with the syscall return code (e.g. most syscalls return -1 on
180 error, unlike perl, which usually delivers "false") as it's sole 180 error, unlike perl, which usually delivers "false") as its sole argument
181 argument when the given syscall has been executed asynchronously. 181 after the given syscall has been executed asynchronously.
182 182
183 All functions expecting a filehandle keep a copy of the filehandle 183 All functions expecting a filehandle keep a copy of the filehandle
184 internally until the request has finished. 184 internally until the request has finished.
185 185
186 All functions return request objects of type IO::AIO::REQ that allow 186 All functions return request objects of type IO::AIO::REQ that allow
… …
199 the user environment, d) use Glib::filename_from_unicode on unicode 199 the user environment, d) use Glib::filename_from_unicode on unicode
200 filenames or e) use something else to ensure your scalar has the correct 200 filenames or e) use something else to ensure your scalar has the correct
201 contents. 201 contents.
202 202
203 This works, btw. independent of the internal UTF-8 bit, which IO::AIO 203 This works, btw. independent of the internal UTF-8 bit, which IO::AIO
204 handles correctly wether it is set or not. 204 handles correctly whether it is set or not.
205 205
206 $prev_pri = aioreq_pri [$pri] 206 $prev_pri = aioreq_pri [$pri]
207 Returns the priority value that would be used for the next request 207 Returns the priority value that would be used for the next request
208 and, if $pri is given, sets the priority for the next aio request. 208 and, if $pri is given, sets the priority for the next aio request.
209 209
… …
275 Or in other words: the file descriptor will be closed, but it will 275 Or in other words: the file descriptor will be closed, but it will
276 not be free for reuse until the perl filehandle is closed. 276 not be free for reuse until the perl filehandle is closed.
277 277
278 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 278 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
279 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 279 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
280 Reads or writes $length bytes from the specified $fh and $offset 280 Reads or writes $length bytes from or to the specified $fh and
281 into the scalar given by $data and offset $dataoffset and calls the 281 $offset into the scalar given by $data and offset $dataoffset and
282 callback without the actual number of bytes read (or -1 on error, 282 calls the callback without the actual number of bytes read (or -1 on
283 just like the syscall). 283 error, just like the syscall).
284
285 "aio_read" will, like "sysread", shrink or grow the $data scalar to
286 offset plus the actual number of bytes read.
284 287
285 If $offset is undefined, then the current file descriptor offset 288 If $offset is undefined, then the current file descriptor offset
286 will be used (and updated), otherwise the file descriptor offset 289 will be used (and updated), otherwise the file descriptor offset
287 will not be changed by these calls. 290 will not be changed by these calls.
288 291
… …
451 aio_copy $srcpath, $dstpath, $callback->($status) 454 aio_copy $srcpath, $dstpath, $callback->($status)
452 Try to copy the *file* (directories not supported as either source 455 Try to copy the *file* (directories not supported as either source
453 or destination) from $srcpath to $dstpath and call the callback with 456 or destination) from $srcpath to $dstpath and call the callback with
454 the 0 (error) or -1 ok. 457 the 0 (error) or -1 ok.
455 458
456 This is a composite request that it creates the destination file 459 This is a composite request that creates the destination file with
457 with mode 0200 and copies the contents of the source file into it 460 mode 0200 and copies the contents of the source file into it using
458 using "aio_sendfile", followed by restoring atime, mtime, access 461 "aio_sendfile", followed by restoring atime, mtime, access mode and
459 mode and uid/gid, in that order. 462 uid/gid, in that order.
460 463
461 If an error occurs, the partial destination file will be unlinked, 464 If an error occurs, the partial destination file will be unlinked,
462 if possible, except when setting atime, mtime, access mode and 465 if possible, except when setting atime, mtime, access mode and
463 uid/gid, where errors are being ignored. 466 uid/gid, where errors are being ignored.
464 467
465 aio_move $srcpath, $dstpath, $callback->($status) 468 aio_move $srcpath, $dstpath, $callback->($status)
466 Try to move the *file* (directories not supported as either source 469 Try to move the *file* (directories not supported as either source
467 or destination) from $srcpath to $dstpath and call the callback with 470 or destination) from $srcpath to $dstpath and call the callback with
468 the 0 (error) or -1 ok. 471 the 0 (error) or -1 ok.
469 472
470 This is a composite request that tries to rename(2) the file first. 473 This is a composite request that tries to rename(2) the file first;
471 If rename files with "EXDEV", it copies the file with "aio_copy" 474 if rename fails with "EXDEV", it copies the file with "aio_copy"
472 and, if that is successful, unlinking the $srcpath. 475 and, if that is successful, unlinks the $srcpath.
473 476
474 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 477 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
475 Scans a directory (similar to "aio_readdir") but additionally tries 478 Scans a directory (similar to "aio_readdir") but additionally tries
476 to efficiently separate the entries of directory $path into two sets 479 to efficiently separate the entries of directory $path into two sets
477 of names, directories you can recurse into (directories), and ones 480 of names, directories you can recurse into (directories), and ones
… …
542 callback with the fdatasync result code. 545 callback with the fdatasync result code.
543 546
544 If this call isn't available because your OS lacks it or it couldn't 547 If this call isn't available because your OS lacks it or it couldn't
545 be detected, it will be emulated by calling "fsync" instead. 548 be detected, it will be emulated by calling "fsync" instead.
546 549
550 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
551 Sync the data portion of the file specified by $offset and $length
552 to disk (but NOT the metadata), by calling the Linux-specific
553 sync_file_range call. If sync_file_range is not available or it
554 returns ENOSYS, then fdatasync or fsync is being substituted.
555
556 $flags can be a combination of
557 "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
558 "IO::AIO::SYNC_FILE_RANGE_WRITE" and
559 "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
560 manpage for details.
561
547 aio_pathsync $path, $callback->($status) 562 aio_pathsync $path, $callback->($status)
548 This request tries to open, fsync and close the given path. This is 563 This request tries to open, fsync and close the given path. This is
549 a composite request intended tosync directories after directory 564 a composite request intended to sync directories after directory
550 operations (E.g. rename). This might not work on all operating 565 operations (E.g. rename). This might not work on all operating
551 systems or have any specific effect, but usually it makes sure that 566 systems or have any specific effect, but usually it makes sure that
552 directory changes get written to disc. It works for anything that 567 directory changes get written to disc. It works for anything that
553 can be opened for read-only, not just directories. 568 can be opened for read-only, not just directories.
554 569
… …
658 Their lifetime, simplified, looks like this: when they are empty, they 673 Their lifetime, simplified, looks like this: when they are empty, they
659 will finish very quickly. If they contain only requests that are in the 674 will finish very quickly. If they contain only requests that are in the
660 "done" state, they will also finish. Otherwise they will continue to 675 "done" state, they will also finish. Otherwise they will continue to
661 exist. 676 exist.
662 677
663 That means after creating a group you have some time to add requests. 678 That means after creating a group you have some time to add requests
664 And in the callbacks of those requests, you can add further requests to 679 (precisely before the callback has been invoked, which is only done
665 the group. And only when all those requests have finished will the the 680 within the "poll_cb"). And in the callbacks of those requests, you can
666 group itself finish. 681 add further requests to the group. And only when all those requests have
682 finished will the the group itself finish.
667 683
668 add $grp ... 684 add $grp ...
669 $grp->add (...) 685 $grp->add (...)
670 Add one or more requests to the group. Any type of IO::AIO::REQ can 686 Add one or more requests to the group. Any type of IO::AIO::REQ can
671 be added, including other groups, as long as you do not create 687 be added, including other groups, as long as you do not create
… …
714 does not impose any limits). 730 does not impose any limits).
715 731
716 If the feed does not queue more requests when called, it will be 732 If the feed does not queue more requests when called, it will be
717 automatically removed from the group. 733 automatically removed from the group.
718 734
719 If the feed limit is 0, it will be set to 2 automatically. 735 If the feed limit is 0 when this method is called, it will be set to
736 2 automatically.
720 737
721 Example: 738 Example:
722 739
723 # stat all files in @files, but only ever use four aio requests concurrently: 740 # stat all files in @files, but only ever use four aio requests concurrently:
724 741
… …
734 limit $grp $num 751 limit $grp $num
735 Sets the feeder limit for the group: The feeder will be called 752 Sets the feeder limit for the group: The feeder will be called
736 whenever the group contains less than this many requests. 753 whenever the group contains less than this many requests.
737 754
738 Setting the limit to 0 will pause the feeding process. 755 Setting the limit to 0 will pause the feeding process.
756
757 The default value for the limit is 0, but note that setting a feeder
758 automatically bumps it up to 2.
739 759
740 SUPPORT FUNCTIONS 760 SUPPORT FUNCTIONS
741 EVENT PROCESSING AND EVENT LOOP INTEGRATION 761 EVENT PROCESSING AND EVENT LOOP INTEGRATION
742 $fileno = IO::AIO::poll_fileno 762 $fileno = IO::AIO::poll_fileno
743 Return the *request result pipe file descriptor*. This filehandle 763 Return the *request result pipe file descriptor*. This filehandle

Diff Legend

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