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.264 by root, Mon Jul 18 07:48:01 2016 UTC vs.
Revision 1.274 by root, Thu Sep 21 23:43:46 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
… …
735C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate 740C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate
736space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>, 741space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>,
737to deallocate a file range. 742to deallocate a file range.
738 743
739IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range 744IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range
740(without leaving a hole) and C<FALLOC_FL_ZERO_RANGE>, to zero a range (see 745(without leaving a hole), C<FALLOC_FL_ZERO_RANGE>, to zero a range,
741your L<fallocate(2)> manpage). 746C<FALLOC_FL_INSERT_RANGE> to insert a range and C<FALLOC_FL_UNSHARE_RANGE>
747to unshare shared blocks (see your L<fallocate(2)> manpage).
742 748
743The file system block size used by C<fallocate> is presumably the 749The file system block size used by C<fallocate> is presumably the
744C<f_bsize> returned by C<statvfs>. 750C<f_bsize> returned by C<statvfs>, but different filesystems and filetypes
751can dictate other limitations.
745 752
746If C<fallocate> isn't available or cannot be emulated (currently no 753If C<fallocate> isn't available or cannot be emulated (currently no
747emulation will be attempted), passes C<-1> and sets C<$!> to C<ENOSYS>. 754emulation will be attempted), passes C<-1> and sets C<$!> to C<ENOSYS>.
748 755
749 756
… …
806rename(2) and call the callback with the result code. 813rename(2) and call the callback with the result code.
807 814
808On systems that support the AIO::WD working directory abstraction 815On systems that support the AIO::WD working directory abstraction
809natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead 816natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
810of failing, C<rename> is called on the absolute path of C<$wd>. 817of failing, C<rename> is called on the absolute path of C<$wd>.
818
819
820=item aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
821
822Basically a version of C<aio_rename> with an additional C<$flags>
823argument. Calling this with C<$flags=0> is the same as calling
824C<aio_rename>.
825
826Non-zero flags are currently only supported on GNU/Linux systems that
827support renameat2. Other systems fail with C<ENOSYS> in this case.
828
829The following constants are available (missing ones are, as usual C<0>),
830see renameat2(2) for details:
831
832C<IO::AIO::RENAME_NOREPLACE>, C<IO::AIO::RENAME_EXCHANGE>
833and C<IO::AIO::RENAME_WHITEOUT>.
811 834
812 835
813=item aio_mkdir $pathname, $mode, $callback->($status) 836=item aio_mkdir $pathname, $mode, $callback->($status)
814 837
815Asynchronously mkdir (create) a directory and call the callback with 838Asynchronously mkdir (create) a directory and call the callback with
… …
1250other processes), although if you are careful and know what you are doing, 1273other processes), although if you are careful and know what you are doing,
1251you still can. 1274you still can.
1252 1275
1253The following constants are available (missing ones are, as usual C<0>): 1276The following constants are available (missing ones are, as usual C<0>):
1254 1277
1278C<F_DUPFD_CLOEXEC>,
1279
1280C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1281
1255C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>. 1282C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
1256 1283
1257C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>, 1284C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1258C<FS_IOC_FIEMAP>. 1285C<FS_IOC_FIEMAP>.
1259 1286
… …
1346 }; 1373 };
1347 1374
1348 $grp 1375 $grp
1349} 1376}
1350 1377
1351=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1378=item aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
1352 1379
1353This is a rather advanced IO::AIO call, which only works on mmap(2)ed 1380This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1354scalars (see the C<IO::AIO::mmap> function, although it also works on data 1381scalars (see the C<IO::AIO::mmap> function, although it also works on data
1355scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the 1382scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the
1356scalar must only be modified in-place while an aio operation is pending on 1383scalar must only be modified in-place while an aio operation is pending on
… …
1358 1385
1359It calls the C<msync> function of your OS, if available, with the memory 1386It calls the C<msync> function of your OS, if available, with the memory
1360area starting at C<$offset> in the string and ending C<$length> bytes 1387area starting at C<$offset> in the string and ending C<$length> bytes
1361later. If C<$length> is negative, counts from the end, and if C<$length> 1388later. If C<$length> is negative, counts from the end, and if C<$length>
1362is C<undef>, then it goes till the end of the string. The flags can be 1389is C<undef>, then it goes till the end of the string. The flags can be
1363a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and 1390either C<IO::AIO::MS_ASYNC> or C<IO::AIO::MS_SYNC>, plus an optional
1364C<IO::AIO::MS_SYNC>. 1391C<IO::AIO::MS_INVALIDATE>.
1365 1392
1366=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1393=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1367 1394
1368This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1395This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1369scalars. 1396scalars.
… …
1981This is a very bad function to use in interactive programs because it 2008This is a very bad function to use in interactive programs because it
1982blocks, and a bad way to reduce concurrency because it is inexact: Better 2009blocks, and a bad way to reduce concurrency because it is inexact: Better
1983use an C<aio_group> together with a feed callback. 2010use an C<aio_group> together with a feed callback.
1984 2011
1985Its main use is in scripts without an event loop - when you want to stat 2012Its main use is in scripts without an event loop - when you want to stat
1986a lot of files, you can write somehting like this: 2013a lot of files, you can write something like this:
1987 2014
1988 IO::AIO::max_outstanding 32; 2015 IO::AIO::max_outstanding 32;
1989 2016
1990 for my $path (...) { 2017 for my $path (...) {
1991 aio_stat $path , ...; 2018 aio_stat $path , ...;
… …
2062=item IO::AIO::madvise $scalar, $offset, $len, $advice 2089=item IO::AIO::madvise $scalar, $offset, $len, $advice
2063 2090
2064Simply calls the C<posix_madvise> function (see its 2091Simply calls the C<posix_madvise> function (see its
2065manpage for details). The following advice constants are 2092manpage for details). The following advice constants are
2066available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>, 2093available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
2067C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>, 2094C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>,
2068C<IO::AIO::MADV_FREE>. 2095C<IO::AIO::MADV_DONTNEED>.
2096
2097If C<$offset> is negative, counts from the end. If C<$length> is negative,
2098the remaining length of the C<$scalar> is used. If possible, C<$length>
2099will be reduced to fit into the C<$scalar>.
2069 2100
2070On systems that do not implement C<posix_madvise>, this function returns 2101On systems that do not implement C<posix_madvise>, this function returns
2071ENOSYS, otherwise the return value of C<posix_madvise>. 2102ENOSYS, otherwise the return value of C<posix_madvise>.
2072 2103
2073=item IO::AIO::mprotect $scalar, $offset, $len, $protect 2104=item IO::AIO::mprotect $scalar, $offset, $len, $protect
… …
2075Simply calls the C<mprotect> function on the preferably AIO::mmap'ed 2106Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
2076$scalar (see its manpage for details). The following protect 2107$scalar (see its manpage for details). The following protect
2077constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>, 2108constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
2078C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>. 2109C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
2079 2110
2111If C<$offset> is negative, counts from the end. If C<$length> is negative,
2112the remaining length of the C<$scalar> is used. If possible, C<$length>
2113will be reduced to fit into the C<$scalar>.
2114
2080On systems that do not implement C<mprotect>, this function returns 2115On systems that do not implement C<mprotect>, this function returns
2081ENOSYS, otherwise the return value of C<mprotect>. 2116ENOSYS, otherwise the return value of C<mprotect>.
2082 2117
2083=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 2118=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
2084 2119
2085Memory-maps a file (or anonymous memory range) and attaches it to the 2120Memory-maps a file (or anonymous memory range) and attaches it to the
2086given C<$scalar>, which will act like a string scalar. Returns true on 2121given C<$scalar>, which will act like a string scalar. Returns true on
2087success, and false otherwise. 2122success, and false otherwise.
2088 2123
2124The scalar must exist, but its contents do not matter - this means you
2125cannot use a nonexistant array or hash element. When in doubt, C<undef>
2126the scalar first.
2127
2089The only operations allowed on the scalar are C<substr>/C<vec> that don't 2128The only operations allowed on the mmapped scalar are C<substr>/C<vec>,
2090change the string length, and most read-only operations such as copying it 2129which don't change the string length, and most read-only operations such
2091or searching it with regexes and so on. 2130as copying it or searching it with regexes and so on.
2092 2131
2093Anything else is unsafe and will, at best, result in memory leaks. 2132Anything else is unsafe and will, at best, result in memory leaks.
2094 2133
2095The memory map associated with the C<$scalar> is automatically removed 2134The memory map associated with the C<$scalar> is automatically removed
2096when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or 2135when the C<$scalar> is undef'd or destroyed, or when the C<IO::AIO::mmap>
2097C<IO::AIO::munmap> functions are called. 2136or C<IO::AIO::munmap> functions are called on it.
2098 2137
2099This calls the C<mmap>(2) function internally. See your system's manual 2138This calls the C<mmap>(2) function internally. See your system's manual
2100page for details on the C<$length>, C<$prot> and C<$flags> parameters. 2139page for details on the C<$length>, C<$prot> and C<$flags> parameters.
2101 2140
2102The C<$length> must be larger than zero and smaller than the actual 2141The C<$length> must be larger than zero and smaller than the actual

Diff Legend

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