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.297 by root, Thu Nov 29 19:53:46 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;
… …
1379 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh; 1385 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1380 aio_mlock $data; # mlock in background 1386 aio_mlock $data; # mlock in background
1381 1387
1382=item aio_mlockall $flags, $callback->($status) 1388=item aio_mlockall $flags, $callback->($status)
1383 1389
1384Calls the C<mlockall> function with the given C<$flags> (a combination of 1390Calls the C<mlockall> function with the given C<$flags> (a
1385C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>). 1391combination of C<IO::AIO::MCL_CURRENT>, C<IO::AIO::MCL_FUTURE> and
1392C<IO::AIO::MCL_ONFAULT>).
1386 1393
1387On systems that do not implement C<mlockall>, this function returns C<-1> 1394On systems that do not implement C<mlockall>, this function returns C<-1>
1388and sets errno to C<ENOSYS>. 1395and sets errno to C<ENOSYS>. Similarly, flag combinations not supported
1396by the system result in a return value of C<-1> with errno being set to
1397C<EINVAL>.
1389 1398
1390Note that the corresponding C<munlockall> is synchronous and is 1399Note that the corresponding C<munlockall> is synchronous and is
1391documented under L<MISCELLANEOUS FUNCTIONS>. 1400documented under L<MISCELLANEOUS FUNCTIONS>.
1392 1401
1393Example: asynchronously lock all current and future pages into memory. 1402Example: asynchronously lock all current and future pages into memory.
… …
1778The default value for the limit is C<0>, but note that setting a feeder 1787The default value for the limit is C<0>, but note that setting a feeder
1779automatically bumps it up to C<2>. 1788automatically bumps it up to C<2>.
1780 1789
1781=back 1790=back
1782 1791
1792
1783=head2 SUPPORT FUNCTIONS 1793=head2 SUPPORT FUNCTIONS
1784 1794
1785=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 1795=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1786 1796
1787=over 4 1797=over 4
… …
1852Strictly equivalent to: 1862Strictly equivalent to:
1853 1863
1854 IO::AIO::poll_wait, IO::AIO::poll_cb 1864 IO::AIO::poll_wait, IO::AIO::poll_cb
1855 while IO::AIO::nreqs; 1865 while IO::AIO::nreqs;
1856 1866
1867This function can be useful at program aborts, to make sure outstanding
1868I/O has been done (C<IO::AIO> uses an C<END> block which already calls
1869this function on normal exits), or when you are merely using C<IO::AIO>
1870for its more advanced functions, rather than for async I/O, e.g.:
1871
1872 my ($dirs, $nondirs);
1873 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1874 IO::AIO::flush;
1875 # $dirs, $nondirs are now set
1876
1857=item IO::AIO::max_poll_reqs $nreqs 1877=item IO::AIO::max_poll_reqs $nreqs
1858 1878
1859=item IO::AIO::max_poll_time $seconds 1879=item IO::AIO::max_poll_time $seconds
1860 1880
1861These set the maximum number of requests (default C<0>, meaning infinity) 1881These set the maximum number of requests (default C<0>, meaning infinity)
… …
1887 poll => 'r', nice => 1, 1907 poll => 'r', nice => 1,
1888 cb => &IO::AIO::poll_cb); 1908 cb => &IO::AIO::poll_cb);
1889 1909
1890=back 1910=back
1891 1911
1912
1892=head3 CONTROLLING THE NUMBER OF THREADS 1913=head3 CONTROLLING THE NUMBER OF THREADS
1893 1914
1894=over 1915=over
1895 1916
1896=item IO::AIO::min_parallel $nthreads 1917=item IO::AIO::min_parallel $nthreads
… …
1983The default value for C<max_outstanding> is very large, so there is no 2004The default value for C<max_outstanding> is very large, so there is no
1984practical limit on the number of outstanding requests. 2005practical limit on the number of outstanding requests.
1985 2006
1986=back 2007=back
1987 2008
2009
1988=head3 STATISTICAL INFORMATION 2010=head3 STATISTICAL INFORMATION
1989 2011
1990=over 2012=over
1991 2013
1992=item IO::AIO::nreqs 2014=item IO::AIO::nreqs
… …
2008 2030
2009Returns the number of requests currently in the pending state (executed, 2031Returns the number of requests currently in the pending state (executed,
2010but not yet processed by poll_cb). 2032but not yet processed by poll_cb).
2011 2033
2012=back 2034=back
2035
2036
2037=head3 SUBSECOND STAT TIME ACCESS
2038
2039Both C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> functions can
2040generally find access/modification and change times with subsecond time
2041accuracy of the system supports it, but perl's built-in functions only
2042return the integer part.
2043
2044The following functions return the timestamps of the most recent
2045stat with subsecond precision on most systems and work both after
2046C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> calls. Their return
2047value is only meaningful after a successful C<stat>/C<lstat> call, or
2048during/after a successful C<aio_stat>/C<aio_lstat> callback.
2049
2050This is similar to the L<Time::HiRes> C<stat> functions, but can return
2051full resolution without rounding and work with standard perl C<stat>,
2052alleviating the need to call the special C<Time::HiRes> functions, which
2053do not act like their perl counterparts.
2054
2055On operating systems or file systems where subsecond time resolution is
2056not supported or could not be detected, a fractional part of C<0> is
2057returned, so it is always safe to call these functions.
2058
2059=over 4
2060
2061=item $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
2062
2063Return the access, modication, change or birth time, respectively,
2064including fractional part. Due to the limited precision of floating point,
2065the accuracy on most platforms is only a bit better than milliseconds
2066for times around now - see the I<nsec> function family, below, for full
2067accuracy.
2068
2069File birth time is only available when the OS and perl support it (on
2070FreeBSD and NetBSD at the time of this writing, although support is
2071adaptive, so if your OS/perl gains support, IO::AIO can take avdantage of
2072it). On systems where it isn't available, C<0> is currently returned, but
2073this might change to C<undef> in a future version.
2074
2075=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
2076
2077Returns access, modification, change and birth time all in one go, and
2078maybe more times in the future version.
2079
2080=item $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
2081
2082Return the fractional access, modifcation, change or birth time, in nanoseconds,
2083as an integer in the range C<0> to C<999999999>.
2084
2085Note that no accessors are provided for access, modification and
2086change times - you need to get those from C<stat _> if required (C<int
2087IO::AIO::st_atime> and so on will I<not> generally give you the correct
2088value).
2089
2090=item $seconds = IO::AIO::st_btimesec
2091
2092The (integral) seconds part of the file birth time, if available.
2093
2094=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
2095
2096Like the functions above, but returns all four times in one go (and maybe
2097more in future versions).
2098
2099=item $counter = IO::AIO::st_gen
2100
2101Returns the generation counter (in practice this is just a random number)
2102of the file. This is only available on platforms which have this member in
2103their C<struct stat> (most BSDs at the time of this writing) and generally
2104only to the root usert. If unsupported, C<0> is returned, but this might
2105change to C<undef> in a future version.
2106
2107=back
2108
2109Example: print the high resolution modification time of F</etc>, using
2110C<stat>, and C<IO::AIO::aio_stat>.
2111
2112 if (stat "/etc") {
2113 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
2114 }
2115
2116 IO::AIO::aio_stat "/etc", sub {
2117 $_[0]
2118 and return;
2119
2120 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
2121 };
2122
2123 IO::AIO::flush;
2124
2125Output of the awbove on my system, showing reduced and full accuracy:
2126
2127 stat(/etc) mtime: 1534043702.020808
2128 aio_stat(/etc) mtime: 1534043702.020807792
2129
2013 2130
2014=head3 MISCELLANEOUS FUNCTIONS 2131=head3 MISCELLANEOUS FUNCTIONS
2015 2132
2016IO::AIO implements some functions that are useful when you want to use 2133IO::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 2134some "Advanced I/O" function not available to in Perl, without going the
… …
2158 2275
2159=item IO::AIO::munmap $scalar 2276=item IO::AIO::munmap $scalar
2160 2277
2161Removes a previous mmap and undefines the C<$scalar>. 2278Removes a previous mmap and undefines the C<$scalar>.
2162 2279
2280=item IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[, $new_address = 0]
2281
2282Calls the Linux-specific mremap(2) system call. The C<$scalar> must have
2283been mapped by C<IO::AIO::mmap>, and C<$flags> must currently either be
2284C<0> or C<IO::AIO::MREMAP_MAYMOVE>.
2285
2286Returns true if successful, and false otherwise. If the underlying mmapped
2287region has changed address, then the true value has the numerical value
2288C<1>, otherwise it has the numerical value C<0>:
2289
2290 my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
2291 or die "mremap: $!";
2292
2293 if ($success*1) {
2294 warn "scalar has chanegd address in memory\n";
2295 }
2296
2297C<IO::AIO::MREMAP_FIXED> and the C<$new_address> argument are currently
2298implemented, but not supported and might go away in a future version.
2299
2300On systems where this call is not supported or is not emulated, this call
2301returns falls and sets C<$!> to C<ENOSYS>.
2302
2163=item IO::AIO::munlock $scalar, $offset = 0, $length = undef 2303=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2164 2304
2165Calls the C<munlock> function, undoing the effects of a previous 2305Calls the C<munlock> function, undoing the effects of a previous
2166C<aio_mlock> call (see its description for details). 2306C<aio_mlock> call (see its description for details).
2167 2307

Diff Legend

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