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.292 by root, Tue Aug 14 09:29:50 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.53;
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
… …
559behaviour). 560behaviour).
560 561
561C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>, 562C<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>, 563C<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>. 564C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
565
566To access higher resolution stat timestamps, see L<SUBSECOND STAT TIME
567ACCESS>.
564 568
565Example: Print the length of F</etc/passwd>: 569Example: Print the length of F</etc/passwd>:
566 570
567 aio_stat "/etc/passwd", sub { 571 aio_stat "/etc/passwd", sub {
568 $_[0] and die "stat failed: $!"; 572 $_[0] and die "stat failed: $!";
… …
789 793
790=over 4 794=over 4
791 795
792=item IO::AIO::READDIR_DENTS 796=item IO::AIO::READDIR_DENTS
793 797
794When this flag is off, then the callback gets an arrayref consisting of 798Normally the callback gets an arrayref consisting of names only (as
795names only (as with C<aio_readdir>), otherwise it gets an arrayref with 799with C<aio_readdir>). If this flag is set, then the callback gets an
796C<[$name, $type, $inode]> arrayrefs, each describing a single directory 800arrayref with C<[$name, $type, $inode]> arrayrefs, each describing a
797entry in more detail. 801single directory entry in more detail:
798 802
799C<$name> is the name of the entry. 803C<$name> is the name of the entry.
800 804
801C<$type> is one of the C<IO::AIO::DT_xxx> constants: 805C<$type> is one of the C<IO::AIO::DT_xxx> constants:
802 806
803C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>, 807C<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>, 808C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>,
805C<IO::AIO::DT_WHT>. 809C<IO::AIO::DT_WHT>.
806 810
807C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to 811C<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> 812to know, you have to run stat yourself. Also, for speed/memory reasons,
809scalars are read-only: you can not modify them. 813the C<$type> scalars are read-only: you must not modify them.
810 814
811C<$inode> is the inode number (which might not be exact on systems with 64 815C<$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 816bit inode numbers and 32 bit perls). This field has unspecified content on
813systems that do not deliver the inode information. 817systems that do not deliver the inode information.
814 818
… …
825short names are tried first. 829short names are tried first.
826 830
827=item IO::AIO::READDIR_STAT_ORDER 831=item IO::AIO::READDIR_STAT_ORDER
828 832
829When this flag is set, then the names will be returned in an order 833When 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() 834suitable 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 835all files in the given directory, then the returned order will likely be
832be fastest. 836faster.
833 837
834If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then 838If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified,
835the likely dirs come first, resulting in a less optimal stat order. 839then the likely dirs come first, resulting in a less optimal stat order
840for stat'ing all entries, but likely a more optimal order for finding
841subdirectories.
836 842
837=item IO::AIO::READDIR_FOUND_UNKNOWN 843=item IO::AIO::READDIR_FOUND_UNKNOWN
838 844
839This flag should not be set when calling C<aio_readdirx>. Instead, it 845This 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 846is being set by C<aio_readdirx>, when any of the C<$type>'s found were
… …
2007Returns the number of requests currently in the pending state (executed, 2013Returns the number of requests currently in the pending state (executed,
2008but not yet processed by poll_cb). 2014but not yet processed by poll_cb).
2009 2015
2010=back 2016=back
2011 2017
2018=head3 SUBSECOND STAT TIME ACCESS
2019
2020Both C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> functions can
2021generally find access/modification and change times with subsecond time
2022accuracy of the system supports it, but perl's built-in functions only
2023return the integer part.
2024
2025The following functions return the timestamps of the most recent
2026stat with subsecond precision on most systems and work both after
2027C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> calls. Their return
2028value is only meaningful after a successful C<stat>/C<lstat> call, or
2029during/after a successful C<aio_stat>/C<aio_lstat> callback.
2030
2031This is similar to the L<Time::HiRes> C<stat> functions, but can return
2032full resolution without rounding and work with standard perl C<stat>,
2033alleviating the need to call the special C<Time::HiRes> functions, which
2034do not act like their perl counterparts.
2035
2036On operating systems or file systems where subsecond time resolution is
2037not supported or could not be detected, a fractional part of C<0> is
2038returned, so it is always safe to call these functions.
2039
2040=over 4
2041
2042=item $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime
2043
2044Return the access, modication or change time, respectively, including
2045fractional part. Due to the limited precision of floating point, the
2046accuracy on most platforms is only a bit better than milliseconds for
2047times around now - see the I<nsec> function family, below, for full
2048accuracy.
2049
2050=item ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtime
2051
2052Returns access, modification and change time all in one go, and maybe more
2053times in the future version.
2054
2055=item $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec
2056
2057Return the fractional access, modifcation or change time, in nanoseconds,
2058as an integer in the range C<0> to C<999999999>.
2059
2060=item ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtimensec
2061
2062Like the functions above, but returns all three times in one go (and maybe
2063more in future versions).
2064
2065=back
2066
2067Example: print the high resolution modification time of F</etc>, using
2068C<stat>, and C<IO::AIO::aio_stat>.
2069
2070 if (stat "/etc") {
2071 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
2072 }
2073
2074 IO::AIO::aio_stat "/etc", sub {
2075 $_[0]
2076 and return;
2077
2078 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
2079 };
2080
2081 IO::AIO::flush;
2082
2083Output of the awbove on my system, showing reduced and full accuracy:
2084
2085 stat(/etc) mtime: 1534043702.020808
2086 aio_stat(/etc) mtime: 1534043702.020807792
2087
2012=head3 MISCELLANEOUS FUNCTIONS 2088=head3 MISCELLANEOUS FUNCTIONS
2013 2089
2014IO::AIO implements some functions that are useful when you want to use 2090IO::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 2091some "Advanced I/O" function not available to in Perl, without going the
2016"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*> 2092"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
… …
2156 2232
2157=item IO::AIO::munmap $scalar 2233=item IO::AIO::munmap $scalar
2158 2234
2159Removes a previous mmap and undefines the C<$scalar>. 2235Removes a previous mmap and undefines the C<$scalar>.
2160 2236
2237=item IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[, $new_address = 0]
2238
2239Calls the Linux-specific mremap(2) system call. The C<$scalar> must have
2240been mapped by C<IO::AIO::mmap>, and C<$flags> must currently either be
2241C<0> or C<IO::AIO::MREMAP_MAYMOVE>.
2242
2243Returns true if successful, and false otherwise. If the underlying mmapped
2244region has changed address, then the true value has the numerical value
2245C<1>, otherwise it has the numerical value C<0>:
2246
2247 my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
2248 or die "mremap: $!";
2249
2250 if ($success*1) {
2251 warn "scalar has chanegd address in memory\n";
2252 }
2253
2254C<IO::AIO::MREMAP_FIXED> and the C<$new_address> argument are currently
2255implemented, but not supported and might go away in a future version.
2256
2257On systems where this call is not supported or is not emulated, this call
2258returns falls and sets C<$!> to C<ENOSYS>.
2259
2161=item IO::AIO::munlock $scalar, $offset = 0, $length = undef 2260=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2162 2261
2163Calls the C<munlock> function, undoing the effects of a previous 2262Calls the C<munlock> function, undoing the effects of a previous
2164C<aio_mlock> call (see its description for details). 2263C<aio_mlock> call (see its description for details).
2165 2264
… …
2404temporary buffers, and each thread requires a stack and other data 2503temporary buffers, and each thread requires a stack and other data
2405structures (usually around 16k-128k, depending on the OS). 2504structures (usually around 16k-128k, depending on the OS).
2406 2505
2407=head1 KNOWN BUGS 2506=head1 KNOWN BUGS
2408 2507
2409Known bugs will be fixed in the next release. 2508Known bugs will be fixed in the next release :)
2509
2510=head1 KNOWN ISSUES
2511
2512Calls that try to "import" foreign memory areas (such as C<IO::AIO::mmap>
2513or C<IO::AIO::aio_slurp>) do not work with generic lvalues, such as
2514non-created hash slots or other scalars I didn't think of. It's best to
2515avoid such and either use scalar variables or making sure that the scalar
2516exists (e.g. by storing C<undef>) and isn't "funny" (e.g. tied).
2517
2518I am not sure anything can be done about this, so this is considered a
2519known issue, rather than a bug.
2410 2520
2411=head1 SEE ALSO 2521=head1 SEE ALSO
2412 2522
2413L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a 2523L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2414more natural syntax. 2524more natural syntax.

Diff Legend

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