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.216 by root, Sun Oct 9 08:24:49 2011 UTC vs.
Revision 1.225 by root, Tue Apr 10 05:01:33 2012 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '4.1'; 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
… …
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)
225 aio_unlink $pathname, $callback->($status) 226 aio_unlink $pathname, $callback->($status)
226 aio_mknod $pathname, $mode, $dev, $callback->($status) 227 aio_mknod $pathname, $mode, $dev, $callback->($status)
227 aio_link $srcpath, $dstpath, $callback->($status) 228 aio_link $srcpath, $dstpath, $callback->($status)
228 aio_symlink $srcpath, $dstpath, $callback->($status) 229 aio_symlink $srcpath, $dstpath, $callback->($status)
229 aio_readlink $pathname, $callback->($link) 230 aio_readlink $pathname, $callback->($link)
… …
276 IO::AIO::madvise $scalar, $offset, $length, $advice 277 IO::AIO::madvise $scalar, $offset, $length, $advice
277 IO::AIO::mprotect $scalar, $offset, $length, $protect 278 IO::AIO::mprotect $scalar, $offset, $length, $protect
278 IO::AIO::munlock $scalar, $offset = 0, $length = undef 279 IO::AIO::munlock $scalar, $offset = 0, $length = undef
279 IO::AIO::munlockall 280 IO::AIO::munlockall
280 281
281=head2 AIO REQUEST FUNCTIONS 282=head2 API NOTES
282 283
283All the C<aio_*> calls are more or less thin wrappers around the syscall 284All the C<aio_*> calls are more or less thin wrappers around the syscall
284with the same name (sans C<aio_>). The arguments are similar or identical, 285with the same name (sans C<aio_>). The arguments are similar or identical,
285and they all accept an additional (and optional) C<$callback> argument 286and they all accept an additional (and optional) C<$callback> argument
286which must be a code reference. This code reference will be called after 287which must be a code reference. This code reference will be called after
… …
317correct contents. 318correct contents.
318 319
319This works, btw. independent of the internal UTF-8 bit, which IO::AIO 320This works, btw. independent of the internal UTF-8 bit, which IO::AIO
320handles correctly whether it is set or not. 321handles correctly whether it is set or not.
321 322
323=head2 AIO REQUEST FUNCTIONS
324
322=over 4 325=over 4
323 326
324=item $prev_pri = aioreq_pri [$pri] 327=item $prev_pri = aioreq_pri [$pri]
325 328
326Returns the priority value that would be used for the next request and, if 329Returns the priority value that would be used for the next request and, if
… …
407 410
408Or in other words: the file descriptor will be closed, but it will not be 411Or in other words: the file descriptor will be closed, but it will not be
409free for reuse until the perl filehandle is closed. 412free for reuse until the perl filehandle is closed.
410 413
411=cut 414=cut
415
416=item aio_seek $fh, $offset, $whence, $callback->($offs)
417
418Seeks the filehandle to the new C<$offset>, similarly to perl's
419C<sysseek>. The C<$whence> can use the traditional values (C<0> for
420C<IO::AIO::SEEK_SET>, C<1> for C<IO::AIO::SEEK_CUR> or C<2> for
421C<IO::AIO::SEEK_END>).
422
423The resulting absolute offset will be passed to the callback, or C<-1> in
424case of an error.
425
426In theory, the C<$whence> constants could be different than the
427corresponding values from L<Fcntl>, but perl guarantees they are the same,
428so don't panic.
429
430As a GNU/Linux (and maybe Solaris) extension, also the constants
431C<IO::AIO::SEEK_DATA> and C<IO::AIO::SEEK_HOLE> are available, if they
432could be found. No guarantees about suitability for use in C<aio_seek> or
433Perl's C<sysseek> can be made though, although I would naively assume they
434"just work".
412 435
413=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 436=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
414 437
415=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 438=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
416 439
… …
1232 1255
1233Example: asynchronously lock all current and future pages into memory. 1256Example: asynchronously lock all current and future pages into memory.
1234 1257
1235 aio_mlockall IO::AIO::MCL_FUTURE; 1258 aio_mlockall IO::AIO::MCL_FUTURE;
1236 1259
1260=item aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1261
1262Queries the extents of the given file (by calling the Linux FIEMAP ioctl,
1263see L<http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for details). If the
1264C<ioctl> is not available on your OS, then this rquiest will fail with
1265C<ENOSYS>.
1266
1267C<$start> is the starting offset to query extents for, C<$length> is the
1268size of the range to query - if it is C<undef>, then the whole file will
1269be queried.
1270
1271C<$flags> is a combination of flags (C<IO::AIO::FIEMAP_FLAG_SYNC> or
1272C<IO::AIO::FIEMAP_FLAG_XATTR> - C<IO::AIO::FIEMAP_FLAGS_COMPAT> is also
1273exported), and is normally C<0> or C<IO::AIO::FIEMAP_FLAG_SYNC> to query
1274the data portion.
1275
1276C<$count> is the maximum number of extent records to return. If it is
1277C<undef>, then IO::AIO queries all extents of the file. As a very special
1278case, if it is C<0>, then the callback receives the number of extents
1279instead of the extents themselves.
1280
1281If an error occurs, the callback receives no arguments. The special
1282C<errno> value C<IO::AIO::EBADR> is available to test for flag errors.
1283
1284Otherwise, the callback receives an array reference with extent
1285structures. Each extent structure is an array reference itself, with the
1286following members:
1287
1288 [$logical, $physical, $length, $flags]
1289
1290Flags is any combination of the following flag values (typically either C<0>
1291or C<IO::AIO::FIEMAP_EXTENT_LAST>):
1292
1293C<IO::AIO::FIEMAP_EXTENT_LAST>, C<IO::AIO::FIEMAP_EXTENT_UNKNOWN>,
1294C<IO::AIO::FIEMAP_EXTENT_DELALLOC>, C<IO::AIO::FIEMAP_EXTENT_ENCODED>,
1295C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>,
1296C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>,
1297C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or
1298C<IO::AIO::FIEMAP_EXTENT_SHARED>.
1299
1237=item aio_group $callback->(...) 1300=item aio_group $callback->(...)
1238 1301
1239This is a very special aio request: Instead of doing something, it is a 1302This is a very special aio request: Instead of doing something, it is a
1240container for other aio requests, which is useful if you want to bundle 1303container for other aio requests, which is useful if you want to bundle
1241many requests into a single, composite, request with a definite callback 1304many requests into a single, composite, request with a definite callback
… …
1906Calls the C<munlockall> function. 1969Calls the C<munlockall> function.
1907 1970
1908On systems that do not implement C<munlockall>, this function returns 1971On systems that do not implement C<munlockall>, this function returns
1909ENOSYS, otherwise the return value of C<munlockall>. 1972ENOSYS, otherwise the return value of C<munlockall>.
1910 1973
1974=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1975
1976Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
1977C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
1978should be the file offset.
1979
1980The following symbol flag values are available: C<IO::AIO::SPLICE_F_MOVE>,
1981C<IO::AIO::SPLICE_F_NONBLOCK>, C<IO::AIO::SPLICE_F_MORE> and
1982C<IO::AIO::SPLICE_F_GIFT>.
1983
1984See the C<splice(2)> manpage for details.
1985
1986=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
1987
1988Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the
1989description for C<IO::AIO::splice> above for details.
1990
1911=back 1991=back
1912 1992
1913=cut 1993=cut
1914 1994
1915min_parallel 8; 1995min_parallel 8;

Diff Legend

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