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.260 by root, Sun May 1 17:19:39 2016 UTC vs.
Revision 1.267 by root, Tue Aug 9 11:39:17 2016 UTC

1=head1 NAME 1=head1 NAME
2 2
3IO::AIO - Asynchronous Input/Output 3IO::AIO - Asynchronous/Advanced Input/Output
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use IO::AIO; 7 use IO::AIO;
8 8
… …
57functions available on many operating systems. However, they are often 57functions available on many operating systems. However, they are often
58not well-supported or restricted (GNU/Linux doesn't allow them on normal 58not well-supported or restricted (GNU/Linux doesn't allow them on normal
59files currently, for example), and they would only support aio_read and 59files currently, for example), and they would only support aio_read and
60aio_write, so the remaining functionality would have to be implemented 60aio_write, so the remaining functionality would have to be implemented
61using threads anyway. 61using threads anyway.
62
63In addition to asynchronous I/O, this module also exports some rather
64arcane interfaces, such as C<madvise> or linux's C<splice> system call,
65which is why the C<A> in C<AIO> can also mean I<advanced>.
62 66
63Although the module will work in the presence of other (Perl-) threads, 67Although the module will work in the presence of other (Perl-) threads,
64it is currently not reentrant in any way, so use appropriate locking 68it is currently not reentrant in any way, so use appropriate locking
65yourself, always call C<poll_cb> from within the same thread, or never 69yourself, always call C<poll_cb> from within the same thread, or never
66call C<poll_cb> (or other C<aio_> functions) recursively. 70call C<poll_cb> (or other C<aio_> functions) recursively.
… …
441=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 445=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
442 446
443=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 447=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
444 448
445Reads or writes C<$length> bytes from or to the specified C<$fh> and 449Reads or writes C<$length> bytes from or to the specified C<$fh> and
446C<$offset> into the scalar given by C<$data> and offset C<$dataoffset> 450C<$offset> into the scalar given by C<$data> and offset C<$dataoffset> and
447and calls the callback without the actual number of bytes read (or -1 on 451calls the callback with the actual number of bytes transferred (or -1 on
448error, just like the syscall). 452error, just like the syscall).
449 453
450C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to 454C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to
451offset plus the actual number of bytes read. 455offset plus the actual number of bytes read.
452 456
… …
510As native sendfile syscalls (as practically any non-POSIX interface hacked 514As native sendfile syscalls (as practically any non-POSIX interface hacked
511together in a hurry to improve benchmark numbers) tend to be rather buggy 515together in a hurry to improve benchmark numbers) tend to be rather buggy
512on many systems, this implementation tries to work around some known bugs 516on many systems, this implementation tries to work around some known bugs
513in Linux and FreeBSD kernels (probably others, too), but that might fail, 517in Linux and FreeBSD kernels (probably others, too), but that might fail,
514so you really really should check the return value of C<aio_sendfile> - 518so you really really should check the return value of C<aio_sendfile> -
515fewre bytes than expected might have been transferred. 519fewer bytes than expected might have been transferred.
516 520
517 521
518=item aio_readahead $fh,$offset,$length, $callback->($retval) 522=item aio_readahead $fh,$offset,$length, $callback->($retval)
519 523
520C<aio_readahead> populates the page cache with data from a file so that 524C<aio_readahead> populates the page cache with data from a file so that
… …
524whole pages, so that offset is effectively rounded down to a page boundary 528whole pages, so that offset is effectively rounded down to a page boundary
525and bytes are read up to the next page boundary greater than or equal to 529and bytes are read up to the next page boundary greater than or equal to
526(off-set+length). C<aio_readahead> does not read beyond the end of the 530(off-set+length). C<aio_readahead> does not read beyond the end of the
527file. The current file offset of the file is left unchanged. 531file. The current file offset of the file is left unchanged.
528 532
529If that syscall doesn't exist (likely if your OS isn't Linux) it will be 533If that syscall doesn't exist (likely if your kernel isn't Linux) it will
530emulated by simply reading the data, which would have a similar effect. 534be emulated by simply reading the data, which would have a similar effect.
531 535
532 536
533=item aio_stat $fh_or_path, $callback->($status) 537=item aio_stat $fh_or_path, $callback->($status)
534 538
535=item aio_lstat $fh, $callback->($status) 539=item aio_lstat $fh, $callback->($status)
… …
1248So in general, you should only use these calls for things that do 1252So in general, you should only use these calls for things that do
1249(filesystem) I/O, not for things that wait for other events (network, 1253(filesystem) I/O, not for things that wait for other events (network,
1250other processes), although if you are careful and know what you are doing, 1254other processes), although if you are careful and know what you are doing,
1251you still can. 1255you still can.
1252 1256
1257The following constants are available (missing ones are, as usual C<0>):
1258
1259C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
1260
1261C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1262C<FS_IOC_FIEMAP>.
1263
1264C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
1265C<FS_IOC_GET_ENCRYPTION_PWSALT>, C<FS_IOC_GET_ENCRYPTION_POLICY>, C<FS_KEY_DESCRIPTOR_SIZE>.
1266
1267C<FS_SECRM_FL>, C<FS_UNRM_FL>, C<FS_COMPR_FL>, C<FS_SYNC_FL>, C<FS_IMMUTABLE_FL>,
1268C<FS_APPEND_FL>, C<FS_NODUMP_FL>, C<FS_NOATIME_FL>, C<FS_DIRTY_FL>,
1269C<FS_COMPRBLK_FL>, C<FS_NOCOMP_FL>, C<FS_ENCRYPT_FL>, C<FS_BTREE_FL>,
1270C<FS_INDEX_FL>, C<FS_JOURNAL_DATA_FL>, C<FS_NOTAIL_FL>, C<FS_DIRSYNC_FL>, C<FS_TOPDIR_FL>,
1271C<FS_FL_USER_MODIFIABLE>.
1272
1273C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1274C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1275C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1276C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
1277
1253=item aio_sync $callback->($status) 1278=item aio_sync $callback->($status)
1254 1279
1255Asynchronously call sync and call the callback when finished. 1280Asynchronously call sync and call the callback when finished.
1256 1281
1257=item aio_fsync $fh, $callback->($status) 1282=item aio_fsync $fh, $callback->($status)
… …
2041=item IO::AIO::madvise $scalar, $offset, $len, $advice 2066=item IO::AIO::madvise $scalar, $offset, $len, $advice
2042 2067
2043Simply calls the C<posix_madvise> function (see its 2068Simply calls the C<posix_madvise> function (see its
2044manpage for details). The following advice constants are 2069manpage for details). The following advice constants are
2045available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>, 2070available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
2046C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>. 2071C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>,
2072C<IO::AIO::MADV_FREE>.
2047 2073
2048On systems that do not implement C<posix_madvise>, this function returns 2074On systems that do not implement C<posix_madvise>, this function returns
2049ENOSYS, otherwise the return value of C<posix_madvise>. 2075ENOSYS, otherwise the return value of C<posix_madvise>.
2050 2076
2051=item IO::AIO::mprotect $scalar, $offset, $len, $protect 2077=item IO::AIO::mprotect $scalar, $offset, $len, $protect

Diff Legend

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