From c9b3aa84be6577a9df8a0a1ee12715b114a10d9b Mon Sep 17 00:00:00 2001 From: Benoit Daloze Date: Fri, 10 Apr 2020 14:32:32 +0200 Subject: 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. --- process.c | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) (limited to 'process.c') diff --git a/process.c b/process.c index 3d3fef12ff..02af42bcbe 100644 --- a/process.c +++ b/process.c @@ -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, Process.clock_getres(:GETTIMEOFDAY_BASED_CLOCK_REALTIME) - * 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. * * Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz) * returns the clock ticks per second. -- cgit v1.2.3