From c8b1fbb36aa0dee050dd7eea5fed9760c410a541 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 18 Apr 2022 13:08:27 -0700 Subject: [PATCH 6/6] Use (TICKS . HZ) for current-time etc. * src/timefns.c (CURRENT_TIME_LIST): Change default to false. All documentation changed. --- doc/lispintro/emacs-lisp-intro.texi | 6 +++--- doc/lispref/files.texi | 14 +++++++------- doc/lispref/intro.texi | 2 +- doc/lispref/os.texi | 15 +++++++-------- etc/NEWS | 8 ++++++++ src/timefns.c | 26 ++++++++++++-------------- 6 files changed, 38 insertions(+), 33 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 466d7f0e60..afaed10cdf 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -15343,9 +15343,9 @@ Files List 100 @end group @group -(20615 27034 579989 697000) -(17905 55681 0 0) -(20615 26327 734791 805000) +(1351051674579989697 . 1000000000) +(1173477761000000000 . 1000000000) +(1351050967734791805 . 1000000000) 13188 "-rw-r--r--" @end group diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index d8b55b114a..4394f64a32 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1423,9 +1423,9 @@ File Attributes @group (file-attributes "files.texi" 'string) @result{} (nil 1 "lh" "users" - (20614 64019 50040 152000) - (20000 23 0 0) - (20614 64555 902289 872000) + (1351023123050040152 . 1000000000) + (1310720023000000000 . 1000000000) + (1351023659902289872 . 1000000000) 122295 "-rw-rw-rw-" t 6473924464520138 1014478468) @@ -1449,13 +1449,13 @@ File Attributes @item "users" is in the group with name @samp{users}. -@item (20614 64019 50040 152000) +@item (1351023123050040152 . 1000000000) was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. -@item (20000 23 0 0) -was last modified on July 15, 2001, at 08:53:43 UTC. +@item (1310720023000000000 . 1000000000) +was last modified on July 15, 2001, at 08:53:43.000000000 UTC. -@item (20614 64555 902289 872000) +@item (1351023659902289872 . 1000000000) last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC. @item 122295 diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 5afd2f4ecf..d1a3fef7a4 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -503,7 +503,7 @@ Version Info @example @group emacs-build-time - @result{} (20614 63694 515336 438000) + @result{} (1650228902637038831 . 1000000000) @end group @end example @end defvar diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 30ece4aeff..ae551b0f71 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1359,9 +1359,6 @@ Time of Day @tex $high \times 2^{16} + low + micro \times 10^{-6} + pico \times 10^{-12}$. @end tex -In some cases, functions may default to returning two- or -three-element lists, with omitted @var{micro} and @var{pico} -components defaulting to zero. On all current machines @var{pico} is a multiple of 1000, but this may change as higher-resolution clocks become available. @end itemize @@ -1415,11 +1412,13 @@ Time of Day @defun current-time This function returns the current time as a Lisp timestamp. -Although the timestamp takes the form @code{(@var{high} @var{low} -@var{micro} @var{pico})} in the current Emacs release, this is -planned to change in a future Emacs version. You can use the -@code{time-convert} function to convert a timestamp to some other -form. @xref{Time Conversion}. +The timestamp has the form @code{(@var{ticks} . @var{hz})} where +@var{ticks} counts clock ticks and @var{hz} is the clock ticks per second. + +In Emacs 28 and earlier, the returned timestamp had the list form +@code{(@var{high} @var{low} @var{usec} @var{psec})}. You can use +@code{(time-convert nil 'list)} to return the current time in this +older form. @xref{Time Conversion}. @end defun @defun float-time &optional time diff --git a/etc/NEWS b/etc/NEWS index d9635cce46..c0b44effc6 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -202,6 +202,14 @@ speakers of the Tamil language. To get back the previous behavior, use the new 'tamil-itrans-digits' and 'tamil-inscript-digits' input methods instead. ++++ +** current-time and related functions now yield (TICKS . HZ) timestamps. +Previously they yielded timestamps of the forms (HI LO US PS), (HI LO +US) or (HI LO), which were less regular and less efficient and which +lacked information about clock resolution. This long-planned change +was documented in Emacs 27. To convert a timestamp X to the old +4-element list form, you can use (time-convert X 'list). + * Changes in Emacs 29.1 diff --git a/src/timefns.c b/src/timefns.c index a6cc9c9f05..286d5eb2b8 100644 --- a/src/timefns.c +++ b/src/timefns.c @@ -69,12 +69,11 @@ Copyright (C) 1985-1987, 1989, 1993-2022 Free Software Foundation, Inc. # define FASTER_TIMEFNS 1 #endif -/* Although current-time etc. generate list-format timestamps - (HI LO US PS), the plan is to change these functions to generate - frequency-based timestamps (TICKS . HZ) in a future release. - To try this now, compile with -DCURRENT_TIME_LIST=0. */ +/* current-time etc. generate (TICKS . HZ) timestamps. + To change that to the old 4-element list format (HI LO US PS), + compile with -DCURRENT_TIME_LIST=1. */ #ifndef CURRENT_TIME_LIST -enum { CURRENT_TIME_LIST = true }; +enum { CURRENT_TIME_LIST = false }; #endif /* Clock resolution of struct timespec. */ @@ -1861,15 +1860,14 @@ DEFUN ("time-convert", Ftime_convert, Stime_convert, 1, 2, 0, DEFUN ("current-time", Fcurrent_time, Scurrent_time, 0, 0, 0, doc: /* Return the current time, as the number of seconds since 1970-01-01 00:00:00. -The time is returned as a list of integers (HIGH LOW USEC PSEC). -HIGH has the most significant bits of the seconds, while LOW has the -least significant 16 bits. USEC and PSEC are the microsecond and -picosecond counts. - -In a future Emacs version, the format of the returned timestamp is -planned to change. Use `time-convert' if you need a particular -timestamp form; for example, (time-convert nil \\='integer) returns -the current time in seconds. */) +The time is returned as a pair of integers (TICKS . HZ), where TICKS +counts clock ticks and HZ is the clock ticks per second. + +In Emacs 28 and earlier, the returned timestamp had the form (HIGH LOW +USEC PSEC), where HIGH is the most significant bits of the seconds, +LOW the least significant 16 bits, and USEC and PSEC are the +microsecond and picosecond counts. Use \(time-convert nil \\='list) +if you need this older timestamp form. */) (void) { return make_lisp_realtime (current_timespec ()); -- 2.35.1