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.202 by root, Tue Jul 5 14:02:15 2011 UTC vs.
Revision 1.208 by root, Mon Sep 26 20:19:08 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
185 aio_wd);
184 186
185 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 187 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
186 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 188 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
187 min_parallel max_parallel max_idle idle_timeout 189 min_parallel max_parallel max_idle idle_timeout
188 nreqs nready npending nthreads 190 nreqs nready npending nthreads
… …
204 206
205This section simply lists the prototypes of the most important functions 207This section simply lists the prototypes of the most important functions
206for quick reference. See the following sections for function-by-function 208for quick reference. See the following sections for function-by-function
207documentation. 209documentation.
208 210
211 aio_wd $pathname, $callback->($wd)
209 aio_open $pathname, $flags, $mode, $callback->($fh) 212 aio_open $pathname, $flags, $mode, $callback->($fh)
210 aio_close $fh, $callback->($status) 213 aio_close $fh, $callback->($status)
211 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 214 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
212 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 215 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
213 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 216 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
… …
236 aio_copy $srcpath, $dstpath, $callback->($status) 239 aio_copy $srcpath, $dstpath, $callback->($status)
237 aio_move $srcpath, $dstpath, $callback->($status) 240 aio_move $srcpath, $dstpath, $callback->($status)
238 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 241 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
239 aio_rmtree $path, $callback->($status) 242 aio_rmtree $path, $callback->($status)
240 aio_sync $callback->($status) 243 aio_sync $callback->($status)
244 aio_syncfs $fh, $callback->($status)
241 aio_fsync $fh, $callback->($status) 245 aio_fsync $fh, $callback->($status)
242 aio_fdatasync $fh, $callback->($status) 246 aio_fdatasync $fh, $callback->($status)
243 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 247 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
244 aio_pathsync $path, $callback->($status) 248 aio_pathsync $path, $callback->($status)
245 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 249 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
… …
685array-ref with the filenames. 689array-ref with the filenames.
686 690
687 691
688=item aio_readdirx $pathname, $flags, $callback->($entries, $flags) 692=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
689 693
690Quite similar to C<aio_readdir>, but the C<$flags> argument allows to tune 694Quite similar to C<aio_readdir>, but the C<$flags> argument allows one to
691behaviour and output format. In case of an error, C<$entries> will be 695tune behaviour and output format. In case of an error, C<$entries> will be
692C<undef>. 696C<undef>.
693 697
694The flags are a combination of the following constants, ORed together (the 698The flags are a combination of the following constants, ORed together (the
695flags will also be passed to the callback, possibly modified): 699flags will also be passed to the callback, possibly modified):
696 700
… …
743 747
744=item IO::AIO::READDIR_FOUND_UNKNOWN 748=item IO::AIO::READDIR_FOUND_UNKNOWN
745 749
746This flag should not be set when calling C<aio_readdirx>. Instead, it 750This flag should not be set when calling C<aio_readdirx>. Instead, it
747is being set by C<aio_readdirx>, when any of the C<$type>'s found were 751is being set by C<aio_readdirx>, when any of the C<$type>'s found were
748C<IO::AIO::DT_UNKNOWN>. The absense of this flag therefore indicates that all 752C<IO::AIO::DT_UNKNOWN>. The absence of this flag therefore indicates that all
749C<$type>'s are known, which can be used to speed up some algorithms. 753C<$type>'s are known, which can be used to speed up some algorithms.
750 754
751=back 755=back
752 756
753 757
… …
935Then entries will be sorted into likely directories a non-initial dot 939Then entries will be sorted into likely directories a non-initial dot
936currently) and likely non-directories (see C<aio_readdirx>). Then every 940currently) and likely non-directories (see C<aio_readdirx>). Then every
937entry plus an appended C</.> will be C<stat>'ed, likely directories first, 941entry plus an appended C</.> will be C<stat>'ed, likely directories first,
938in order of their inode numbers. If that succeeds, it assumes that the 942in order of their inode numbers. If that succeeds, it assumes that the
939entry is a directory or a symlink to directory (which will be checked 943entry is a directory or a symlink to directory (which will be checked
940seperately). This is often faster than stat'ing the entry itself because 944separately). This is often faster than stat'ing the entry itself because
941filesystems might detect the type of the entry without reading the inode 945filesystems might detect the type of the entry without reading the inode
942data (e.g. ext2fs filetype feature), even on systems that cannot return 946data (e.g. ext2fs filetype feature), even on systems that cannot return
943the filetype information on readdir. 947the filetype information on readdir.
944 948
945If the known number of directories (link count - 2) has been reached, the 949If the known number of directories (link count - 2) has been reached, the
… …
1083callback with the fdatasync result code. 1087callback with the fdatasync result code.
1084 1088
1085If this call isn't available because your OS lacks it or it couldn't be 1089If this call isn't available because your OS lacks it or it couldn't be
1086detected, it will be emulated by calling C<fsync> instead. 1090detected, it will be emulated by calling C<fsync> instead.
1087 1091
1092=item aio_syncfs $fh, $callback->($status)
1093
1094Asynchronously call the syncfs syscall to sync the filesystem associated
1095to the given filehandle and call the callback with the syncfs result
1096code. If syncfs is not available, calls sync(), but returns C<-1> and sets
1097errno to C<ENOSYS> nevertheless.
1098
1088=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 1099=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
1089 1100
1090Sync the data portion of the file specified by C<$offset> and C<$length> 1101Sync the data portion of the file specified by C<$offset> and C<$length>
1091to disk (but NOT the metadata), by calling the Linux-specific 1102to disk (but NOT the metadata), by calling the Linux-specific
1092sync_file_range call. If sync_file_range is not available or it returns 1103sync_file_range call. If sync_file_range is not available or it returns
… …
1664 1675
1665=item IO::AIO::fadvise $fh, $offset, $len, $advice 1676=item IO::AIO::fadvise $fh, $offset, $len, $advice
1666 1677
1667Simply calls the C<posix_fadvise> function (see its 1678Simply calls the C<posix_fadvise> function (see its
1668manpage for details). The following advice constants are 1679manpage for details). The following advice constants are
1669avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 1680available: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1670C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 1681C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1671C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 1682C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1672 1683
1673On systems that do not implement C<posix_fadvise>, this function returns 1684On systems that do not implement C<posix_fadvise>, this function returns
1674ENOSYS, otherwise the return value of C<posix_fadvise>. 1685ENOSYS, otherwise the return value of C<posix_fadvise>.
1675 1686
1676=item IO::AIO::madvise $scalar, $offset, $len, $advice 1687=item IO::AIO::madvise $scalar, $offset, $len, $advice
1677 1688
1678Simply calls the C<posix_madvise> function (see its 1689Simply calls the C<posix_madvise> function (see its
1679manpage for details). The following advice constants are 1690manpage for details). The following advice constants are
1680avaiable: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>, 1691available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
1681C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>. 1692C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
1682 1693
1683On systems that do not implement C<posix_madvise>, this function returns 1694On systems that do not implement C<posix_madvise>, this function returns
1684ENOSYS, otherwise the return value of C<posix_madvise>. 1695ENOSYS, otherwise the return value of C<posix_madvise>.
1685 1696
1686=item IO::AIO::mprotect $scalar, $offset, $len, $protect 1697=item IO::AIO::mprotect $scalar, $offset, $len, $protect
1687 1698
1688Simply calls the C<mprotect> function on the preferably AIO::mmap'ed 1699Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
1689$scalar (see its manpage for details). The following protect 1700$scalar (see its manpage for details). The following protect
1690constants are avaiable: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>, 1701constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
1691C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>. 1702C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
1692 1703
1693On systems that do not implement C<mprotect>, this function returns 1704On systems that do not implement C<mprotect>, this function returns
1694ENOSYS, otherwise the return value of C<mprotect>. 1705ENOSYS, otherwise the return value of C<mprotect>.
1695 1706
… …
1803=head2 FORK BEHAVIOUR 1814=head2 FORK BEHAVIOUR
1804 1815
1805Usage of pthreads in a program changes the semantics of fork 1816Usage of pthreads in a program changes the semantics of fork
1806considerably. Specifically, only async-safe functions can be called after 1817considerably. Specifically, only async-safe functions can be called after
1807fork. Perl doesn't know about this, so in general, you cannot call fork 1818fork. Perl doesn't know about this, so in general, you cannot call fork
1808with defined behaviour in perl. IO::AIO uses pthreads, so this applies, 1819with defined behaviour in perl if pthreads are involved. IO::AIO uses
1809but many other extensions and (for inexplicable reasons) perl itself often 1820pthreads, so this applies, but many other extensions and (for inexplicable
1810is linked against pthreads, so this limitation applies. 1821reasons) perl itself often is linked against pthreads, so this limitation
1822applies to quite a lot of perls.
1811 1823
1812Some operating systems have extensions that allow safe use of fork, and 1824This module no longer tries to fight your OS, or POSIX. That means IO::AIO
1813this module should do "the right thing" on those, and tries on others. At 1825only works in the process that loaded it. Forking is fully supported, but
1814the time of this writing (2011) only GNU/Linux supports these extensions 1826using IO::AIO in the child is not.
1815to POSIX. 1827
1828You might get around by not I<using> IO::AIO before (or after)
1829forking. You could also try to call the L<IO::AIO::reinit> function in the
1830child:
1831
1832=over 4
1833
1834=item IO::AIO::reinit
1835
1836Abandons all current requests and I/O threads and simply reinitialises all
1837data structures. This is not an operation supported by any standards, but
1838happens to work on GNU/Linux and some newer BSD systems.
1839
1840The only reasonable use for this function is to call it after forking, if
1841C<IO::AIO> was used in the parent. Calling it while IO::AIO is active in
1842the process will result in undefined behaviour. Calling it at any time
1843will also result in any undefined (by POSIX) behaviour.
1844
1845=back
1816 1846
1817=head2 MEMORY USAGE 1847=head2 MEMORY USAGE
1818 1848
1819Per-request usage: 1849Per-request usage:
1820 1850

Diff Legend

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