[DOC] Process doc (#8363)

1 files changed, 180 insertions, 149 deletions

diff --git a/process.c b/process.c
index 0c7191f72c..77f38e1d98 100644
--- a/process.c
+++ b/process.c
@@ -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 _)