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

Comparing IO-AIO/README (file contents):
Revision 1.50 by root, Sun Oct 9 08:24:49 2011 UTC vs.
Revision 1.53 by root, Thu Oct 11 03:20:52 2012 UTC

… …
146 the actual aio request is severed and calling its methods will 146 the actual aio request is severed and calling its methods will
147 either do nothing or result in a runtime error). 147 either do nothing or result in a runtime error).
148 148
149FUNCTIONS 149FUNCTIONS
150 QUICK OVERVIEW 150 QUICK OVERVIEW
151 This section simply lists the prototypes of the most important functions 151 This section simply lists the prototypes most of the functions for quick
152 for quick reference. See the following sections for function-by-function 152 reference. See the following sections for function-by-function
153 documentation. 153 documentation.
154 154
155 aio_wd $pathname, $callback->($wd) 155 aio_wd $pathname, $callback->($wd)
156 aio_open $pathname, $flags, $mode, $callback->($fh) 156 aio_open $pathname, $flags, $mode, $callback->($fh)
157 aio_close $fh, $callback->($status) 157 aio_close $fh, $callback->($status)
158 aio_seek $fh,$offset,$whence, $callback->($offs)
158 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 159 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
159 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 160 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
160 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 161 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
161 aio_readahead $fh,$offset,$length, $callback->($retval) 162 aio_readahead $fh,$offset,$length, $callback->($retval)
162 aio_stat $fh_or_path, $callback->($status) 163 aio_stat $fh_or_path, $callback->($status)
163 aio_lstat $fh, $callback->($status) 164 aio_lstat $fh, $callback->($status)
164 aio_statvfs $fh_or_path, $callback->($statvfs) 165 aio_statvfs $fh_or_path, $callback->($statvfs)
165 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 166 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
166 aio_chown $fh_or_path, $uid, $gid, $callback->($status) 167 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
168 aio_chmod $fh_or_path, $mode, $callback->($status)
167 aio_truncate $fh_or_path, $offset, $callback->($status) 169 aio_truncate $fh_or_path, $offset, $callback->($status)
168 aio_chmod $fh_or_path, $mode, $callback->($status) 170 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
171 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
169 aio_unlink $pathname, $callback->($status) 172 aio_unlink $pathname, $callback->($status)
170 aio_mknod $pathname, $mode, $dev, $callback->($status) 173 aio_mknod $pathname, $mode, $dev, $callback->($status)
171 aio_link $srcpath, $dstpath, $callback->($status) 174 aio_link $srcpath, $dstpath, $callback->($status)
172 aio_symlink $srcpath, $dstpath, $callback->($status) 175 aio_symlink $srcpath, $dstpath, $callback->($status)
173 aio_readlink $pathname, $callback->($link) 176 aio_readlink $pathname, $callback->($link)
… …
215 IO::AIO::nready 218 IO::AIO::nready
216 IO::AIO::npending 219 IO::AIO::npending
217 220
218 IO::AIO::sendfile $ofh, $ifh, $offset, $count 221 IO::AIO::sendfile $ofh, $ifh, $offset, $count
219 IO::AIO::fadvise $fh, $offset, $len, $advice 222 IO::AIO::fadvise $fh, $offset, $len, $advice
223 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
224 IO::AIO::munmap $scalar
220 IO::AIO::madvise $scalar, $offset, $length, $advice 225 IO::AIO::madvise $scalar, $offset, $length, $advice
221 IO::AIO::mprotect $scalar, $offset, $length, $protect 226 IO::AIO::mprotect $scalar, $offset, $length, $protect
222 IO::AIO::munlock $scalar, $offset = 0, $length = undef 227 IO::AIO::munlock $scalar, $offset = 0, $length = undef
223 IO::AIO::munlockall 228 IO::AIO::munlockall
224 229
225 AIO REQUEST FUNCTIONS 230 API NOTES
226 All the "aio_*" calls are more or less thin wrappers around the syscall 231 All the "aio_*" calls are more or less thin wrappers around the syscall
227 with the same name (sans "aio_"). The arguments are similar or 232 with the same name (sans "aio_"). The arguments are similar or
228 identical, and they all accept an additional (and optional) $callback 233 identical, and they all accept an additional (and optional) $callback
229 argument which must be a code reference. This code reference will be 234 argument which must be a code reference. This code reference will be
230 called after the syscall has been executed in an asynchronous fashion. 235 called after the syscall has been executed in an asynchronous fashion.
… …
260 else to ensure your scalar has the correct contents. 265 else to ensure your scalar has the correct contents.
261 266
262 This works, btw. independent of the internal UTF-8 bit, which IO::AIO 267 This works, btw. independent of the internal UTF-8 bit, which IO::AIO
263 handles correctly whether it is set or not. 268 handles correctly whether it is set or not.
264 269
270 AIO REQUEST FUNCTIONS
265 $prev_pri = aioreq_pri [$pri] 271 $prev_pri = aioreq_pri [$pri]
266 Returns the priority value that would be used for the next request 272 Returns the priority value that would be used for the next request
267 and, if $pri is given, sets the priority for the next aio request. 273 and, if $pri is given, sets the priority for the next aio request.
268 274
269 The default priority is 0, the minimum and maximum priorities are -4 275 The default priority is 0, the minimum and maximum priorities are -4
… …
291 Similar to "aioreq_pri", but subtracts the given value from the 297 Similar to "aioreq_pri", but subtracts the given value from the
292 current priority, so the effect is cumulative. 298 current priority, so the effect is cumulative.
293 299
294 aio_open $pathname, $flags, $mode, $callback->($fh) 300 aio_open $pathname, $flags, $mode, $callback->($fh)
295 Asynchronously open or create a file and call the callback with a 301 Asynchronously open or create a file and call the callback with a
296 newly created filehandle for the file. 302 newly created filehandle for the file (or "undef" in case of an
303 error).
297 304
298 The pathname passed to "aio_open" must be absolute. See API NOTES, 305 The pathname passed to "aio_open" must be absolute. See API NOTES,
299 above, for an explanation. 306 above, for an explanation.
300 307
301 The $flags argument is a bitmask. See the "Fcntl" module for a list. 308 The $flags argument is a bitmask. See the "Fcntl" module for a list.
… …
340 will use dup2 to overwrite the file descriptor with the write-end of 347 will use dup2 to overwrite the file descriptor with the write-end of
341 a pipe (the pipe fd will be created on demand and will be cached). 348 a pipe (the pipe fd will be created on demand and will be cached).
342 349
343 Or in other words: the file descriptor will be closed, but it will 350 Or in other words: the file descriptor will be closed, but it will
344 not be free for reuse until the perl filehandle is closed. 351 not be free for reuse until the perl filehandle is closed.
352
353 aio_seek $fh, $offset, $whence, $callback->($offs)
354 Seeks the filehandle to the new $offset, similarly to perl's
355 "sysseek". The $whence can use the traditional values (0 for
356 "IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for
357 "IO::AIO::SEEK_END").
358
359 The resulting absolute offset will be passed to the callback, or -1
360 in case of an error.
361
362 In theory, the $whence constants could be different than the
363 corresponding values from Fcntl, but perl guarantees they are the
364 same, so don't panic.
365
366 As a GNU/Linux (and maybe Solaris) extension, also the constants
367 "IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if they
368 could be found. No guarantees about suitability for use in
369 "aio_seek" or Perl's "sysseek" can be made though, although I would
370 naively assume they "just work".
345 371
346 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 372 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
347 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 373 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
348 Reads or writes $length bytes from or to the specified $fh and 374 Reads or writes $length bytes from or to the specified $fh and
349 $offset into the scalar given by $data and offset $dataoffset and 375 $offset into the scalar given by $data and offset $dataoffset and
… …
504 namemax => 255, 530 namemax => 255,
505 frsize => 1024, 531 frsize => 1024,
506 fsid => 1810 532 fsid => 1810
507 } 533 }
508 534
535 Here is a (likely partial) list of fsid values used by Linux - it is
536 safe to hardcode these when the $^O is "linux":
537
538 0x0000adf5 adfs
539 0x0000adff affs
540 0x5346414f afs
541 0x09041934 anon-inode filesystem
542 0x00000187 autofs
543 0x42465331 befs
544 0x1badface bfs
545 0x42494e4d binfmt_misc
546 0x9123683e btrfs
547 0x0027e0eb cgroupfs
548 0xff534d42 cifs
549 0x73757245 coda
550 0x012ff7b7 coh
551 0x28cd3d45 cramfs
552 0x453dcd28 cramfs-wend (wrong endianness)
553 0x64626720 debugfs
554 0x00001373 devfs
555 0x00001cd1 devpts
556 0x0000f15f ecryptfs
557 0x00414a53 efs
558 0x0000137d ext
559 0x0000ef53 ext2/ext3
560 0x0000ef51 ext2
561 0x00004006 fat
562 0x65735546 fuseblk
563 0x65735543 fusectl
564 0x0bad1dea futexfs
565 0x01161970 gfs2
566 0x47504653 gpfs
567 0x00004244 hfs
568 0xf995e849 hpfs
569 0x958458f6 hugetlbfs
570 0x2bad1dea inotifyfs
571 0x00009660 isofs
572 0x000072b6 jffs2
573 0x3153464a jfs
574 0x6b414653 k-afs
575 0x0bd00bd0 lustre
576 0x0000137f minix
577 0x0000138f minix 30 char names
578 0x00002468 minix v2
579 0x00002478 minix v2 30 char names
580 0x00004d5a minix v3
581 0x19800202 mqueue
582 0x00004d44 msdos
583 0x0000564c novell
584 0x00006969 nfs
585 0x6e667364 nfsd
586 0x00003434 nilfs
587 0x5346544e ntfs
588 0x00009fa1 openprom
589 0x7461636F ocfs2
590 0x00009fa0 proc
591 0x6165676c pstorefs
592 0x0000002f qnx4
593 0x858458f6 ramfs
594 0x52654973 reiserfs
595 0x00007275 romfs
596 0x67596969 rpc_pipefs
597 0x73636673 securityfs
598 0xf97cff8c selinux
599 0x0000517b smb
600 0x534f434b sockfs
601 0x73717368 squashfs
602 0x62656572 sysfs
603 0x012ff7b6 sysv2
604 0x012ff7b5 sysv4
605 0x01021994 tmpfs
606 0x15013346 udf
607 0x00011954 ufs
608 0x54190100 ufs byteswapped
609 0x00009fa2 usbdevfs
610 0x01021997 v9fs
611 0xa501fcf5 vxfs
612 0xabba1974 xenfs
613 0x012ff7b4 xenix
614 0x58465342 xfs
615 0x012fd16d xia
616
509 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 617 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
510 Works like perl's "utime" function (including the special case of 618 Works like perl's "utime" function (including the special case of
511 $atime and $mtime being undef). Fractional times are supported if 619 $atime and $mtime being undef). Fractional times are supported if
512 the underlying syscalls support them. 620 the underlying syscalls support them.
513 621
… …
534 # same as above: 642 # same as above:
535 aio_chown "path", 0, undef; 643 aio_chown "path", 0, undef;
536 644
537 aio_truncate $fh_or_path, $offset, $callback->($status) 645 aio_truncate $fh_or_path, $offset, $callback->($status)
538 Works like truncate(2) or ftruncate(2). 646 Works like truncate(2) or ftruncate(2).
647
648 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
649 Allocates or freed disk space according to the $mode argument. See
650 the linux "fallocate" docuemntation for details.
651
652 $mode can currently be 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to
653 allocate space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
654 IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
655
656 The file system block size used by "fallocate" is presumably the
657 "f_bsize" returned by "statvfs".
658
659 If "fallocate" isn't available or cannot be emulated (currently no
660 emulation will be attempted), passes -1 and sets $! to "ENOSYS".
539 661
540 aio_chmod $fh_or_path, $mode, $callback->($status) 662 aio_chmod $fh_or_path, $mode, $callback->($status)
541 Works like perl's "chmod" function. 663 Works like perl's "chmod" function.
542 664
543 aio_unlink $pathname, $callback->($status) 665 aio_unlink $pathname, $callback->($status)
… …
863 Example: asynchronously lock all current and future pages into 985 Example: asynchronously lock all current and future pages into
864 memory. 986 memory.
865 987
866 aio_mlockall IO::AIO::MCL_FUTURE; 988 aio_mlockall IO::AIO::MCL_FUTURE;
867 989
990 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
991 Queries the extents of the given file (by calling the Linux "FIEMAP"
992 ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
993 details). If the ioctl is not available on your OS, then this
994 request will fail with "ENOSYS".
995
996 $start is the starting offset to query extents for, $length is the
997 size of the range to query - if it is "undef", then the whole file
998 will be queried.
999
1000 $flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or
1001 "IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
1002 also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
1003 query the data portion.
1004
1005 $count is the maximum number of extent records to return. If it is
1006 "undef", then IO::AIO queries all extents of the range. As a very
1007 special case, if it is 0, then the callback receives the number of
1008 extents instead of the extents themselves (which is unreliable, see
1009 below).
1010
1011 If an error occurs, the callback receives no arguments. The special
1012 "errno" value "IO::AIO::EBADR" is available to test for flag errors.
1013
1014 Otherwise, the callback receives an array reference with extent
1015 structures. Each extent structure is an array reference itself, with
1016 the following members:
1017
1018 [$logical, $physical, $length, $flags]
1019
1020 Flags is any combination of the following flag values (typically
1021 either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
1022
1023 "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
1024 "IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
1025 "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
1026 "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
1027 "IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
1028 "IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
1029 "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
1030 or "IO::AIO::FIEMAP_EXTENT_SHARED".
1031
1032 At the time of this writing (Linux 3.2), this requets is unreliable
1033 unless $count is "undef", as the kernel has all sorts of bugs
1034 preventing it to return all extents of a range for files with large
1035 number of extents. The code works around all these issues if $count
1036 is undef.
1037
868 aio_group $callback->(...) 1038 aio_group $callback->(...)
869 This is a very special aio request: Instead of doing something, it 1039 This is a very special aio request: Instead of doing something, it
870 is a container for other aio requests, which is useful if you want 1040 is a container for other aio requests, which is useful if you want
871 to bundle many requests into a single, composite, request with a 1041 to bundle many requests into a single, composite, request with a
872 definite callback and the ability to cancel the whole request with 1042 definite callback and the ability to cancel the whole request with
… …
1412 On systems that do not implement "mprotect", this function returns 1582 On systems that do not implement "mprotect", this function returns
1413 ENOSYS, otherwise the return value of "mprotect". 1583 ENOSYS, otherwise the return value of "mprotect".
1414 1584
1415 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 1585 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1416 Memory-maps a file (or anonymous memory range) and attaches it to 1586 Memory-maps a file (or anonymous memory range) and attaches it to
1417 the given $scalar, which will act like a string scalar. 1587 the given $scalar, which will act like a string scalar. Returns true
1588 on success, and false otherwise.
1418 1589
1419 The only operations allowed on the scalar are "substr"/"vec" that 1590 The only operations allowed on the scalar are "substr"/"vec" that
1420 don't change the string length, and most read-only operations such 1591 don't change the string length, and most read-only operations such
1421 as copying it or searching it with regexes and so on. 1592 as copying it or searching it with regexes and so on.
1422 1593
… …
1472 IO::AIO::munlockall 1643 IO::AIO::munlockall
1473 Calls the "munlockall" function. 1644 Calls the "munlockall" function.
1474 1645
1475 On systems that do not implement "munlockall", this function returns 1646 On systems that do not implement "munlockall", this function returns
1476 ENOSYS, otherwise the return value of "munlockall". 1647 ENOSYS, otherwise the return value of "munlockall".
1648
1649 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1650 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1651 $w_off are "undef", then "NULL" is passed for these, otherwise they
1652 should be the file offset.
1653
1654 $r_fh and $w_fh should not refer to the same file, as splice might
1655 silently corrupt the data in this case.
1656
1657 The following symbol flag values are available:
1658 "IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
1659 "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
1660
1661 See the splice(2) manpage for details.
1662
1663 IO::AIO::tee $r_fh, $w_fh, $length, $flags
1664 Calls the GNU/Linux tee(2) syscall, see it's manpage and the
1665 description for "IO::AIO::splice" above for details.
1477 1666
1478EVENT LOOP INTEGRATION 1667EVENT LOOP INTEGRATION
1479 It is recommended to use AnyEvent::AIO to integrate IO::AIO 1668 It is recommended to use AnyEvent::AIO to integrate IO::AIO
1480 automatically into many event loops: 1669 automatically into many event loops:
1481 1670

Diff Legend

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