Warn about Process#clock_getres being unreliable in documentation

* [Bug #16740]
* Remove the GETTIMEOFDAY_BASED_CLOCK_REALTIME example because the
  caveat applies to all clock ids, not just the Symbol clock ids.
This commit is contained in:
Benoit Daloze 2020-04-10 14:32:32 +02:00
Родитель 302da060af
Коммит c9b3aa84be
1 изменённых файлов: 12 добавлений и 11 удалений

Просмотреть файл

@ -7955,29 +7955,30 @@ rb_clock_gettime(int argc, VALUE *argv, VALUE _)
* call-seq:
* Process.clock_getres(clock_id [, unit]) -> number
*
* Returns the time resolution returned by POSIX clock_getres() function.
* Returns an estimate of the resolution of a +clock_id+ using the POSIX
* clock_getres() function.
*
* Note the reported resolution is often inaccurate on most platforms due to
* operating system bugs for this function and therefore the reported resolution
* often differs from the actual resolution of the clock in practice.
*
* +clock_id+ specifies a kind of clock.
* See the document of +Process.clock_gettime+ for details.
*
* +clock_id+ can be a symbol as +Process.clock_gettime+.
* However the result may not be accurate.
* For example, <code>Process.clock_getres(:GETTIMEOFDAY_BASED_CLOCK_REALTIME)</code>
* returns 1.0e-06 which means 1 microsecond, but actual resolution can be more coarse.
* +clock_id+ can be a symbol as for +Process.clock_gettime+.
*
* If the given +clock_id+ is not supported, Errno::EINVAL is raised.
*
* +unit+ specifies a type of the return value.
* +unit+ specifies the type of the return value.
* +Process.clock_getres+ accepts +unit+ as +Process.clock_gettime+.
* The default value, +:float_second+, is also same as
* The default value, +:float_second+, is also the same as
* +Process.clock_gettime+.
*
* +Process.clock_getres+ also accepts +:hertz+ as +unit+.
* +:hertz+ means a the reciprocal of +:float_second+.
* +:hertz+ means the reciprocal of +:float_second+.
*
* +:hertz+ can be used to obtain the exact value of
* the clock ticks per second for times() function and
* CLOCKS_PER_SEC for clock() function.
* 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.