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.219 by root, Tue Mar 27 18:54:45 2012 UTC vs.
Revision 1.233 by root, Mon Aug 13 01:01:04 2012 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '4.12'; 173 our $VERSION = '4.15';
174 174
175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close 175 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync 177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_fallocate 178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_fallocate
179 aio_pathsync aio_readahead 179 aio_pathsync aio_readahead aio_fiemap
180 aio_rename aio_link aio_move aio_copy aio_group 180 aio_rename aio_link aio_move aio_copy aio_group
181 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown 181 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
182 aio_chmod aio_utime aio_truncate 182 aio_chmod aio_utime aio_truncate
183 aio_msync aio_mtouch aio_mlock aio_mlockall 183 aio_msync aio_mtouch aio_mlock aio_mlockall
184 aio_statvfs 184 aio_statvfs
… …
202 202
203=head1 FUNCTIONS 203=head1 FUNCTIONS
204 204
205=head2 QUICK OVERVIEW 205=head2 QUICK OVERVIEW
206 206
207This section simply lists the prototypes of the most important functions 207This section simply lists the prototypes most of the functions for
208for quick reference. See the following sections for function-by-function 208quick reference. See the following sections for function-by-function
209documentation. 209documentation.
210 210
211 aio_wd $pathname, $callback->($wd) 211 aio_wd $pathname, $callback->($wd)
212 aio_open $pathname, $flags, $mode, $callback->($fh) 212 aio_open $pathname, $flags, $mode, $callback->($fh)
213 aio_close $fh, $callback->($status) 213 aio_close $fh, $callback->($status)
214 aio_seek $fh,$offset,$whence, $callback->($offs)
214 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 215 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
215 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 216 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
216 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 217 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
217 aio_readahead $fh,$offset,$length, $callback->($retval) 218 aio_readahead $fh,$offset,$length, $callback->($retval)
218 aio_stat $fh_or_path, $callback->($status) 219 aio_stat $fh_or_path, $callback->($status)
219 aio_lstat $fh, $callback->($status) 220 aio_lstat $fh, $callback->($status)
220 aio_statvfs $fh_or_path, $callback->($statvfs) 221 aio_statvfs $fh_or_path, $callback->($statvfs)
221 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 222 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
222 aio_chown $fh_or_path, $uid, $gid, $callback->($status) 223 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
224 aio_chmod $fh_or_path, $mode, $callback->($status)
223 aio_truncate $fh_or_path, $offset, $callback->($status) 225 aio_truncate $fh_or_path, $offset, $callback->($status)
224 aio_chmod $fh_or_path, $mode, $callback->($status) 226 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
227 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
225 aio_unlink $pathname, $callback->($status) 228 aio_unlink $pathname, $callback->($status)
226 aio_mknod $pathname, $mode, $dev, $callback->($status) 229 aio_mknod $pathname, $mode, $dev, $callback->($status)
227 aio_link $srcpath, $dstpath, $callback->($status) 230 aio_link $srcpath, $dstpath, $callback->($status)
228 aio_symlink $srcpath, $dstpath, $callback->($status) 231 aio_symlink $srcpath, $dstpath, $callback->($status)
229 aio_readlink $pathname, $callback->($link) 232 aio_readlink $pathname, $callback->($link)
… …
271 IO::AIO::nready 274 IO::AIO::nready
272 IO::AIO::npending 275 IO::AIO::npending
273 276
274 IO::AIO::sendfile $ofh, $ifh, $offset, $count 277 IO::AIO::sendfile $ofh, $ifh, $offset, $count
275 IO::AIO::fadvise $fh, $offset, $len, $advice 278 IO::AIO::fadvise $fh, $offset, $len, $advice
279 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
280 IO::AIO::munmap $scalar
276 IO::AIO::madvise $scalar, $offset, $length, $advice 281 IO::AIO::madvise $scalar, $offset, $length, $advice
277 IO::AIO::mprotect $scalar, $offset, $length, $protect 282 IO::AIO::mprotect $scalar, $offset, $length, $protect
278 IO::AIO::munlock $scalar, $offset = 0, $length = undef 283 IO::AIO::munlock $scalar, $offset = 0, $length = undef
279 IO::AIO::munlockall 284 IO::AIO::munlockall
280 285
… …
357 362
358 363
359=item aio_open $pathname, $flags, $mode, $callback->($fh) 364=item aio_open $pathname, $flags, $mode, $callback->($fh)
360 365
361Asynchronously open or create a file and call the callback with a newly 366Asynchronously open or create a file and call the callback with a newly
362created filehandle for the file. 367created filehandle for the file (or C<undef> in case of an error).
363 368
364The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 369The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
365for an explanation. 370for an explanation.
366 371
367The C<$flags> argument is a bitmask. See the C<Fcntl> module for a 372The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
… …
409 414
410Or in other words: the file descriptor will be closed, but it will not be 415Or in other words: the file descriptor will be closed, but it will not be
411free for reuse until the perl filehandle is closed. 416free for reuse until the perl filehandle is closed.
412 417
413=cut 418=cut
419
420=item aio_seek $fh, $offset, $whence, $callback->($offs)
421
422Seeks the filehandle to the new C<$offset>, similarly to perl's
423C<sysseek>. The C<$whence> can use the traditional values (C<0> for
424C<IO::AIO::SEEK_SET>, C<1> for C<IO::AIO::SEEK_CUR> or C<2> for
425C<IO::AIO::SEEK_END>).
426
427The resulting absolute offset will be passed to the callback, or C<-1> in
428case of an error.
429
430In theory, the C<$whence> constants could be different than the
431corresponding values from L<Fcntl>, but perl guarantees they are the same,
432so don't panic.
433
434As a GNU/Linux (and maybe Solaris) extension, also the constants
435C<IO::AIO::SEEK_DATA> and C<IO::AIO::SEEK_HOLE> are available, if they
436could be found. No guarantees about suitability for use in C<aio_seek> or
437Perl's C<sysseek> can be made though, although I would naively assume they
438"just work".
414 439
415=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 440=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
416 441
417=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 442=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
418 443
… …
613 638
614 639
615=item aio_truncate $fh_or_path, $offset, $callback->($status) 640=item aio_truncate $fh_or_path, $offset, $callback->($status)
616 641
617Works like truncate(2) or ftruncate(2). 642Works like truncate(2) or ftruncate(2).
643
644
645=item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
646
647Allocates or freed disk space according to the C<$mode> argument. See the
648linux C<fallocate> docuemntation for details.
649
650C<$mode> can currently be C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE>
651to allocate space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE |
652IO::AIO::FALLOC_FL_KEEP_SIZE>, to deallocate a file range.
653
654The file system block size used by C<fallocate> is presumably the
655C<f_bsize> returned by C<statvfs>.
656
657If C<fallocate> isn't available or cannot be emulated (currently no
658emulation will be attempted), passes C<-1> and sets C<$!> to C<ENOSYS>.
618 659
619 660
620=item aio_chmod $fh_or_path, $mode, $callback->($status) 661=item aio_chmod $fh_or_path, $mode, $callback->($status)
621 662
622Works like perl's C<chmod> function. 663Works like perl's C<chmod> function.
… …
1234 1275
1235Example: asynchronously lock all current and future pages into memory. 1276Example: asynchronously lock all current and future pages into memory.
1236 1277
1237 aio_mlockall IO::AIO::MCL_FUTURE; 1278 aio_mlockall IO::AIO::MCL_FUTURE;
1238 1279
1280=item aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1281
1282Queries the extents of the given file (by calling the Linux FIEMAP ioctl,
1283see L<http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for details). If the
1284C<ioctl> is not available on your OS, then this request will fail with
1285C<ENOSYS>.
1286
1287C<$start> is the starting offset to query extents for, C<$length> is the
1288size of the range to query - if it is C<undef>, then the whole file will
1289be queried.
1290
1291C<$flags> is a combination of flags (C<IO::AIO::FIEMAP_FLAG_SYNC> or
1292C<IO::AIO::FIEMAP_FLAG_XATTR> - C<IO::AIO::FIEMAP_FLAGS_COMPAT> is also
1293exported), and is normally C<0> or C<IO::AIO::FIEMAP_FLAG_SYNC> to query
1294the data portion.
1295
1296C<$count> is the maximum number of extent records to return. If it is
1297C<undef>, then IO::AIO queries all extents of the range. As a very special
1298case, if it is C<0>, then the callback receives the number of extents
1299instead of the extents themselves (which is unreliable, see below).
1300
1301If an error occurs, the callback receives no arguments. The special
1302C<errno> value C<IO::AIO::EBADR> is available to test for flag errors.
1303
1304Otherwise, the callback receives an array reference with extent
1305structures. Each extent structure is an array reference itself, with the
1306following members:
1307
1308 [$logical, $physical, $length, $flags]
1309
1310Flags is any combination of the following flag values (typically either C<0>
1311or C<IO::AIO::FIEMAP_EXTENT_LAST> (1)):
1312
1313C<IO::AIO::FIEMAP_EXTENT_LAST>, C<IO::AIO::FIEMAP_EXTENT_UNKNOWN>,
1314C<IO::AIO::FIEMAP_EXTENT_DELALLOC>, C<IO::AIO::FIEMAP_EXTENT_ENCODED>,
1315C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>,
1316C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>,
1317C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or
1318C<IO::AIO::FIEMAP_EXTENT_SHARED>.
1319
1320At the time of this writing (Linux 3.2), this requets is unreliable unless
1321C<$count> is C<undef>, as the kernel has all sorts of bugs preventing
1322it to return all extents of a range for files with large number of
1323extents. The code works around all these issues if C<$count> is undef.
1324
1239=item aio_group $callback->(...) 1325=item aio_group $callback->(...)
1240 1326
1241This is a very special aio request: Instead of doing something, it is a 1327This is a very special aio request: Instead of doing something, it is a
1242container for other aio requests, which is useful if you want to bundle 1328container for other aio requests, which is useful if you want to bundle
1243many requests into a single, composite, request with a definite callback 1329many requests into a single, composite, request with a definite callback
… …
1845ENOSYS, otherwise the return value of C<mprotect>. 1931ENOSYS, otherwise the return value of C<mprotect>.
1846 1932
1847=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 1933=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1848 1934
1849Memory-maps a file (or anonymous memory range) and attaches it to the 1935Memory-maps a file (or anonymous memory range) and attaches it to the
1850given C<$scalar>, which will act like a string scalar. 1936given C<$scalar>, which will act like a string scalar. Returns true on
1937success, and false otherwise.
1851 1938
1852The only operations allowed on the scalar are C<substr>/C<vec> that don't 1939The only operations allowed on the scalar are C<substr>/C<vec> that don't
1853change the string length, and most read-only operations such as copying it 1940change the string length, and most read-only operations such as copying it
1854or searching it with regexes and so on. 1941or searching it with regexes and so on.
1855 1942
… …
1908Calls the C<munlockall> function. 1995Calls the C<munlockall> function.
1909 1996
1910On systems that do not implement C<munlockall>, this function returns 1997On systems that do not implement C<munlockall>, this function returns
1911ENOSYS, otherwise the return value of C<munlockall>. 1998ENOSYS, otherwise the return value of C<munlockall>.
1912 1999
2000=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2001
2002Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2003C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
2004should be the file offset.
2005
2006C<$r_fh> and C<$w_fh> should not refer to the same file, as splice might
2007silently corrupt the data in this case.
2008
2009The following symbol flag values are available: C<IO::AIO::SPLICE_F_MOVE>,
2010C<IO::AIO::SPLICE_F_NONBLOCK>, C<IO::AIO::SPLICE_F_MORE> and
2011C<IO::AIO::SPLICE_F_GIFT>.
2012
2013See the C<splice(2)> manpage for details.
2014
2015=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2016
2017Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the
2018description for C<IO::AIO::splice> above for details.
2019
1913=back 2020=back
1914 2021
1915=cut 2022=cut
1916 2023
1917min_parallel 8; 2024min_parallel 8;

Diff Legend

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