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

Comparing IO-AIO/README (file contents):
Revision 1.34 by root, Thu Nov 20 09:01:40 2008 UTC vs.
Revision 1.37 by root, Fri Jun 12 16:55:17 2009 UTC

… …
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
… …
439 aio_readdir $pathname, $callback->($entries) 442 aio_readdir $pathname, $callback->($entries)
440 Unlike the POSIX call of the same name, "aio_readdir" reads an 443 Unlike the POSIX call of the same name, "aio_readdir" reads an
441 entire directory (i.e. opendir + readdir + closedir). The entries 444 entire directory (i.e. opendir + readdir + closedir). The entries
442 will not be sorted, and will NOT include the "." and ".." entries. 445 will not be sorted, and will NOT include the "." and ".." entries.
443 446
444 The callback a single argument which is either "undef" or an 447 The callback is passed a single argument which is either "undef" or
445 array-ref with the filenames. 448 an array-ref with the filenames.
449
450 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
451 Quite similar to "aio_readdir", but the $flags argument allows to
452 tune behaviour and output format. In case of an error, $entries will
453 be "undef".
454
455 The flags are a combination of the following constants, ORed
456 together (the flags will also be passed to the callback, possibly
457 modified):
458
459 IO::AIO::READDIR_DENTS
460 When this flag is off, then the callback gets an arrayref with
461 of names only (as with "aio_readdir"), otherwise it gets an
462 arrayref with "[$name, $type, $inode]" arrayrefs, each
463 describing a single directory entry in more detail.
464
465 $name is the name of the entry.
466
467 $type is one of the "IO::AIO::DT_xxx" constants:
468
469 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
470 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
471 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
472
473 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
474 you need to know, you have to run stat yourself. Also, for speed
475 reasons, the $type scalars are read-only: you can not modify
476 them.
477
478 $inode is the inode number (which might not be exact on systems
479 with 64 bit inode numbers and 32 bit perls). On systems that do
480 not deliver the inode information, this will always be zero.
481
482 IO::AIO::READDIR_DIRS_FIRST
483 When this flag is set, then the names will be returned in an
484 order where likely directories come first. This is useful when
485 you need to quickly find directories, or you want to find all
486 directories while avoiding to stat() each entry.
487
488 If the system returns type information in readdir, then this is
489 used to find directories directly. Otherwise, likely directories
490 are files beginning with ".", or otherwise files with no dots,
491 of which files with short names are tried first.
492
493 IO::AIO::READDIR_STAT_ORDER
494 When this flag is set, then the names will be returned in an
495 order suitable for stat()'ing each one. That is, when you plan
496 to stat() all files in the given directory, then the returned
497 order will likely be fastest.
498
499 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
500 specified, then the likely dirs come first, resulting in a less
501 optimal stat order.
502
503 IO::AIO::READDIR_FOUND_UNKNOWN
504 This flag should not be set when calling "aio_readdirx".
505 Instead, it is being set by "aio_readdirx", when any of the
506 $type's found were "IO::AIO::DT_UNKNOWN". The absense of this
507 flag therefore indicates that all $type's are known, which can
508 be used to speed up some algorithms.
446 509
447 aio_load $path, $data, $callback->($status) 510 aio_load $path, $data, $callback->($status)
448 This is a composite request that tries to fully load the given file 511 This is a composite request that tries to fully load the given file
449 into memory. Status is the same as with aio_read. 512 into memory. Status is the same as with aio_read.
450 513
… …
497 Implementation notes. 560 Implementation notes.
498 561
499 The "aio_readdir" cannot be avoided, but "stat()"'ing every entry 562 The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
500 can. 563 can.
501 564
565 If readdir returns file type information, then this is used directly
566 to find directories.
567
502 After reading the directory, the modification time, size etc. of the 568 Otherwise, after reading the directory, the modification time, size
503 directory before and after the readdir is checked, and if they match 569 etc. of the directory before and after the readdir is checked, and
504 (and isn't the current time), the link count will be used to decide 570 if they match (and isn't the current time), the link count will be
505 how many entries are directories (if >= 2). Otherwise, no knowledge 571 used to decide how many entries are directories (if >= 2).
506 of the number of subdirectories will be assumed. 572 Otherwise, no knowledge of the number of subdirectories will be
573 assumed.
507 574
508 Then entries will be sorted into likely directories (everything 575 Then entries will be sorted into likely directories a non-initial
509 without a non-initial dot currently) and likely non-directories 576 dot currently) and likely non-directories (see "aio_readdirx"). Then
510 (everything else). Then every entry plus an appended "/." will be 577 every entry plus an appended "/." will be "stat"'ed, likely
511 "stat"'ed, likely directories first. If that succeeds, it assumes 578 directories first, in order of their inode numbers. If that
512 that the entry is a directory or a symlink to directory (which will 579 succeeds, it assumes that the entry is a directory or a symlink to
513 be checked seperately). This is often faster than stat'ing the entry 580 directory (which will be checked seperately). This is often faster
514 itself because filesystems might detect the type of the entry 581 than stat'ing the entry itself because filesystems might detect the
515 without reading the inode data (e.g. ext2fs filetype feature). 582 type of the entry without reading the inode data (e.g. ext2fs
583 filetype feature), even on systems that cannot return the filetype
584 information on readdir.
516 585
517 If the known number of directories (link count - 2) has been 586 If the known number of directories (link count - 2) has been
518 reached, the rest of the entries is assumed to be non-directories. 587 reached, the rest of the entries is assumed to be non-directories.
519 588
520 This only works with certainty on POSIX (= UNIX) filesystems, which 589 This only works with certainty on POSIX (= UNIX) filesystems, which
… …
615 684
616 cancel $req 685 cancel $req
617 Cancels the request, if possible. Has the effect of skipping 686 Cancels the request, if possible. Has the effect of skipping
618 execution when entering the execute state and skipping calling the 687 execution when entering the execute state and skipping calling the
619 callback when entering the the result state, but will leave the 688 callback when entering the the result state, but will leave the
620 request otherwise untouched. That means that requests that currently 689 request otherwise untouched (with the exception of readdir). That
621 execute will not be stopped and resources held by the request will 690 means that requests that currently execute will not be stopped and
622 not be freed prematurely. 691 resources held by the request will not be freed prematurely.
623 692
624 cb $req $callback->(...) 693 cb $req $callback->(...)
625 Replace (or simply set) the callback registered to the request. 694 Replace (or simply set) the callback registered to the request.
626 695
627 IO::AIO::GRP CLASS 696 IO::AIO::GRP CLASS

Diff Legend

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