[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.288 by root, Tue Jul 31 22:27:49 2018 UTC vs.
Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC

…		…
171	use common::sense;	171	use common::sense;
172		172
173	use base 'Exporter';	173	use base 'Exporter';
174		174
175	BEGIN {	175	BEGIN {
176	our $VERSION = 4.5;	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
…		…
541		541
542	=item aio_stat $fh_or_path, $callback->($status)	542	=item aio_stat $fh_or_path, $callback->($status)
543		543
544	=item aio_lstat $fh, $callback->($status)	544	=item aio_lstat $fh, $callback->($status)
545		545
546	Works like perl's C<stat> or C<lstat> in void context. The callback will	546	Works almost exactly like perl's C<stat> or C<lstat> in void context. The
547	be called after the stat and the results will be available using C<stat _>	547	callback will be called after the stat and the results will be available
548	or C<-s _> etc...	548	using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
		549	and C<-T>).
549		550
550	The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,	551	The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
551	for an explanation.	552	for an explanation.
552		553
553	Currently, the stats are always 64-bit-stats, i.e. instead of returning an	554	Currently, the stats are always 64-bit-stats, i.e. instead of returning an
…		…
560	behaviour).	561	behaviour).
561		562
562	C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,	563	C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
563	C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,	564	C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
564	C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.	565	C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
		566
		567	To access higher resolution stat timestamps, see L<SUBSECOND STAT TIME
		568	ACCESS>.
565		569
566	Example: Print the length of F</etc/passwd>:	570	Example: Print the length of F</etc/passwd>:
567		571
568	aio_stat "/etc/passwd", sub {	572	aio_stat "/etc/passwd", sub {
569	$_[0] and die "stat failed: $!";	573	$_[0] and die "stat failed: $!";
…		…
619		623
620	Works like perl's C<utime> function (including the special case of $atime	624	Works like perl's C<utime> function (including the special case of $atime
621	and $mtime being undef). Fractional times are supported if the underlying	625	and $mtime being undef). Fractional times are supported if the underlying
622	syscalls support them.	626	syscalls support them.
623		627
624	When called with a pathname, uses utimes(2) if available, otherwise	628	When called with a pathname, uses utimensat(2) or utimes(2) if available,
625	utime(2). If called on a file descriptor, uses futimes(2) if available,	629	otherwise utime(2). If called on a file descriptor, uses futimens(2)
626	otherwise returns ENOSYS, so this is not portable.	630	or futimes(2) if available, otherwise returns ENOSYS, so this is not
		631	portable.
627		632
628	Examples:	633	Examples:
629		634
630	# set atime and mtime to current time (basically touch(1)):	635	# set atime and mtime to current time (basically touch(1)):
631	aio_utime "path", undef, undef;	636	aio_utime "path", undef, undef;
…		…
1779	The default value for the limit is C<0>, but note that setting a feeder	1784	The default value for the limit is C<0>, but note that setting a feeder
1780	automatically bumps it up to C<2>.	1785	automatically bumps it up to C<2>.
1781		1786
1782	=back	1787	=back
1783		1788
		1789
1784	=head2 SUPPORT FUNCTIONS	1790	=head2 SUPPORT FUNCTIONS
1785		1791
1786	=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION	1792	=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1787		1793
1788	=over 4	1794	=over 4
…		…
1853	Strictly equivalent to:	1859	Strictly equivalent to:
1854		1860
1855	IO::AIO::poll_wait, IO::AIO::poll_cb	1861	IO::AIO::poll_wait, IO::AIO::poll_cb
1856	while IO::AIO::nreqs;	1862	while IO::AIO::nreqs;
1857		1863
		1864	This function can be useful at program aborts, to make sure outstanding
		1865	I/O has been done (C<IO::AIO> uses an C<END> block which already calls
		1866	this function on normal exits), or when you are merely using C<IO::AIO>
		1867	for 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
1858	=item IO::AIO::max_poll_reqs $nreqs	1874	=item IO::AIO::max_poll_reqs $nreqs
1859		1875
1860	=item IO::AIO::max_poll_time $seconds	1876	=item IO::AIO::max_poll_time $seconds
1861		1877
1862	These set the maximum number of requests (default C<0>, meaning infinity)	1878	These set the maximum number of requests (default C<0>, meaning infinity)
…		…
1888	poll => 'r', nice => 1,	1904	poll => 'r', nice => 1,
1889	cb => &IO::AIO::poll_cb);	1905	cb => &IO::AIO::poll_cb);
1890		1906
1891	=back	1907	=back
1892		1908
		1909
