diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2023-09-03 14:36:51 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-09-03 15:36:51 -0400 |
commit | 40ab77eb3dd075536bcc3a6c225a7c245c247db8 (patch) | |
tree | d3ac849f6428dee678f5ac3751ce8ea73f71b557 /process.c | |
parent | 3602e253e79b796661168b458e22ba1694ec06e5 (diff) |
[DOC] Process doc (#8363)
Notes
Notes:
Merged-By: peterzhu2118 <peter@peterzhu.ca>
Diffstat (limited to 'process.c')
-rw-r--r-- | process.c | 329 |
1 files changed, 180 insertions, 149 deletions
@@ -8096,130 +8096,167 @@ ruby_real_ms_time(void) /* * call-seq: - * Process.clock_gettime(clock_id [, unit]) -> number - * - * Returns a time returned by POSIX clock_gettime() function. - * - * p Process.clock_gettime(Process::CLOCK_MONOTONIC) - * #=> 896053.968060096 - * - * +clock_id+ specifies a kind of clock. - * It is specified as a constant which begins with <code>Process::CLOCK_</code> - * such as Process::CLOCK_REALTIME and Process::CLOCK_MONOTONIC. - * - * The supported constants depends on OS and version. - * Ruby provides following types of +clock_id+ if available. - * - * [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_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 - * [CLOCK_THREAD_CPUTIME_ID] SUSv3 to 4, Linux 2.5.63, FreeBSD 7.1, OpenBSD 5.4, macOS 10.12 - * [CLOCK_VIRTUAL] FreeBSD 3.0, OpenBSD 2.1 - * [CLOCK_PROF] FreeBSD 3.0, OpenBSD 2.1 - * [CLOCK_REALTIME_FAST] FreeBSD 8.1 - * [CLOCK_REALTIME_PRECISE] FreeBSD 8.1 - * [CLOCK_REALTIME_COARSE] Linux 2.6.32 - * [CLOCK_REALTIME_ALARM] Linux 3.0 - * [CLOCK_MONOTONIC_FAST] FreeBSD 8.1 - * [CLOCK_MONOTONIC_PRECISE] FreeBSD 8.1 - * [CLOCK_MONOTONIC_COARSE] Linux 2.6.32 - * [CLOCK_MONOTONIC_RAW] Linux 2.6.28, macOS 10.12 - * [CLOCK_MONOTONIC_RAW_APPROX] macOS 10.12 - * [CLOCK_BOOTTIME] Linux 2.6.39 - * [CLOCK_BOOTTIME_ALARM] Linux 3.0 - * [CLOCK_UPTIME] FreeBSD 7.0, OpenBSD 5.5 - * [CLOCK_UPTIME_FAST] FreeBSD 8.1 - * [CLOCK_UPTIME_RAW] macOS 10.12 - * [CLOCK_UPTIME_RAW_APPROX] macOS 10.12 - * [CLOCK_UPTIME_PRECISE] FreeBSD 8.1 - * [CLOCK_SECOND] FreeBSD 8.1 - * [CLOCK_TAI] Linux 3.10 + * Process.clock_gettime(clock_id, unit = :float_second) -> number + * + * Returns a clock time as determined by POSIX function + * {clock_gettime()}[https://man7.org/linux/man-pages/man3/clock_gettime.3.html]: + * + * Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID) # => 198.650379677 + * + * Argument +clock_id+ should be a symbol or a constant that specifies + * the clock whose time is to be returned; + * see below. + * + * Optional argument +unit+ should be a symbol that specifies + * the unit to be used in the returned clock time; + * see below. + * + * <b>Argument +clock_id+</b> + * + * Argument +clock_id+ specifies the clock whose time is to be returned; + * it may be a constant such as <tt>Process::CLOCK_REALTIME</tt>, + * or a symbol shorthand such as +:CLOCK_REALTIME+. + * + * The supported clocks depend on the underlying operating system; + * this method supports the following clocks on the indicated platforms + * (raises Errno::EINVAL if called with an unsupported clock): + * + * - +:CLOCK_BOOTTIME+: Linux 2.6.39. + * - +:CLOCK_BOOTTIME_ALARM+: Linux 3.0. + * - +: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_COARSE+: Linux 2.6.32. + * - +:CLOCK_MONOTONIC_FAST+: FreeBSD 8.1. + * - +:CLOCK_MONOTONIC_PRECISE+: FreeBSD 8.1. + * - +:CLOCK_MONOTONIC_RAW+: Linux 2.6.28, macOS 10.12. + * - +:CLOCK_MONOTONIC_RAW_APPROX+: macOS 10.12. + * - +:CLOCK_PROCESS_CPUTIME_ID+: SUSv3 to 4, Linux 2.5.63, FreeBSD 9.3, OpenBSD 5.4, macOS 10.12. + * - +:CLOCK_PROF+: FreeBSD 3.0, OpenBSD 2.1. + * - +: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. + * Time.now is recommended over +:CLOCK_REALTIME:. + * - +:CLOCK_REALTIME_ALARM+: Linux 3.0. + * - +: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. * SUS contains POSIX and clock_gettime is defined in the POSIX part. - * SUS defines CLOCK_REALTIME mandatory but - * CLOCK_MONOTONIC, CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID are optional. - * - * Also, several symbols are accepted as +clock_id+. - * There are emulations for clock_gettime(). - * - * For example, Process::CLOCK_REALTIME is defined as - * +:GETTIMEOFDAY_BASED_CLOCK_REALTIME+ when clock_gettime() is not available. - * - * Emulations for +CLOCK_REALTIME+: - * [:GETTIMEOFDAY_BASED_CLOCK_REALTIME] - * Use gettimeofday() defined by SUS. - * (SUSv4 obsoleted it, though.) - * The resolution is 1 microsecond. - * [:TIME_BASED_CLOCK_REALTIME] - * Use time() defined by ISO C. - * The resolution is 1 second. - * - * Emulations for +CLOCK_MONOTONIC+: - * [:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC] - * Use mach_absolute_time(), available on Darwin. - * The resolution is CPU dependent. - * [:TIMES_BASED_CLOCK_MONOTONIC] - * Use the result value of times() defined by POSIX. - * 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)". - * For example, GNU/Linux returns a value based on jiffies and it is monotonic. - * However, 4.4BSD uses gettimeofday() and it is not monotonic. - * (FreeBSD uses clock_gettime(CLOCK_MONOTONIC) instead, though.) - * The resolution is the clock tick. - * "getconf CLK_TCK" command shows the clock ticks per second. - * (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 - * cannot represent over 497 days. - * - * Emulations for +CLOCK_PROCESS_CPUTIME_ID+: - * [:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID] - * Use getrusage() defined by SUS. - * getrusage() is used with RUSAGE_SELF to obtain the time only for - * the calling process (excluding the time for child processes). - * The result is addition of user time (ru_utime) and system time (ru_stime). - * The resolution is 1 microsecond. - * [:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID] - * Use times() defined by POSIX. - * 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. - * The resolution is the clock tick. - * "getconf CLK_TCK" command shows the clock ticks per second. - * (The clock ticks per second is defined by HZ macro in older systems.) - * If it is 100, the resolution is 10 millisecond. - * [:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID] - * Use clock() defined by ISO C. - * The resolution is 1/CLOCKS_PER_SEC. - * CLOCKS_PER_SEC is the C-level macro defined by time.h. - * SUS defines CLOCKS_PER_SEC is 1000000. - * Non-Unix systems may define it a different value, though. - * If CLOCKS_PER_SEC is 1000000 as SUS, the resolution is 1 microsecond. - * If CLOCKS_PER_SEC is 1000000 and clock_t is 32 bits integer type, it cannot represent over 72 minutes. - * - * If the given +clock_id+ is not supported, Errno::EINVAL is raised. - * - * +unit+ specifies a type of the return value. - * - * [:float_second] number of seconds as a float (default) - * [:float_millisecond] number of milliseconds as a float - * [:float_microsecond] number of microseconds as a float - * [:second] number of seconds as an integer - * [:millisecond] number of milliseconds as an integer - * [:microsecond] number of microseconds as an integer - * [:nanosecond] number of nanoseconds as an integer + * SUS defines +:CLOCK_REALTIME+ as mandatory but + * +:CLOCK_MONOTONIC+, +:CLOCK_PROCESS_CPUTIME_ID+, + * and +:CLOCK_THREAD_CPUTIME_ID+ are optional. + * + * Certain emulations are used when the given +clock_id+ + * is not supported directly: + * + * - Emulations for +:CLOCK_REALTIME+: + * + * - +:GETTIMEOFDAY_BASED_CLOCK_REALTIME+: + * Use gettimeofday() defined by SUS (deprecated in SUSv4). + * The resolution is 1 microsecond. + * - +:TIME_BASED_CLOCK_REALTIME+: + * Use time() defined by ISO C. + * The resolution is 1 second. + * + * - Emulations for +:CLOCK_MONOTONIC+: + * + * - +:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC+: + * Use mach_absolute_time(), available on Darwin. + * The resolution is CPU dependent. + * - +:TIMES_BASED_CLOCK_MONOTONIC+: + * Use the result value of times() defined by POSIX, thus: + * >>> + * 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. + * However, 4.4BSD uses gettimeofday() and it is not monotonic. + * (FreeBSD uses +:CLOCK_MONOTONIC+ instead, though.) + * + * The resolution is the clock tick. + * "getconf CLK_TCK" command shows the clock ticks per second. + * (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 cannot represent over 497 days. + * + * - Emulations for +:CLOCK_PROCESS_CPUTIME_ID+: + * + * - +:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID+: + * Use getrusage() defined by SUS. + * getrusage() is used with RUSAGE_SELF to obtain the time only for + * the calling process (excluding the time for child processes). + * The result is addition of user time (ru_utime) and system time (ru_stime). + * The resolution is 1 microsecond. + * - +:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID+: + * Use times() defined by POSIX. + * 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. + * The resolution is the clock tick. + * "getconf CLK_TCK" command shows the clock ticks per second. + * (The clock ticks per second is defined by HZ macro in older systems.) + * If it is 100, the resolution is 10 millisecond. + * - +:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID+: + * Use clock() defined by ISO C. + * The resolution is <tt>1/CLOCKS_PER_SEC</tt>. + * +CLOCKS_PER_SEC+ is the C-level macro defined by time.h. + * SUS defines +CLOCKS_PER_SEC+ as 1000000; + * other systems may define it differently. + * If +CLOCKS_PER_SEC+ is 1000000 (as in SUS), + * 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. + * + * <b>Argument +unit+</b> + * + * Optional argument +unit+ (default +:float_second+) + * specifies the unit for the returned value. + * + * - +:float_microsecond+: Number of microseconds as a float. + * - +:float_millisecond+: Number of milliseconds as a float. + * - +:float_second+: Number of seconds as a float. + * - +:microsecond+: Number of microseconds as an integer. + * - +:millisecond+: Number of milliseconds 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. * 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+. * - * The origin (zero) of the returned value varies. - * For example, system start up time, process start up time, the Epoch, etc. + * The origin (time zero) of the returned value is system-dependent, + * 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 - * (1970-01-01 00:00:00 UTC). - * But some systems count leap seconds and others doesn't. - * So the result can be interpreted differently across systems. - * Time.now is recommended over CLOCK_REALTIME. + * The origin in +:CLOCK_REALTIME+ is defined as the Epoch: + * <tt>1970-01-01 00:00:00 UTC</tt>; + * some systems count leap seconds and others don't, + * so the result may vary across systems. */ static VALUE rb_clock_gettime(int argc, VALUE *argv, VALUE _) @@ -8414,45 +8451,39 @@ rb_clock_gettime(int argc, VALUE *argv, VALUE _) /* * call-seq: - * Process.clock_getres(clock_id [, unit]) -> number - * - * Returns an estimate of the resolution of a +clock_id+ using the POSIX - * <code>clock_getres()</code> function. - * - * Note the reported resolution is often inaccurate on most platforms due to - * 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. + * Process.clock_getres(clock_id, unit = :float_second) -> number * - * +clock_id+ specifies a kind of clock. - * See the document of +Process.clock_gettime+ for details. - * +clock_id+ can be a symbol as for +Process.clock_gettime+. + * Returns a clock resolution as determined by POSIX function + * {clock_getres()}[https://man7.org/linux/man-pages/man3/clock_getres.3.html]: * - * If the given +clock_id+ is not supported, Errno::EINVAL is raised. + * Process.clock_getres(:CLOCK_REALTIME) # => 1.0e-09 * - * +unit+ specifies the type of the return value. - * +Process.clock_getres+ accepts +unit+ as +Process.clock_gettime+. - * The default value, +:float_second+, is also the same as - * +Process.clock_gettime+. + * See Process.clock_gettime for the values of +clock_id+ and +unit+. * - * +Process.clock_getres+ also accepts +:hertz+ as +unit+. - * +:hertz+ means the reciprocal of +:float_second+. - * - * +:hertz+ can be used to obtain the exact value of - * the clock ticks per second for the times() function and - * 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 + * Examples: * + * Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond) # => 0.001 + * Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_millisecond) # => 1.0e-06 + * Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_second) # => 1.0e-09 + * 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 + * + * In addition to the values for +unit+ supported in Process.clock_gettime, + * this method supports +:hertz+, the integer number of clock ticks per second + * (which is the reciprocal of +:float_second+): + * + * Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz) # => 100.0 + * Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :float_second) # => 0.01 + * + * <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 rb_clock_getres(int argc, VALUE *argv, VALUE _) |