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.284 by root, Fri Mar 23 01:14:08 2018 UTC vs.
Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC

… …
171use common::sense; 171use common::sense;
172 172
173use base 'Exporter'; 173use base 'Exporter';
174 174
175BEGIN { 175BEGIN {
176 our $VERSION = 4.4; 176 our $VERSION = 4.6;
177 177
178 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
179 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
180 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
181 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
… …
192 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 192 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
193 min_parallel max_parallel max_idle idle_timeout 193 min_parallel max_parallel max_idle idle_timeout
194 nreqs nready npending nthreads 194 nreqs nready npending nthreads
195 max_poll_time max_poll_reqs 195 max_poll_time max_poll_reqs
196 sendfile fadvise madvise 196 sendfile fadvise madvise
197 mmap munmap munlock munlockall); 197 mmap munmap mremap munlock munlockall);
198 198
199 push @AIO_REQ, qw(aio_busy); # not exported 199 push @AIO_REQ, qw(aio_busy); # not exported
200 200
201 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 201 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
202 202
… …
285 285
286 IO::AIO::sendfile $ofh, $ifh, $offset, $count 286 IO::AIO::sendfile $ofh, $ifh, $offset, $count
287 IO::AIO::fadvise $fh, $offset, $len, $advice 287 IO::AIO::fadvise $fh, $offset, $len, $advice
288 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] 288 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
289 IO::AIO::munmap $scalar 289 IO::AIO::munmap $scalar
290 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
290 IO::AIO::madvise $scalar, $offset, $length, $advice 291 IO::AIO::madvise $scalar, $offset, $length, $advice
291 IO::AIO::mprotect $scalar, $offset, $length, $protect 292 IO::AIO::mprotect $scalar, $offset, $length, $protect
292 IO::AIO::munlock $scalar, $offset = 0, $length = undef 293 IO::AIO::munlock $scalar, $offset = 0, $length = undef
293 IO::AIO::munlockall 294 IO::AIO::munlockall
294 295
… …
404following POSIX and non-POSIX constants are available (missing ones on 405following POSIX and non-POSIX constants are available (missing ones on
405your system are, as usual, C<0>): 406your system are, as usual, C<0>):
406 407
407C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>, 408C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
408C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>, 409C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
409C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, and C<O_TTY_INIT>. 410C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, C<O_TTY_INIT> and C<O_ACCMODE>.
410 411
411 412
412=item aio_close $fh, $callback->($status) 413=item aio_close $fh, $callback->($status)
413 414
414Asynchronously close a file and call the callback with the result 415Asynchronously close a file and call the callback with the result
… …
540 541
541=item aio_stat $fh_or_path, $callback->($status) 542=item aio_stat $fh_or_path, $callback->($status)
542 543
543=item aio_lstat $fh, $callback->($status) 544=item aio_lstat $fh, $callback->($status)
544 545
545Works like perl's C<stat> or C<lstat> in void context. The callback will 546Works almost exactly like perl's C<stat> or C<lstat> in void context. The
546be called after the stat and the results will be available using C<stat _> 547callback will be called after the stat and the results will be available
547or C<-s _> etc... 548using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
549and C<-T>).
548 550
549The pathname passed to C<aio_stat> must be absolute. See API NOTES, above, 551The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
550for an explanation. 552for an explanation.
551 553
552Currently, the stats are always 64-bit-stats, i.e. instead of returning an 554Currently, the stats are always 64-bit-stats, i.e. instead of returning an
… …
559behaviour). 561behaviour).
560 562
561C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>, 563C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
562C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>, 564C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
563C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>. 565C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
566
567To access higher resolution stat timestamps, see L<SUBSECOND STAT TIME
568ACCESS>.
564 569
565Example: Print the length of F</etc/passwd>: 570Example: Print the length of F</etc/passwd>:
566 571
567 aio_stat "/etc/passwd", sub { 572 aio_stat "/etc/passwd", sub {
568 $_[0] and die "stat failed: $!"; 573 $_[0] and die "stat failed: $!";
… …
618 623
619Works like perl's C<utime> function (including the special case of $atime 624Works like perl's C<utime> function (including the special case of $atime
620and $mtime being undef). Fractional times are supported if the underlying 625and $mtime being undef). Fractional times are supported if the underlying
621syscalls support them. 626syscalls support them.
622 627
623When called with a pathname, uses utimes(2) if available, otherwise 628When called with a pathname, uses utimensat(2) or utimes(2) if available,
624utime(2). If called on a file descriptor, uses futimes(2) if available, 629otherwise utime(2). If called on a file descriptor, uses futimens(2)
625otherwise returns ENOSYS, so this is not portable. 630or futimes(2) if available, otherwise returns ENOSYS, so this is not
631portable.
626 632
627Examples: 633Examples:
628 634
629 # set atime and mtime to current time (basically touch(1)): 635 # set atime and mtime to current time (basically touch(1)):
630 aio_utime "path", undef, undef; 636 aio_utime "path", undef, undef;
… …
1778The default value for the limit is C<0>, but note that setting a feeder 1784The default value for the limit is C<0>, but note that setting a feeder
1779automatically bumps it up to C<2>. 1785automatically bumps it up to C<2>.
1780 1786
1781=back 1787=back
1782 1788
1789
1783=head2 SUPPORT FUNCTIONS 1790=head2 SUPPORT FUNCTIONS
1784 1791
1785=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 1792=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1786 1793
1787=over 4 1794=over 4
… …
1852Strictly equivalent to: 1859Strictly equivalent to:
1853 1860
1854 IO::AIO::poll_wait, IO::AIO::poll_cb 1861 IO::AIO::poll_wait, IO::AIO::poll_cb
1855 while IO::AIO::nreqs; 1862 while IO::AIO::nreqs;
1856 1863
1864This function can be useful at program aborts, to make sure outstanding
1865I/O has been done (C<IO::AIO> uses an C<END> block which already calls
1866this function on normal exits), or when you are merely using C<IO::AIO>
1867for its more advanced functions, rather than for async I/O, e.g.:
1868
1869 my ($dirs, $nondirs);
1870 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1871 IO::AIO::flush;
1872 # $dirs, $nondirs are now set
1873
1857=item IO::AIO::max_poll_reqs $nreqs 1874=item IO::AIO::max_poll_reqs $nreqs
1858 1875
1859=item IO::AIO::max_poll_time $seconds 1876=item IO::AIO::max_poll_time $seconds
1860 1877
1861These set the maximum number of requests (default C<0>, meaning infinity) 1878These set the maximum number of requests (default C<0>, meaning infinity)
… …
1887 poll => 'r', nice => 1, 1904 poll => 'r', nice => 1,
1888 cb => &IO::AIO::poll_cb); 1905 cb => &IO::AIO::poll_cb);
1889 1906
1890=back 1907=back
1891 1908
1909
1892=head3 CONTROLLING THE NUMBER OF THREADS 1910=head3 CONTROLLING THE NUMBER OF THREADS
1893 1911
1894=over 1912=over
1895 1913
1896=item IO::AIO::min_parallel $nthreads 1914=item IO::AIO::min_parallel $nthreads
… …
1983The default value for C<max_outstanding> is very large, so there is no 2001The default value for C<max_outstanding> is very large, so there is no
1984practical limit on the number of outstanding requests. 2002practical limit on the number of outstanding requests.
1985 2003
1986=back 2004=back
1987 2005
2006
1988=head3 STATISTICAL INFORMATION 2007=head3 STATISTICAL INFORMATION
1989 2008
1990=over 2009=over
1991 2010
1992=item IO::AIO::nreqs 2011=item IO::AIO::nreqs
… …
2008 2027
2009Returns the number of requests currently in the pending state (executed, 2028Returns the number of requests currently in the pending state (executed,
2010but not yet processed by poll_cb). 2029but not yet processed by poll_cb).
2011 2030
2012=back 2031=back
2032
2033
2034=head3 SUBSECOND STAT TIME ACCESS
2035
2036Both C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> functions can
2037generally find access/modification and change times with subsecond time
2038accuracy of the system supports it, but perl's built-in functions only
2039return the integer part.
2040
2041The following functions return the timestamps of the most recent
2042stat with subsecond precision on most systems and work both after
2043C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> calls. Their return
2044value is only meaningful after a successful C<stat>/C<lstat> call, or
2045during/after a successful C<aio_stat>/C<aio_lstat> callback.
2046
2047This is similar to the L<Time::HiRes> C<stat> functions, but can return
2048full resolution without rounding and work with standard perl C<stat>,
2049alleviating the need to call the special C<Time::HiRes> functions, which
2050do not act like their perl counterparts.
2051
2052On operating systems or file systems where subsecond time resolution is
2053not supported or could not be detected, a fractional part of C<0> is
2054returned, so it is always safe to call these functions.
2055
2056=over 4
2057
2058=item $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
2059
2060Return the access, modication, change or birth time, respectively,
2061including fractional part. Due to the limited precision of floating point,
2062the accuracy on most platforms is only a bit better than milliseconds
2063for times around now - see the I<nsec> function family, below, for full
2064accuracy.
2065
2066File birth time is only available when the OS and perl support it (on
2067FreeBSD and NetBSD at the time of this writing, although support is
2068adaptive, so if your OS/perl gains support, IO::AIO can take avdantage of
2069it). On systems where it isn't available, C<0> is currently returned, but
2070this might change to C<undef> in a future version.
2071
2072=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
2073
2074Returns access, modification, change and birth time all in one go, and
2075maybe more times in the future version.
2076
2077=item $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
2078
2079Return the fractional access, modifcation, change or birth time, in nanoseconds,
2080as an integer in the range C<0> to C<999999999>.
2081
2082Note that no accessors are provided for access, modification and
2083change times - you need to get those from C<stat _> if required (C<int
2084IO::AIO::st_atime> and so on will I<not> generally give you the correct
2085value).
2086
2087=item $seconds = IO::AIO::st_btimesec
2088
2089The (integral) seconds part of the file birth time, if available.
2090
2091=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
2092
2093Like the functions above, but returns all four times in one go (and maybe
2094more in future versions).
2095
2096=item $counter = IO::AIO::st_gen
2097
2098Returns the generation counter (in practice this is just a random number)
2099of the file. This is only available on platforms which have this member in
2100their C<struct stat> (most BSDs at the time of this writing) and generally
2101only to the root usert. If unsupported, C<0> is returned, but this might
2102change to C<undef> in a future version.
2103
2104=back
2105
2106Example: print the high resolution modification time of F</etc>, using
2107C<stat>, and C<IO::AIO::aio_stat>.
2108
2109 if (stat "/etc") {
2110 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
2111 }
2112
2113 IO::AIO::aio_stat "/etc", sub {
2114 $_[0]
2115 and return;
2116
2117 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
2118 };
2119
2120 IO::AIO::flush;
2121
2122Output of the awbove on my system, showing reduced and full accuracy:
2123
2124 stat(/etc) mtime: 1534043702.020808
2125 aio_stat(/etc) mtime: 1534043702.020807792
2126
2013 2127
2014=head3 MISCELLANEOUS FUNCTIONS 2128=head3 MISCELLANEOUS FUNCTIONS
2015 2129
2016IO::AIO implements some functions that are useful when you want to use 2130IO::AIO implements some functions that are useful when you want to use
2017some "Advanced I/O" function not available to in Perl, without going the 2131some "Advanced I/O" function not available to in Perl, without going the
… …
2158 2272
2159=item IO::AIO::munmap $scalar 2273=item IO::AIO::munmap $scalar
2160 2274
2161Removes a previous mmap and undefines the C<$scalar>. 2275Removes a previous mmap and undefines the C<$scalar>.
2162 2276
2277=item IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[, $new_address = 0]
2278
2279Calls the Linux-specific mremap(2) system call. The C<$scalar> must have
2280been mapped by C<IO::AIO::mmap>, and C<$flags> must currently either be
2281C<0> or C<IO::AIO::MREMAP_MAYMOVE>.
2282
2283Returns true if successful, and false otherwise. If the underlying mmapped
2284region has changed address, then the true value has the numerical value
2285C<1>, otherwise it has the numerical value C<0>:
2286
2287 my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
2288 or die "mremap: $!";
2289
2290 if ($success*1) {
2291 warn "scalar has chanegd address in memory\n";
2292 }
2293
2294C<IO::AIO::MREMAP_FIXED> and the C<$new_address> argument are currently
2295implemented, but not supported and might go away in a future version.
2296
2297On systems where this call is not supported or is not emulated, this call
2298returns falls and sets C<$!> to C<ENOSYS>.
2299
2163=item IO::AIO::munlock $scalar, $offset = 0, $length = undef 2300=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2164 2301
2165Calls the C<munlock> function, undoing the effects of a previous 2302Calls the C<munlock> function, undoing the effects of a previous
2166C<aio_mlock> call (see its description for details). 2303C<aio_mlock> call (see its description for details).
2167 2304

Diff Legend

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