1893	=head3 CONTROLLING THE NUMBER OF THREADS	1910	=head3 CONTROLLING THE NUMBER OF THREADS
1894		1911
1895	=over	1912	=over
1896		1913
1897	=item IO::AIO::min_parallel $nthreads	1914	=item IO::AIO::min_parallel $nthreads
…		…
1984	The default value for C<max_outstanding> is very large, so there is no	2001	The default value for C<max_outstanding> is very large, so there is no
1985	practical limit on the number of outstanding requests.	2002	practical limit on the number of outstanding requests.
1986		2003
1987	=back	2004	=back
1988		2005
		2006
1989	=head3 STATISTICAL INFORMATION	2007	=head3 STATISTICAL INFORMATION
1990		2008
1991	=over	2009	=over
1992		2010
1993	=item IO::AIO::nreqs	2011	=item IO::AIO::nreqs
…		…
2009		2027
2010	Returns the number of requests currently in the pending state (executed,	2028	Returns the number of requests currently in the pending state (executed,
2011	but not yet processed by poll_cb).	2029	but not yet processed by poll_cb).
2012		2030
2013	=back	2031	=back
		2032
		2033
		2034	=head3 SUBSECOND STAT TIME ACCESS
		2035
		2036	Both C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> functions can
		2037	generally find access/modification and change times with subsecond time
		2038	accuracy of the system supports it, but perl's built-in functions only
		2039	return the integer part.
		2040
		2041	The following functions return the timestamps of the most recent
		2042	stat with subsecond precision on most systems and work both after
		2043	C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> calls. Their return
		2044	value is only meaningful after a successful C<stat>/C<lstat> call, or
		2045	during/after a successful C<aio_stat>/C<aio_lstat> callback.
		2046
		2047	This is similar to the L<Time::HiRes> C<stat> functions, but can return
		2048	full resolution without rounding and work with standard perl C<stat>,
		2049	alleviating the need to call the special C<Time::HiRes> functions, which
		2050	do not act like their perl counterparts.
		2051
		2052	On operating systems or file systems where subsecond time resolution is
		2053	not supported or could not be detected, a fractional part of C<0> is
		2054	returned, 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
		2060	Return the access, modication, change or birth time, respectively,
		2061	including fractional part. Due to the limited precision of floating point,
		2062	the accuracy on most platforms is only a bit better than milliseconds
		2063	for times around now - see the I<nsec> function family, below, for full
		2064	accuracy.
		2065
		2066	File birth time is only available when the OS and perl support it (on
		2067	FreeBSD and NetBSD at the time of this writing, although support is
		2068	adaptive, so if your OS/perl gains support, IO::AIO can take avdantage of
		2069	it). On systems where it isn't available, C<0> is currently returned, but
		2070	this might change to C<undef> in a future version.
		2071
		2072	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		2073
		2074	Returns access, modification, change and birth time all in one go, and
		2075	maybe 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
		2079	Return the fractional access, modifcation, change or birth time, in nanoseconds,
		2080	as an integer in the range C<0> to C<999999999>.
		2081
		2082	Note that no accessors are provided for access, modification and
		2083	change times - you need to get those from C<stat _> if required (C<int
		2084	IO::AIO::st_atime> and so on will I<not> generally give you the correct
		2085	value).
		2086
		2087	=item $seconds = IO::AIO::st_btimesec
		2088
		2089	The (integral) seconds part of the file birth time, if available.
		2090
		2091	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		2092
		2093	Like the functions above, but returns all four times in one go (and maybe
		2094	more in future versions).
		2095
		2096	=item $counter = IO::AIO::st_gen
		2097
		2098	Returns the generation counter (in practice this is just a random number)
		2099	of the file. This is only available on platforms which have this member in
		2100	their C<struct stat> (most BSDs at the time of this writing) and generally
		2101	only to the root usert. If unsupported, C<0> is returned, but this might
		2102	change to C<undef> in a future version.
		2103
		2104	=back
		2105
		2106	Example: print the high resolution modification time of F</etc>, using
		2107	C<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
		2122	Output 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
2014		2127
2015	=head3 MISCELLANEOUS FUNCTIONS	2128	=head3 MISCELLANEOUS FUNCTIONS
2016		2129
2017	IO::AIO implements some functions that are useful when you want to use	2130	IO::AIO implements some functions that are useful when you want to use
2018	some "Advanced I/O" function not available to in Perl, without going the	2131	some "Advanced I/O" function not available to in Perl, without going the

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.288 by root, Tue Jul 31 22:27:49 2018 UTC vs. Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.288 by root, Tue Jul 31 22:27:49 2018 UTC vs.
Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC