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.201 by root, Tue Jul 5 09:24:11 2011 UTC vs.
Revision 1.207 by root, Mon Jul 25 16:50:33 2011 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '3.93'; 173 our $VERSION = '4.0';
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_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 aio_fsync 177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead 178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_fallocate
179 aio_pathsync aio_readahead
179 aio_rename aio_link aio_move aio_copy aio_group 180 aio_rename aio_link aio_move aio_copy aio_group
180 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
181 aio_chmod aio_utime aio_truncate 182 aio_chmod aio_utime aio_truncate
182 aio_msync aio_mtouch aio_mlock aio_mlockall 183 aio_msync aio_mtouch aio_mlock aio_mlockall
183 aio_statvfs); 184 aio_statvfs);
… …
236 aio_copy $srcpath, $dstpath, $callback->($status) 237 aio_copy $srcpath, $dstpath, $callback->($status)
237 aio_move $srcpath, $dstpath, $callback->($status) 238 aio_move $srcpath, $dstpath, $callback->($status)
238 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 239 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
239 aio_rmtree $path, $callback->($status) 240 aio_rmtree $path, $callback->($status)
240 aio_sync $callback->($status) 241 aio_sync $callback->($status)
242 aio_syncfs $fh, $callback->($status)
241 aio_fsync $fh, $callback->($status) 243 aio_fsync $fh, $callback->($status)
242 aio_fdatasync $fh, $callback->($status) 244 aio_fdatasync $fh, $callback->($status)
243 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 245 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
244 aio_pathsync $path, $callback->($status) 246 aio_pathsync $path, $callback->($status)
245 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 247 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
… …
647 649
648 650
649=item aio_realpath $path, $callback->($path) 651=item aio_realpath $path, $callback->($path)
650 652
651Asynchronously make the path absolute and resolve any symlinks in 653Asynchronously make the path absolute and resolve any symlinks in
652C<$path>. The resulting path only consists of directories. 654C<$path>. The resulting path only consists of directories (Same as
655L<Cwd::realpath>).
653 656
654This request can be used to get the absolute path of the current working 657This request can be used to get the absolute path of the current working
655directory by passing it a path of F<.> (a single dot). 658directory by passing it a path of F<.> (a single dot).
656 659
657 660
… …
684array-ref with the filenames. 687array-ref with the filenames.
685 688
686 689
687=item aio_readdirx $pathname, $flags, $callback->($entries, $flags) 690=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
688 691
689Quite similar to C<aio_readdir>, but the C<$flags> argument allows to tune 692Quite similar to C<aio_readdir>, but the C<$flags> argument allows one to
690behaviour and output format. In case of an error, C<$entries> will be 693tune behaviour and output format. In case of an error, C<$entries> will be
691C<undef>. 694C<undef>.
692 695
693The flags are a combination of the following constants, ORed together (the 696The flags are a combination of the following constants, ORed together (the
694flags will also be passed to the callback, possibly modified): 697flags will also be passed to the callback, possibly modified):
695 698
… …
742 745
743=item IO::AIO::READDIR_FOUND_UNKNOWN 746=item IO::AIO::READDIR_FOUND_UNKNOWN
744 747
745This flag should not be set when calling C<aio_readdirx>. Instead, it 748This flag should not be set when calling C<aio_readdirx>. Instead, it
746is being set by C<aio_readdirx>, when any of the C<$type>'s found were 749is being set by C<aio_readdirx>, when any of the C<$type>'s found were
747C<IO::AIO::DT_UNKNOWN>. The absense of this flag therefore indicates that all 750C<IO::AIO::DT_UNKNOWN>. The absence of this flag therefore indicates that all
748C<$type>'s are known, which can be used to speed up some algorithms. 751C<$type>'s are known, which can be used to speed up some algorithms.
749 752
750=back 753=back
751 754
752 755
… …
934Then entries will be sorted into likely directories a non-initial dot 937Then entries will be sorted into likely directories a non-initial dot
935currently) and likely non-directories (see C<aio_readdirx>). Then every 938currently) and likely non-directories (see C<aio_readdirx>). Then every
936entry plus an appended C</.> will be C<stat>'ed, likely directories first, 939entry plus an appended C</.> will be C<stat>'ed, likely directories first,
937in order of their inode numbers. If that succeeds, it assumes that the 940in order of their inode numbers. If that succeeds, it assumes that the
938entry is a directory or a symlink to directory (which will be checked 941entry is a directory or a symlink to directory (which will be checked
939seperately). This is often faster than stat'ing the entry itself because 942separately). This is often faster than stat'ing the entry itself because
940filesystems might detect the type of the entry without reading the inode 943filesystems might detect the type of the entry without reading the inode
941data (e.g. ext2fs filetype feature), even on systems that cannot return 944data (e.g. ext2fs filetype feature), even on systems that cannot return
942the filetype information on readdir. 945the filetype information on readdir.
943 946
944If the known number of directories (link count - 2) has been reached, the 947If the known number of directories (link count - 2) has been reached, the
… …
1082callback with the fdatasync result code. 1085callback with the fdatasync result code.
1083 1086
1084If this call isn't available because your OS lacks it or it couldn't be 1087If this call isn't available because your OS lacks it or it couldn't be
1085detected, it will be emulated by calling C<fsync> instead. 1088detected, it will be emulated by calling C<fsync> instead.
1086 1089
1090=item aio_syncfs $fh, $callback->($status)
1091
1092Asynchronously call the syncfs syscall to sync the filesystem associated
1093to the given filehandle and call the callback with the syncfs result
1094code. If syncfs is not available, calls sync(), but returns C<-1> and sets
1095errno to C<ENOSYS> nevertheless.
1096
1087=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 1097=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
1088 1098
1089Sync the data portion of the file specified by C<$offset> and C<$length> 1099Sync the data portion of the file specified by C<$offset> and C<$length>
1090to disk (but NOT the metadata), by calling the Linux-specific 1100to disk (but NOT the metadata), by calling the Linux-specific
1091sync_file_range call. If sync_file_range is not available or it returns 1101sync_file_range call. If sync_file_range is not available or it returns
… …
1663 1673
1664=item IO::AIO::fadvise $fh, $offset, $len, $advice 1674=item IO::AIO::fadvise $fh, $offset, $len, $advice
1665 1675
1666Simply calls the C<posix_fadvise> function (see its 1676Simply calls the C<posix_fadvise> function (see its
1667manpage for details). The following advice constants are 1677manpage for details). The following advice constants are
1668avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 1678available: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1669C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 1679C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1670C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 1680C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1671 1681
1672On systems that do not implement C<posix_fadvise>, this function returns 1682On systems that do not implement C<posix_fadvise>, this function returns
1673ENOSYS, otherwise the return value of C<posix_fadvise>. 1683ENOSYS, otherwise the return value of C<posix_fadvise>.
1674 1684
1675=item IO::AIO::madvise $scalar, $offset, $len, $advice 1685=item IO::AIO::madvise $scalar, $offset, $len, $advice
1676 1686
1677Simply calls the C<posix_madvise> function (see its 1687Simply calls the C<posix_madvise> function (see its
1678manpage for details). The following advice constants are 1688manpage for details). The following advice constants are
1679avaiable: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>, 1689available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
1680C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>. 1690C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
1681 1691
1682On systems that do not implement C<posix_madvise>, this function returns 1692On systems that do not implement C<posix_madvise>, this function returns
1683ENOSYS, otherwise the return value of C<posix_madvise>. 1693ENOSYS, otherwise the return value of C<posix_madvise>.
1684 1694
1685=item IO::AIO::mprotect $scalar, $offset, $len, $protect 1695=item IO::AIO::mprotect $scalar, $offset, $len, $protect
1686 1696
1687Simply calls the C<mprotect> function on the preferably AIO::mmap'ed 1697Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
1688$scalar (see its manpage for details). The following protect 1698$scalar (see its manpage for details). The following protect
1689constants are avaiable: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>, 1699constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
1690C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>. 1700C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
1691 1701
1692On systems that do not implement C<mprotect>, this function returns 1702On systems that do not implement C<mprotect>, this function returns
1693ENOSYS, otherwise the return value of C<mprotect>. 1703ENOSYS, otherwise the return value of C<mprotect>.
1694 1704
… …
1802=head2 FORK BEHAVIOUR 1812=head2 FORK BEHAVIOUR
1803 1813
1804Usage of pthreads in a program changes the semantics of fork 1814Usage of pthreads in a program changes the semantics of fork
1805considerably. Specifically, only async-safe functions can be called after 1815considerably. Specifically, only async-safe functions can be called after
1806fork. Perl doesn't know about this, so in general, you cannot call fork 1816fork. Perl doesn't know about this, so in general, you cannot call fork
1807with defined behaviour in perl. IO::AIO uses pthreads, so this applies, 1817with defined behaviour in perl if pthreads are involved. IO::AIO uses
1808but many other extensions and (for inexplicable reasons) perl itself often 1818pthreads, so this applies, but many other extensions and (for inexplicable
1809is linked against pthreads, so this limitation applies. 1819reasons) perl itself often is linked against pthreads, so this limitation
1820applies to quite a lot of perls.
1810 1821
1811Some operating systems have extensions that allow safe use of fork, and 1822This module no longer tries to fight your OS, or POSIX. That means IO::AIO
1812this module should do "the right thing" on those, and tries on others. At 1823only works in the process that loaded it. Forking is fully supported, but
1813the time of this writing (2011) only GNU/Linux supports these extensions 1824using IO::AIO in the child is not.
1814to POSIX. 1825
1826You might get around by not I<using> IO::AIO before (or after)
1827forking. You could also try to call the L<IO::AIO::reinit> function in the
1828child:
1829
1830=over 4
1831
1832=item IO::AIO::reinit
1833
1834Abandons all current requests and I/O threads and simply reinitialises all
1835data structures. This is not an operation supported by any standards, but
1836happens to work on GNU/Linux and some newer BSD systems.
1837
1838The only reasonable use for this function is to call it after forking, if
1839C<IO::AIO> was used in the parent. Calling it while IO::AIO is active in
1840the process will result in undefined behaviour. Calling it at any time
1841will also result in any undefined (by POSIX) behaviour.
1842
1843=back
1815 1844
1816=head2 MEMORY USAGE 1845=head2 MEMORY USAGE
1817 1846
1818Per-request usage: 1847Per-request usage:
1819 1848

Diff Legend

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