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.282 by root, Tue Feb 20 05:23:47 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;
… …
789 795
790=over 4 796=over 4
791 797
792=item IO::AIO::READDIR_DENTS 798=item IO::AIO::READDIR_DENTS
793 799
794When this flag is off, then the callback gets an arrayref consisting of 800Normally the callback gets an arrayref consisting of names only (as
795names only (as with C<aio_readdir>), otherwise it gets an arrayref with 801with C<aio_readdir>). If this flag is set, then the callback gets an
796C<[$name, $type, $inode]> arrayrefs, each describing a single directory 802arrayref with C<[$name, $type, $inode]> arrayrefs, each describing a
797entry in more detail. 803single directory entry in more detail:
798 804
799C<$name> is the name of the entry. 805C<$name> is the name of the entry.
800 806
801C<$type> is one of the C<IO::AIO::DT_xxx> constants: 807C<$type> is one of the C<IO::AIO::DT_xxx> constants:
802 808
803C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>, 809C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>,
804C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>, 810C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>,
805C<IO::AIO::DT_WHT>. 811C<IO::AIO::DT_WHT>.
806 812
807C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to 813C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need
808know, you have to run stat yourself. Also, for speed reasons, the C<$type> 814to know, you have to run stat yourself. Also, for speed/memory reasons,
809scalars are read-only: you can not modify them. 815the C<$type> scalars are read-only: you must not modify them.
810 816
811C<$inode> is the inode number (which might not be exact on systems with 64 817C<$inode> is the inode number (which might not be exact on systems with 64
812bit inode numbers and 32 bit perls). This field has unspecified content on 818bit inode numbers and 32 bit perls). This field has unspecified content on
813systems that do not deliver the inode information. 819systems that do not deliver the inode information.
814 820
… …
825short names are tried first. 831short names are tried first.
826 832
827=item IO::AIO::READDIR_STAT_ORDER 833=item IO::AIO::READDIR_STAT_ORDER
828 834
829When this flag is set, then the names will be returned in an order 835When this flag is set, then the names will be returned in an order
830suitable for stat()'ing each one. That is, when you plan to stat() 836suitable for stat()'ing each one. That is, when you plan to stat() most or
831all files in the given directory, then the returned order will likely 837all files in the given directory, then the returned order will likely be
832be fastest. 838faster.
833 839
834If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then 840If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified,
835the likely dirs come first, resulting in a less optimal stat order. 841then the likely dirs come first, resulting in a less optimal stat order
842for stat'ing all entries, but likely a more optimal order for finding
843subdirectories.
836 844
837=item IO::AIO::READDIR_FOUND_UNKNOWN 845=item IO::AIO::READDIR_FOUND_UNKNOWN
838 846
839This flag should not be set when calling C<aio_readdirx>. Instead, it 847This flag should not be set when calling C<aio_readdirx>. Instead, it
840is being set by C<aio_readdirx>, when any of the C<$type>'s found were 848is being set by C<aio_readdirx>, when any of the C<$type>'s found were
… …
1776The 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
1777automatically bumps it up to C<2>. 1785automatically bumps it up to C<2>.
1778 1786
1779=back 1787=back
1780 1788
1789
1781=head2 SUPPORT FUNCTIONS 1790=head2 SUPPORT FUNCTIONS
1782 1791
1783=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 1792=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1784 1793
1785=over 4 1794=over 4
… …
1850Strictly equivalent to: 1859Strictly equivalent to:
1851 1860
1852 IO::AIO::poll_wait, IO::AIO::poll_cb 1861 IO::AIO::poll_wait, IO::AIO::poll_cb
1853 while IO::AIO::nreqs; 1862 while IO::AIO::nreqs;
1854 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
1855=item IO::AIO::max_poll_reqs $nreqs 1874=item IO::AIO::max_poll_reqs $nreqs
1856 1875
1857=item IO::AIO::max_poll_time $seconds 1876=item IO::AIO::max_poll_time $seconds
1858 1877
1859These set the maximum number of requests (default C<0>, meaning infinity) 1878These set the maximum number of requests (default C<0>, meaning infinity)
… …
1885 poll => 'r', nice => 1, 1904 poll => 'r', nice => 1,
1886 cb => &IO::AIO::poll_cb); 1905 cb => &IO::AIO::poll_cb);
1887 1906
1888=back 1907=back
1889 1908
1909
1890=head3 CONTROLLING THE NUMBER OF THREADS 1910=head3 CONTROLLING THE NUMBER OF THREADS
1891 1911
1892=over 1912=over
1893 1913
1894=item IO::AIO::min_parallel $nthreads 1914=item IO::AIO::min_parallel $nthreads
… …
1981The 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
1982practical limit on the number of outstanding requests. 2002practical limit on the number of outstanding requests.
1983 2003
1984=back 2004=back
1985 2005
2006
1986=head3 STATISTICAL INFORMATION 2007=head3 STATISTICAL INFORMATION
1987 2008
1988=over 2009=over
1989 2010
1990=item IO::AIO::nreqs 2011=item IO::AIO::nreqs
… …
2006 2027
2007Returns the number of requests currently in the pending state (executed, 2028Returns the number of requests currently in the pending state (executed,
2008but not yet processed by poll_cb). 2029but not yet processed by poll_cb).
2009 2030
2010=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
2011 2127
2012=head3 MISCELLANEOUS FUNCTIONS 2128=head3 MISCELLANEOUS FUNCTIONS
2013 2129
2014IO::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
2015some "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
… …
2156 2272
2157=item IO::AIO::munmap $scalar 2273=item IO::AIO::munmap $scalar
2158 2274
2159Removes a previous mmap and undefines the C<$scalar>. 2275Removes a previous mmap and undefines the C<$scalar>.
2160 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
2161=item IO::AIO::munlock $scalar, $offset = 0, $length = undef 2300=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2162 2301
2163Calls the C<munlock> function, undoing the effects of a previous 2302Calls the C<munlock> function, undoing the effects of a previous
2164C<aio_mlock> call (see its description for details). 2303C<aio_mlock> call (see its description for details).
2165 2304
… …
2404temporary buffers, and each thread requires a stack and other data 2543temporary buffers, and each thread requires a stack and other data
2405structures (usually around 16k-128k, depending on the OS). 2544structures (usually around 16k-128k, depending on the OS).
2406 2545
2407=head1 KNOWN BUGS 2546=head1 KNOWN BUGS
2408 2547
2409Known bugs will be fixed in the next release. 2548Known bugs will be fixed in the next release :)
2549
2550=head1 KNOWN ISSUES
2551
2552Calls that try to "import" foreign memory areas (such as C<IO::AIO::mmap>
2553or C<IO::AIO::aio_slurp>) do not work with generic lvalues, such as
2554non-created hash slots or other scalars I didn't think of. It's best to
2555avoid such and either use scalar variables or making sure that the scalar
2556exists (e.g. by storing C<undef>) and isn't "funny" (e.g. tied).
2557
2558I am not sure anything can be done about this, so this is considered a
2559known issue, rather than a bug.
2410 2560
2411=head1 SEE ALSO 2561=head1 SEE ALSO
2412 2562
2413L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a 2563L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2414more natural syntax. 2564more natural syntax.

Diff Legend

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