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.262 by root, Thu Jun 9 03:15:37 2016 UTC vs.
Revision 1.271 by root, Fri Jun 23 21:43:51 2017 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
… …
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 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>.
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.
67 71
… …
167use common::sense; 171use common::sense;
168 172
169use base 'Exporter'; 173use base 'Exporter';
170 174
171BEGIN { 175BEGIN {
172 our $VERSION = 4.34; 176 our $VERSION = 4.35;
173 177
174 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close 178 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
175 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 179 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
176 aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl 180 aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl
177 aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range 181 aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
178 aio_pathsync aio_readahead aio_fiemap aio_allocate 182 aio_pathsync aio_readahead aio_fiemap aio_allocate
179 aio_rename aio_link aio_move aio_copy aio_group 183 aio_rename aio_rename2 aio_link aio_move aio_copy aio_group
180 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown 184 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
181 aio_chmod aio_utime aio_truncate 185 aio_chmod aio_utime aio_truncate
182 aio_msync aio_mtouch aio_mlock aio_mlockall 186 aio_msync aio_mtouch aio_mlock aio_mlockall
183 aio_statvfs 187 aio_statvfs
184 aio_wd); 188 aio_wd);
… …
229 aio_link $srcpath, $dstpath, $callback->($status) 233 aio_link $srcpath, $dstpath, $callback->($status)
230 aio_symlink $srcpath, $dstpath, $callback->($status) 234 aio_symlink $srcpath, $dstpath, $callback->($status)
231 aio_readlink $pathname, $callback->($link) 235 aio_readlink $pathname, $callback->($link)
232 aio_realpath $pathname, $callback->($path) 236 aio_realpath $pathname, $callback->($path)
233 aio_rename $srcpath, $dstpath, $callback->($status) 237 aio_rename $srcpath, $dstpath, $callback->($status)
238 aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
234 aio_mkdir $pathname, $mode, $callback->($status) 239 aio_mkdir $pathname, $mode, $callback->($status)
235 aio_rmdir $pathname, $callback->($status) 240 aio_rmdir $pathname, $callback->($status)
236 aio_readdir $pathname, $callback->($entries) 241 aio_readdir $pathname, $callback->($entries)
237 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 242 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
238 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST 243 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
… …
248 aio_syncfs $fh, $callback->($status) 253 aio_syncfs $fh, $callback->($status)
249 aio_fsync $fh, $callback->($status) 254 aio_fsync $fh, $callback->($status)
250 aio_fdatasync $fh, $callback->($status) 255 aio_fdatasync $fh, $callback->($status)
251 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 256 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
252 aio_pathsync $pathname, $callback->($status) 257 aio_pathsync $pathname, $callback->($status)
253 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 258 aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
254 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 259 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
255 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 260 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
256 aio_mlockall $flags, $callback->($status) 261 aio_mlockall $flags, $callback->($status)
257 aio_group $callback->(...) 262 aio_group $callback->(...)
258 aio_nop $callback->() 263 aio_nop $callback->()
… …
441=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 446=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
442 447
443=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 448=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
444 449
445Reads or writes C<$length> bytes from or to the specified C<$fh> and 450Reads 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> 451C<$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 452calls the callback with the actual number of bytes transferred (or -1 on
448error, just like the syscall). 453error, just like the syscall).
449 454
450C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to 455C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to
451offset plus the actual number of bytes read. 456offset plus the actual number of bytes read.
452 457
… …
808On systems that support the AIO::WD working directory abstraction 813On systems that support the AIO::WD working directory abstraction
809natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead 814natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
810of failing, C<rename> is called on the absolute path of C<$wd>. 815of failing, C<rename> is called on the absolute path of C<$wd>.
811 816
812 817
818=item aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
819
820Basically a version of C<aio_rename> with an additional C<$flags>
821argument. Calling this with C<$flags=0> is the same as calling
822C<aio_rename>.
823
824Non-zero flags are currently only supported on GNU/Linux systems that
825support renameat2. Other systems fail with C<ENOSYS> in this case.
826
827The following constants are available (missing ones are, as usual C<0>),
828see renameat2(2) for details:
829
830C<IO::AIO::RENAME_NOREPLACE>, C<IO::AIO::RENAME_EXCHANGE>
831and C<IO::AIO::RENAME_WHITEOUT>.
832
833
813=item aio_mkdir $pathname, $mode, $callback->($status) 834=item aio_mkdir $pathname, $mode, $callback->($status)
814 835
815Asynchronously mkdir (create) a directory and call the callback with 836Asynchronously mkdir (create) a directory and call the callback with
816the result code. C<$mode> will be modified by the umask at the time the 837the result code. C<$mode> will be modified by the umask at the time the
817request is executed, so do not change your umask. 838request is executed, so do not change your umask.
… …
1248So in general, you should only use these calls for things that do 1269So 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, 1270(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, 1271other processes), although if you are careful and know what you are doing,
1251you still can. 1272you still can.
1252 1273
1274The following constants are available (missing ones are, as usual C<0>):
1275
1276C<F_DUPFD_CLOEXEC>,
1277
1278C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1279
1280C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
1281
1282C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1283C<FS_IOC_FIEMAP>.
1284
1285C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
1286C<FS_IOC_GET_ENCRYPTION_PWSALT>, C<FS_IOC_GET_ENCRYPTION_POLICY>, C<FS_KEY_DESCRIPTOR_SIZE>.
1287
1288C<FS_SECRM_FL>, C<FS_UNRM_FL>, C<FS_COMPR_FL>, C<FS_SYNC_FL>, C<FS_IMMUTABLE_FL>,
1289C<FS_APPEND_FL>, C<FS_NODUMP_FL>, C<FS_NOATIME_FL>, C<FS_DIRTY_FL>,
1290C<FS_COMPRBLK_FL>, C<FS_NOCOMP_FL>, C<FS_ENCRYPT_FL>, C<FS_BTREE_FL>,
1291C<FS_INDEX_FL>, C<FS_JOURNAL_DATA_FL>, C<FS_NOTAIL_FL>, C<FS_DIRSYNC_FL>, C<FS_TOPDIR_FL>,
1292C<FS_FL_USER_MODIFIABLE>.
1293
1294C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1295C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1296C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1297C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
1298
1253=item aio_sync $callback->($status) 1299=item aio_sync $callback->($status)
1254 1300
1255Asynchronously call sync and call the callback when finished. 1301Asynchronously call sync and call the callback when finished.
1256 1302
1257=item aio_fsync $fh, $callback->($status) 1303=item aio_fsync $fh, $callback->($status)
… …
1325 }; 1371 };
1326 1372
1327 $grp 1373 $grp
1328} 1374}
1329 1375
1330=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1376=item aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
1331 1377
1332This is a rather advanced IO::AIO call, which only works on mmap(2)ed 1378This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1333scalars (see the C<IO::AIO::mmap> function, although it also works on data 1379scalars (see the C<IO::AIO::mmap> function, although it also works on data
1334scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the 1380scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the
1335scalar must only be modified in-place while an aio operation is pending on 1381scalar must only be modified in-place while an aio operation is pending on
… …
1337 1383
1338It calls the C<msync> function of your OS, if available, with the memory 1384It calls the C<msync> function of your OS, if available, with the memory
1339area starting at C<$offset> in the string and ending C<$length> bytes 1385area starting at C<$offset> in the string and ending C<$length> bytes
1340later. If C<$length> is negative, counts from the end, and if C<$length> 1386later. If C<$length> is negative, counts from the end, and if C<$length>
1341is C<undef>, then it goes till the end of the string. The flags can be 1387is C<undef>, then it goes till the end of the string. The flags can be
1342a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and 1388either C<IO::AIO::MS_ASYNC> or C<IO::AIO::MS_SYNC>, plus an optional
1343C<IO::AIO::MS_SYNC>. 1389C<IO::AIO::MS_INVALIDATE>.
1344 1390
1345=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1391=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1346 1392
1347This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1393This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1348scalars. 1394scalars.
… …
2041=item IO::AIO::madvise $scalar, $offset, $len, $advice 2087=item IO::AIO::madvise $scalar, $offset, $len, $advice
2042 2088
2043Simply calls the C<posix_madvise> function (see its 2089Simply calls the C<posix_madvise> function (see its
2044manpage for details). The following advice constants are 2090manpage for details). The following advice constants are
2045available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>, 2091available: 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>. 2092C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>,
2093C<IO::AIO::MADV_FREE>.
2094
2095If C<$offset> is negative, counts from the end. If C<$length> is negative,
2096the remaining length of the C<$scalar> is used. If possible, C<$length>
2097will be reduced to fit into the C<$scalar>.
2047 2098
2048On systems that do not implement C<posix_madvise>, this function returns 2099On systems that do not implement C<posix_madvise>, this function returns
2049ENOSYS, otherwise the return value of C<posix_madvise>. 2100ENOSYS, otherwise the return value of C<posix_madvise>.
2050 2101
2051=item IO::AIO::mprotect $scalar, $offset, $len, $protect 2102=item IO::AIO::mprotect $scalar, $offset, $len, $protect
… …
2053Simply calls the C<mprotect> function on the preferably AIO::mmap'ed 2104Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
2054$scalar (see its manpage for details). The following protect 2105$scalar (see its manpage for details). The following protect
2055constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>, 2106constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
2056C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>. 2107C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
2057 2108
2109If C<$offset> is negative, counts from the end. If C<$length> is negative,
2110the remaining length of the C<$scalar> is used. If possible, C<$length>
2111will be reduced to fit into the C<$scalar>.
2112
2058On systems that do not implement C<mprotect>, this function returns 2113On systems that do not implement C<mprotect>, this function returns
2059ENOSYS, otherwise the return value of C<mprotect>. 2114ENOSYS, otherwise the return value of C<mprotect>.
2060 2115
2061=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 2116=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
2062 2117
2063Memory-maps a file (or anonymous memory range) and attaches it to the 2118Memory-maps a file (or anonymous memory range) and attaches it to the
2064given C<$scalar>, which will act like a string scalar. Returns true on 2119given C<$scalar>, which will act like a string scalar. Returns true on
2065success, and false otherwise. 2120success, and false otherwise.
2066 2121
2122The scalar must exist, but its contents do not matter - this means you
2123cannot use a nonexistant array or hash element. When in doubt, C<undef>
2124the scalar first.
2125
2067The only operations allowed on the scalar are C<substr>/C<vec> that don't 2126The only operations allowed on the mmapped scalar are C<substr>/C<vec>,
2068change the string length, and most read-only operations such as copying it 2127which don't change the string length, and most read-only operations such
2069or searching it with regexes and so on. 2128as copying it or searching it with regexes and so on.
2070 2129
2071Anything else is unsafe and will, at best, result in memory leaks. 2130Anything else is unsafe and will, at best, result in memory leaks.
2072 2131
2073The memory map associated with the C<$scalar> is automatically removed 2132The memory map associated with the C<$scalar> is automatically removed
2074when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or 2133when the C<$scalar> is undef'd or destroyed, or when the C<IO::AIO::mmap>
2075C<IO::AIO::munmap> functions are called. 2134or C<IO::AIO::munmap> functions are called on it.
2076 2135
2077This calls the C<mmap>(2) function internally. See your system's manual 2136This calls the C<mmap>(2) function internally. See your system's manual
2078page for details on the C<$length>, C<$prot> and C<$flags> parameters. 2137page for details on the C<$length>, C<$prot> and C<$flags> parameters.
2079 2138
2080The C<$length> must be larger than zero and smaller than the actual 2139The C<$length> must be larger than zero and smaller than the actual

Diff Legend

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