1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOC] Process doc (#8363)

Browse Source
This commit is contained in:
Burdette Lamar 2023-09-03 14:36:51 -05:00 committed by GitHub
parent 3602e253e7
commit 40ab77eb3d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
Notes: git 2023-09-03 19:37:13 +00:00 
Merged-By: peterzhu2118 <peter@peterzhu.ca>
1 changed files with 164 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
process.c
View File

@ -8096,89 +8096,106 @@ ruby_real_ms_time(void)
/* /*
* call-seq: * call-seq:
* Process.clock_gettime(clock_id [, unit]) -> number * Process.clock_gettime(clock_id, unit = :float_second) -> number
* *
* Returns a time returned by POSIX clock_gettime() function. * Returns a clock time as determined by POSIX function
* {clock_gettime()}[https://man7.org/linux/man-pages/man3/clock_gettime.3.html]:
* *
* p Process.clock_gettime(Process::CLOCK_MONOTONIC) * Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID) # => 198.650379677
* #=> 896053.968060096
* *
* +clock_id+ specifies a kind of clock. * Argument +clock_id+ should be a symbol or a constant that specifies
* It is specified as a constant which begins with <code>Process::CLOCK_</code> * the clock whose time is to be returned;
* such as Process::CLOCK_REALTIME and Process::CLOCK_MONOTONIC. * see below.
* *
* The supported constants depends on OS and version. * Optional argument +unit+ should be a symbol that specifies
* Ruby provides following types of +clock_id+ if available. * the unit to be used in the returned clock time;
* see below.
* *
* [CLOCK_REALTIME] SUSv2 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 2.1, macOS 10.12, Windows-8/Server-2012 * <b>Argument +clock_id+</b>
* [CLOCK_MONOTONIC] SUSv3 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 3.4, macOS 10.12, Windows-2000 *
* [CLOCK_PROCESS_CPUTIME_ID] SUSv3 to 4, Linux 2.5.63, FreeBSD 9.3, OpenBSD 5.4, macOS 10.12 * Argument +clock_id+ specifies the clock whose time is to be returned;
* [CLOCK_THREAD_CPUTIME_ID] SUSv3 to 4, Linux 2.5.63, FreeBSD 7.1, OpenBSD 5.4, macOS 10.12 * it may be a constant such as <tt>Process::CLOCK_REALTIME</tt>,
* [CLOCK_VIRTUAL] FreeBSD 3.0, OpenBSD 2.1 * or a symbol shorthand such as +:CLOCK_REALTIME+.
* [CLOCK_PROF] FreeBSD 3.0, OpenBSD 2.1 *
* [CLOCK_REALTIME_FAST] FreeBSD 8.1 * The supported clocks depend on the underlying operating system;
* [CLOCK_REALTIME_PRECISE] FreeBSD 8.1 * this method supports the following clocks on the indicated platforms
* [CLOCK_REALTIME_COARSE] Linux 2.6.32 * (raises Errno::EINVAL if called with an unsupported clock):
* [CLOCK_REALTIME_ALARM] Linux 3.0 *
* [CLOCK_MONOTONIC_FAST] FreeBSD 8.1 * - +:CLOCK_BOOTTIME+: Linux 2.6.39.
* [CLOCK_MONOTONIC_PRECISE] FreeBSD 8.1 * - +:CLOCK_BOOTTIME_ALARM+: Linux 3.0.
* [CLOCK_MONOTONIC_COARSE] Linux 2.6.32 * - +:CLOCK_MONOTONIC+: SUSv3 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 3.4, macOS 10.12, Windows-2000.
* [CLOCK_MONOTONIC_RAW] Linux 2.6.28, macOS 10.12 * - +:CLOCK_MONOTONIC_COARSE+: Linux 2.6.32.
* [CLOCK_MONOTONIC_RAW_APPROX] macOS 10.12 * - +:CLOCK_MONOTONIC_FAST+: FreeBSD 8.1.
* [CLOCK_BOOTTIME] Linux 2.6.39 * - +:CLOCK_MONOTONIC_PRECISE+: FreeBSD 8.1.
* [CLOCK_BOOTTIME_ALARM] Linux 3.0 * - +:CLOCK_MONOTONIC_RAW+: Linux 2.6.28, macOS 10.12.
* [CLOCK_UPTIME] FreeBSD 7.0, OpenBSD 5.5 * - +:CLOCK_MONOTONIC_RAW_APPROX+: macOS 10.12.
* [CLOCK_UPTIME_FAST] FreeBSD 8.1 * - +:CLOCK_PROCESS_CPUTIME_ID+: SUSv3 to 4, Linux 2.5.63, FreeBSD 9.3, OpenBSD 5.4, macOS 10.12.
* [CLOCK_UPTIME_RAW] macOS 10.12 * - +:CLOCK_PROF+: FreeBSD 3.0, OpenBSD 2.1.
* [CLOCK_UPTIME_RAW_APPROX] macOS 10.12 * - +:CLOCK_REALTIME+: SUSv2 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 2.1, macOS 10.12, Windows-8/Server-2012.
* [CLOCK_UPTIME_PRECISE] FreeBSD 8.1 * Time.now is recommended over +:CLOCK_REALTIME:.
* [CLOCK_SECOND] FreeBSD 8.1 * - +:CLOCK_REALTIME_ALARM+: Linux 3.0.
* [CLOCK_TAI] Linux 3.10 * - +:CLOCK_REALTIME_COARSE+: Linux 2.6.32.
* - +:CLOCK_REALTIME_FAST+: FreeBSD 8.1.
* - +:CLOCK_REALTIME_PRECISE+: FreeBSD 8.1.
* - +:CLOCK_SECOND+: FreeBSD 8.1.
* - +:CLOCK_TAI+: Linux 3.10.
* - +:CLOCK_THREAD_CPUTIME_ID+: SUSv3 to 4, Linux 2.5.63, FreeBSD 7.1, OpenBSD 5.4, macOS 10.12.
* - +:CLOCK_UPTIME+: FreeBSD 7.0, OpenBSD 5.5.
* - +:CLOCK_UPTIME_FAST+: FreeBSD 8.1.
* - +:CLOCK_UPTIME_PRECISE+: FreeBSD 8.1.
* - +:CLOCK_UPTIME_RAW+: macOS 10.12.
* - +:CLOCK_UPTIME_RAW_APPROX+: macOS 10.12.
* - +:CLOCK_VIRTUAL+: FreeBSD 3.0, OpenBSD 2.1.
* *
* Note that SUS stands for Single Unix Specification. * Note that SUS stands for Single Unix Specification.
* SUS contains POSIX and clock_gettime is defined in the POSIX part. * SUS contains POSIX and clock_gettime is defined in the POSIX part.
* SUS defines CLOCK_REALTIME mandatory but * SUS defines +:CLOCK_REALTIME+ as mandatory but
* CLOCK_MONOTONIC, CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID are optional. * +:CLOCK_MONOTONIC+, +:CLOCK_PROCESS_CPUTIME_ID+,
* and +:CLOCK_THREAD_CPUTIME_ID+ are optional.
* *
* Also, several symbols are accepted as +clock_id+. * Certain emulations are used when the given +clock_id+
* There are emulations for clock_gettime(). * is not supported directly:
* *
* For example, Process::CLOCK_REALTIME is defined as * - Emulations for +:CLOCK_REALTIME+:
* +:GETTIMEOFDAY_BASED_CLOCK_REALTIME+ when clock_gettime() is not available.
* *
* Emulations for +CLOCK_REALTIME+: * - +:GETTIMEOFDAY_BASED_CLOCK_REALTIME+:
* [:GETTIMEOFDAY_BASED_CLOCK_REALTIME] * Use gettimeofday() defined by SUS (deprecated in SUSv4).
* Use gettimeofday() defined by SUS.
* (SUSv4 obsoleted it, though.)
* The resolution is 1 microsecond. * The resolution is 1 microsecond.
* [:TIME_BASED_CLOCK_REALTIME] * - +:TIME_BASED_CLOCK_REALTIME+:
* Use time() defined by ISO C. * Use time() defined by ISO C.
* The resolution is 1 second. * The resolution is 1 second.
* *
* Emulations for +CLOCK_MONOTONIC+: * - Emulations for +:CLOCK_MONOTONIC+:
* [:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC] *
* - +:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC+:
* Use mach_absolute_time(), available on Darwin. * Use mach_absolute_time(), available on Darwin.
* The resolution is CPU dependent. * The resolution is CPU dependent.
* [:TIMES_BASED_CLOCK_MONOTONIC] * - +:TIMES_BASED_CLOCK_MONOTONIC+:
* Use the result value of times() defined by POSIX. * Use the result value of times() defined by POSIX, thus:
* POSIX defines it as "times() shall return the elapsed real time, in clock ticks, since an arbitrary point in the past (for example, system start-up time)". * >>>
* Upon successful completion, times() shall return the elapsed real time,
* in clock ticks, since an arbitrary point in the past
* (for example, system start-up time).
*
* For example, GNU/Linux returns a value based on jiffies and it is monotonic. * For example, GNU/Linux returns a value based on jiffies and it is monotonic.
* However, 4.4BSD uses gettimeofday() and it is not monotonic. * However, 4.4BSD uses gettimeofday() and it is not monotonic.
* (FreeBSD uses clock_gettime(CLOCK_MONOTONIC) instead, though.) * (FreeBSD uses +:CLOCK_MONOTONIC+ instead, though.)
*
* The resolution is the clock tick. * The resolution is the clock tick.
* "getconf CLK_TCK" command shows the clock ticks per second. * "getconf CLK_TCK" command shows the clock ticks per second.
* (The clock ticks per second is defined by HZ macro in older systems.) * (The clock ticks-per-second is defined by HZ macro in older systems.)
* If it is 100 and clock_t is 32 bits integer type, the resolution is 10 millisecond and * If it is 100 and clock_t is 32 bits integer type,
* cannot represent over 497 days. * the resolution is 10 millisecond and cannot represent over 497 days.
* *
* Emulations for +CLOCK_PROCESS_CPUTIME_ID+: * - Emulations for +:CLOCK_PROCESS_CPUTIME_ID+:
* [:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID] *
* - +:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID+:
* Use getrusage() defined by SUS. * Use getrusage() defined by SUS.
* getrusage() is used with RUSAGE_SELF to obtain the time only for * getrusage() is used with RUSAGE_SELF to obtain the time only for
* the calling process (excluding the time for child processes). * the calling process (excluding the time for child processes).
* The result is addition of user time (ru_utime) and system time (ru_stime). * The result is addition of user time (ru_utime) and system time (ru_stime).
* The resolution is 1 microsecond. * The resolution is 1 microsecond.
* [:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID] * - +:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID+:
* Use times() defined by POSIX. * Use times() defined by POSIX.
* The result is addition of user time (tms_utime) and system time (tms_stime). * The result is addition of user time (tms_utime) and system time (tms_stime).
* tms_cutime and tms_cstime are ignored to exclude the time for child processes. * tms_cutime and tms_cstime are ignored to exclude the time for child processes.
@ -8186,40 +8203,60 @@ ruby_real_ms_time(void)
* "getconf CLK_TCK" command shows the clock ticks per second. * "getconf CLK_TCK" command shows the clock ticks per second.
* (The clock ticks per second is defined by HZ macro in older systems.) * (The clock ticks per second is defined by HZ macro in older systems.)
* If it is 100, the resolution is 10 millisecond. * If it is 100, the resolution is 10 millisecond.
* [:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID] * - +:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID+:
* Use clock() defined by ISO C. * Use clock() defined by ISO C.
* The resolution is 1/CLOCKS_PER_SEC. * The resolution is <tt>1/CLOCKS_PER_SEC</tt>.
* CLOCKS_PER_SEC is the C-level macro defined by time.h. * +CLOCKS_PER_SEC+ is the C-level macro defined by time.h.
* SUS defines CLOCKS_PER_SEC is 1000000. * SUS defines +CLOCKS_PER_SEC+ as 1000000;
* Non-Unix systems may define it a different value, though. * other systems may define it differently.
* If CLOCKS_PER_SEC is 1000000 as SUS, the resolution is 1 microsecond. * If +CLOCKS_PER_SEC+ is 1000000 (as in SUS),
* If CLOCKS_PER_SEC is 1000000 and clock_t is 32 bits integer type, it cannot represent over 72 minutes. * the resolution is 1 microsecond.
* If +CLOCKS_PER_SEC+ is 1000000 and clock_t is a 32-bit integer type,
* it cannot represent over 72 minutes.
* *
* If the given +clock_id+ is not supported, Errno::EINVAL is raised. * <b>Argument +unit+</b>
* *
* +unit+ specifies a type of the return value. * Optional argument +unit+ (default +:float_second+)
* specifies the unit for the returned value.
* *
* [:float_second] number of seconds as a float (default) * - +:float_microsecond+: Number of microseconds as a float.
* [:float_millisecond] number of milliseconds as a float * - +:float_millisecond+: Number of milliseconds as a float.
* [:float_microsecond] number of microseconds as a float * - +:float_second+: Number of seconds as a float.
* [:second] number of seconds as an integer * - +:microsecond+: Number of microseconds as an integer.
* [:millisecond] number of milliseconds as an integer * - +:millisecond+: Number of milliseconds as an integer.
* [:microsecond] number of microseconds as an integer * - +:nanosecond+: Number of nanoseconds as an integer.
* [:nanosecond] number of nanoseconds as an integer * - +::second+: Number of seconds as an integer.
*
* Examples:
*
* Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond)
* # => 203605054.825
* Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_millisecond)
* # => 203643.696848
* Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_second)
* # => 203.762181929
* Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :microsecond)
* # => 204123212
* Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :millisecond)
* # => 204298
* Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :nanosecond)
* # => 204602286036
* Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :second)
* # => 204
* *
* The underlying function, clock_gettime(), returns a number of nanoseconds. * The underlying function, clock_gettime(), returns a number of nanoseconds.
* Float object (IEEE 754 double) is not enough to represent * Float object (IEEE 754 double) is not enough to represent
* the return value for CLOCK_REALTIME. * the return value for +:CLOCK_REALTIME+.
* If the exact nanoseconds value is required, use +:nanosecond+ as the +unit+. * If the exact nanoseconds value is required, use +:nanosecond+ as the +unit+.
* *
* The origin (zero) of the returned value varies. * The origin (time zero) of the returned value is system-dependent,
* For example, system start up time, process start up time, the Epoch, etc. * and may be, for example, system start up time,
* process start up time, the Epoch, etc.
* *
* The origin in CLOCK_REALTIME is defined as the Epoch * The origin in +:CLOCK_REALTIME+ is defined as the Epoch:
* (1970-01-01 00:00:00 UTC). * <tt>1970-01-01 00:00:00 UTC</tt>;
* But some systems count leap seconds and others doesn't. * some systems count leap seconds and others don't,
* So the result can be interpreted differently across systems. * so the result may vary across systems.
* Time.now is recommended over CLOCK_REALTIME.
*/ */
static VALUE static VALUE
rb_clock_gettime(int argc, VALUE *argv, VALUE _) rb_clock_gettime(int argc, VALUE *argv, VALUE _)
@ -8414,45 +8451,39 @@ rb_clock_gettime(int argc, VALUE *argv, VALUE _)
/* /*
* call-seq: * call-seq:
* Process.clock_getres(clock_id [, unit]) -> number * Process.clock_getres(clock_id, unit = :float_second) -> number
* *
* Returns an estimate of the resolution of a +clock_id+ using the POSIX * Returns a clock resolution as determined by POSIX function
* <code>clock_getres()</code> function. * {clock_getres()}[https://man7.org/linux/man-pages/man3/clock_getres.3.html]:
* *
* Note the reported resolution is often inaccurate on most platforms due to * Process.clock_getres(:CLOCK_REALTIME) # => 1.0e-09
* underlying bugs for this function and therefore the reported resolution
* often differs from the actual resolution of the clock in practice.
* Inaccurate reported resolutions have been observed for various clocks including
* CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW when using Linux, macOS, BSD or AIX
* platforms, when using ARM processors, or when using virtualization.
* *
* +clock_id+ specifies a kind of clock. * See Process.clock_gettime for the values of +clock_id+ and +unit+.
* See the document of +Process.clock_gettime+ for details.
* +clock_id+ can be a symbol as for +Process.clock_gettime+.
* *
* If the given +clock_id+ is not supported, Errno::EINVAL is raised. * Examples:
* *
* +unit+ specifies the type of the return value. * Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond) # => 0.001
* +Process.clock_getres+ accepts +unit+ as +Process.clock_gettime+. * Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_millisecond) # => 1.0e-06
* The default value, +:float_second+, is also the same as * Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_second) # => 1.0e-09
* +Process.clock_gettime+. * Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :microsecond) # => 0
* Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :millisecond) # => 0
* Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :nanosecond) # => 1
* Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :second) # => 0
* *
* +Process.clock_getres+ also accepts +:hertz+ as +unit+. * In addition to the values for +unit+ supported in Process.clock_gettime,
* +:hertz+ means the reciprocal of +:float_second+. * this method supports +:hertz+, the integer number of clock ticks per second
* (which is the reciprocal of +:float_second+):
* *
* +:hertz+ can be used to obtain the exact value of * Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz) # => 100.0
* the clock ticks per second for the times() function and * Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :float_second) # => 0.01
* CLOCKS_PER_SEC for the clock() function.
*
* <code>Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz)</code>
* returns the clock ticks per second.
*
* <code>Process.clock_getres(:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz)</code>
* returns CLOCKS_PER_SEC.
*
* p Process.clock_getres(Process::CLOCK_MONOTONIC)
* #=> 1.0e-09
* *
* <b>Accuracy</b>:
* Note that the returned resolution may be inaccurate on some platforms
* due to underlying bugs.
* Inaccurate resolutions have been reported for various clocks including
* +:CLOCK_MONOTONIC+ and +:CLOCK_MONOTONIC_RAW+
* on Linux, macOS, BSD or AIX platforms, when using ARM processors,
* or when using virtualization.
*/ */
static VALUE static VALUE
rb_clock_getres(int argc, VALUE *argv, VALUE _) rb_clock_getres(int argc, VALUE *argv, VALUE _)