diff --git a/Modules/timemodule.c b/Modules/timemodule.c --- a/Modules/timemodule.c +++ b/Modules/timemodule.c @@ -811,13 +811,18 @@ } PyDoc_STRVAR(wallclock_doc, -"wallclock() -> float\n\ +"wallclock() -> floating point number\n\ \n\ -Return the current time in fractions of a second to the system's best\n\ -ability. Use this when the most accurate representation of wall-clock is\n\ +Return the current time in seconds with the highest available precision.\n\ +Use this when the most precise representation of wallclock time is\n\ required, i.e. when \"processor time\" is inappropriate. The reference point\n\ of the returned value is undefined so only the difference of consecutive\n\ -calls is valid."); +calls is valid.\n\ +\n\ +Depending on your operating system and hardware, wallclock() may be\n\ +affected by changes in the system time, including moving backwards.\n\ +If available on your system, monotonic() is guaranteed to monotonically\n\ +increase between consecutive calls and is recommended for timing instead."); #if (defined(MS_WINDOWS) && !defined(__BORLANDC__)) \ || (defined(HAVE_CLOCK_GETTIME) && defined(CLOCK_MONOTONIC)) \ @@ -869,10 +874,16 @@ } PyDoc_STRVAR(monotonic_doc, -"monotonic() -> float\n\ +"monotonic() -> floating point number\n\ \n\ -Monotonic clock. The reference point of the returned value is undefined so\n\ -only the difference of consecutive calls is valid."); +Return monotonically increasing time in seconds with high precision.\n\ +Use this when the most precise representation of wallclock time is\n\ +required, i.e. when \"processor time\" is inappropriate. The reference point\n\ +of the returned value is undefined so only the difference of consecutive\n\ +calls is valid.\n\ +\n\ +The value of monotonic() is guaranteed to never decrease over the process's\n\ +lifetime (e.g. as other clocks may when the system time is changed)."); #endif static void @@ -1061,7 +1072,13 @@ mktime() -- convert local time tuple to seconds since Epoch\n\ strftime() -- convert time tuple to string according to format specification\n\ strptime() -- parse string to time tuple according to format specification\n\ -tzset() -- change the local timezone"); +tzset() -- change the local timezone\n\ +wallclock() -- return time since unspecified epoch" +#ifdef HAVE_PYTIME_MONOTONIC +"\n\ +monotonic() -- return monotonically increasing time since unspecified epoch" +#endif +);