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.33 by root, Sun Oct 12 22:40:52 2008 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
… …
451 aio_copy $srcpath, $dstpath, $callback->($status) 451 aio_copy $srcpath, $dstpath, $callback->($status)
452 Try to copy the *file* (directories not supported as either source 452 Try to copy the *file* (directories not supported as either source
453 or destination) from $srcpath to $dstpath and call the callback with 453 or destination) from $srcpath to $dstpath and call the callback with
454 the 0 (error) or -1 ok. 454 the 0 (error) or -1 ok.
455 455
456 This is a composite request that it creates the destination file 456 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 457 mode 0200 and copies the contents of the source file into it using
458 using "aio_sendfile", followed by restoring atime, mtime, access 458 "aio_sendfile", followed by restoring atime, mtime, access mode and
459 mode and uid/gid, in that order. 459 uid/gid, in that order.
460 460
461 If an error occurs, the partial destination file will be unlinked, 461 If an error occurs, the partial destination file will be unlinked,
462 if possible, except when setting atime, mtime, access mode and 462 if possible, except when setting atime, mtime, access mode and
463 uid/gid, where errors are being ignored. 463 uid/gid, where errors are being ignored.
464 464
465 aio_move $srcpath, $dstpath, $callback->($status) 465 aio_move $srcpath, $dstpath, $callback->($status)
466 Try to move the *file* (directories not supported as either source 466 Try to move the *file* (directories not supported as either source
467 or destination) from $srcpath to $dstpath and call the callback with 467 or destination) from $srcpath to $dstpath and call the callback with
468 the 0 (error) or -1 ok. 468 the 0 (error) or -1 ok.
469 469
470 This is a composite request that tries to rename(2) the file first. 470 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" 471 if rename fails with "EXDEV", it copies the file with "aio_copy"
472 and, if that is successful, unlinking the $srcpath. 472 and, if that is successful, unlinks the $srcpath.
473 473
474 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 474 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
475 Scans a directory (similar to "aio_readdir") but additionally tries 475 Scans a directory (similar to "aio_readdir") but additionally tries
476 to efficiently separate the entries of directory $path into two sets 476 to efficiently separate the entries of directory $path into two sets
477 of names, directories you can recurse into (directories), and ones 477 of names, directories you can recurse into (directories), and ones
… …
544 If this call isn't available because your OS lacks it or it couldn't 544 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. 545 be detected, it will be emulated by calling "fsync" instead.
546 546
547 aio_pathsync $path, $callback->($status) 547 aio_pathsync $path, $callback->($status)
548 This request tries to open, fsync and close the given path. This is 548 This request tries to open, fsync and close the given path. This is
549 a composite request intended tosync directories after directory 549 a composite request intended to sync directories after directory
550 operations (E.g. rename). This might not work on all operating 550 operations (E.g. rename). This might not work on all operating
551 systems or have any specific effect, but usually it makes sure that 551 systems or have any specific effect, but usually it makes sure that
552 directory changes get written to disc. It works for anything that 552 directory changes get written to disc. It works for anything that
553 can be opened for read-only, not just directories. 553 can be opened for read-only, not just directories.
554 554
… …
658 Their lifetime, simplified, looks like this: when they are empty, they 658 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 659 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 660 "done" state, they will also finish. Otherwise they will continue to
661 exist. 661 exist.
662 662
663 That means after creating a group you have some time to add requests. 663 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 664 (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 665 within the "poll_cb"). And in the callbacks of those requests, you can
666 group itself finish. 666 add further requests to the group. And only when all those requests have
667 finished will the the group itself finish.
667 668
668 add $grp ... 669 add $grp ...
669 $grp->add (...) 670 $grp->add (...)
670 Add one or more requests to the group. Any type of IO::AIO::REQ can 671 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 672 be added, including other groups, as long as you do not create
… …
714 does not impose any limits). 715 does not impose any limits).
715 716
716 If the feed does not queue more requests when called, it will be 717 If the feed does not queue more requests when called, it will be
717 automatically removed from the group. 718 automatically removed from the group.
718 719
719 If the feed limit is 0, it will be set to 2 automatically. 720 If the feed limit is 0 when this method is called, it will be set to
721 2 automatically.
720 722
721 Example: 723 Example:
722 724
723 # stat all files in @files, but only ever use four aio requests concurrently: 725 # stat all files in @files, but only ever use four aio requests concurrently:
724 726
… …
734 limit $grp $num 736 limit $grp $num
735 Sets the feeder limit for the group: The feeder will be called 737 Sets the feeder limit for the group: The feeder will be called
736 whenever the group contains less than this many requests. 738 whenever the group contains less than this many requests.
737 739
738 Setting the limit to 0 will pause the feeding process. 740 Setting the limit to 0 will pause the feeding process.
741
742 The default value for the limit is 0, but note that setting a feeder
743 automatically bumps it up to 2.
739 744
740 SUPPORT FUNCTIONS 745 SUPPORT FUNCTIONS
741 EVENT PROCESSING AND EVENT LOOP INTEGRATION 746 EVENT PROCESSING AND EVENT LOOP INTEGRATION
742 $fileno = IO::AIO::poll_fileno 747 $fileno = IO::AIO::poll_fileno
743 Return the *request result pipe file descriptor*. This filehandle 748 Return the *request result pipe file descriptor*. This filehandle

Diff Legend

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