From: Paul Eggert Date: Thu, 28 Apr 2022 19:50:39 +0000 (-0700) Subject: Change current-time back to list form X-Git-Tag: emacs-29.0.90~1931^2~231 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=083d2708f9ec7f09712488a99fc9eedd3d594ff6;p=emacs.git Change current-time back to list form Change current-time and related functions back to using the traditional list form. Also, add a new boolean variable current-time-list that lets people try out (TICKS . HZ) form, with the goal of smoothing the transition. * src/timefns.c (CURRENT_TIME_LIST): Change default back to true. (current-time-list): New boolean Lisp variable, which defaults to CURRENT_TIME_LIST. All uses of CURRENT_TIME_LIST changed to use current_time_list, and all documentation changed. --- diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index afaed10cdfe..049c8a65a8f 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -15343,9 +15343,12 @@ nil 100 @end group @group -(1351051674579989697 . 1000000000) -(1173477761000000000 . 1000000000) -(1351050967734791805 . 1000000000) +(20615 27034 579989 697000) +(17905 55681 0 0) +(20615 26327 734791 805000)@footnote{If @code{current-time-list} is +@code{nil} the three timestamps are @code{(1351051674579989697 +. 1000000000)}, @code{(1173477761000000000 . 1000000000)}, and +@code{(1351050967734791805 . 1000000000)}, respectively.} 13188 "-rw-r--r--" @end group diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 4394f64a320..75905658e64 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1423,9 +1423,9 @@ For example, here are the file attributes for @file{files.texi}: @group (file-attributes "files.texi" 'string) @result{} (nil 1 "lh" "users" - (1351023123050040152 . 1000000000) - (1310720023000000000 . 1000000000) - (1351023659902289872 . 1000000000) + (20614 64019 50040 152000) + (20000 23 0 0) + (20614 64555 902289 872000) 122295 "-rw-rw-rw-" t 6473924464520138 1014478468) @@ -1449,14 +1449,20 @@ is owned by the user with name @samp{lh}. @item "users" is in the group with name @samp{users}. -@item (1351023123050040152 . 1000000000) -was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. +@item (20614 64019 50040 152000) +was last accessed on October 23, 2012, at 20:12:03.050040152 UTC@. +(This timestamp is @code{(1351023123050040152 . 1000000000)} +if @code{current-time-list} is @code{nil}.) -@item (1310720023000000000 . 1000000000) -was last modified on July 15, 2001, at 08:53:43.000000000 UTC. +@item (20000 23 0 0) +was last modified on July 15, 2001, at 08:53:43.000000000 UTC@. +(This timestamp is @code{(1310720023000000000 . 1000000000)} +if @code{current-time-list} is @code{nil}.) -@item (1351023659902289872 . 1000000000) -last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC. +@item (20614 64555 902289 872000) +last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC@. +(This timestamp is @code{(1351023659902289872 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item 122295 is 122295 bytes long. (It may not contain 122295 characters, though, diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index d1a3fef7a4b..975215d6976 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -503,9 +503,11 @@ if the information is not available. @example @group emacs-build-time - @result{} (1650228902637038831 . 1000000000) + @result{} (25194 55894 8547 617000) @end group @end example +(This timestamp is @code{(1651169878008547617 . 1000000000)} +if @code{current-time-list} was @code{nil} when Emacs was built.) @end defvar @defvar emacs-version diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 89ddf164a17..20b6c1cec63 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1359,6 +1359,10 @@ This represents the number of seconds using the formula: @tex $high \times 2^{16} + low + micro \times 10^{-6} + pico \times 10^{-12}$. @end tex +If @code{current-time-list} is @code{t}, +some 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 @@ -1410,15 +1414,28 @@ The operating system limits the range of time and zone values. @end example @end defun +@defvar current-time-list +This boolean variable is a transition aid. If @code{t}, +@code{current-time} and related functions return timestamps in list +form, typically @code{(@var{high} @var{low} @var{micro} @var{pico})}; +otherwise, they use @code{(@var{ticks} . @var{hz})} form. Currently +this variable defaults to @code{t}, for behavior compatible with +previous Emacs versions. Developers are encourage to test +timestamp-related code with this variable set to @code{nil}, as it +will default to @code{nil} in a future Emacs version, and will be +removed in some version after that. +@end defvar + @defun current-time This function returns the current time as a Lisp timestamp. -The timestamp has the form @code{(@var{ticks} . @var{hz})} where +If @code{current-time-list} is @code{nil}, +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}. +Otherwise, the timestamp has the list form +@code{(@var{high} @var{low} @var{usec} @var{psec})}. +You can use @code{(time-convert nil t)} or @code{(time-convert nil 'list)} +to obtain a particular form regardless of the value of +@code{current-time-list}. @xref{Time Conversion}. @end defun @defun float-time &optional time diff --git a/etc/NEWS b/etc/NEWS index 70087f2629e..9f93c4067f7 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -203,12 +203,15 @@ 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). +** New variable current-time-list governing default timestamp form. +Functions like current-time now yield (TICKS . HZ) timestamps if this +new variable is nil. The variable defaults to t, which means these +functions default to timestamps of the forms (HI LO US PS), (HI LO US) +or (HI LO), which are less regular and less efficient. This is part +of a long-planned change first documented in Emacs 27. Developers are +encourage to test timestamp-related code with this variable set to +nil, as it will default to nil in a future Emacs version and will be +removed some time after that. * Changes in Emacs 29.1 diff --git a/src/timefns.c b/src/timefns.c index 651e0760e83..bca9a566e08 100644 --- a/src/timefns.c +++ b/src/timefns.c @@ -69,11 +69,11 @@ enum { TM_YEAR_BASE = 1900 }; # define FASTER_TIMEFNS 1 #endif -/* 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. */ +/* current-time-list defaults to t, typically generating (HI LO US PS) + timestamps. To change the default to nil, generating (TICKS . HZ) + timestamps, compile with -DCURRENT_TIME_LIST=0. */ #ifndef CURRENT_TIME_LIST -enum { CURRENT_TIME_LIST = false }; +enum { CURRENT_TIME_LIST = true }; #endif #if FIXNUM_OVERFLOW_P (1000000000) @@ -568,7 +568,7 @@ lisp_time_seconds (struct lisp_time t) Lisp_Object make_lisp_time (struct timespec t) { - if (CURRENT_TIME_LIST) + if (current_time_list) { time_t s = t.tv_sec; int ns = t.tv_nsec; @@ -1171,13 +1171,13 @@ time_arith (Lisp_Object a, Lisp_Object b, bool subtract) } /* Return an integer if the timestamp resolution is 1, - otherwise the (TICKS . HZ) form if !CURRENT_TIME_LIST or if + otherwise the (TICKS . HZ) form if !current_time_list or if either input used (TICKS . HZ) form or the result can't be expressed exactly in (HI LO US PS) form, otherwise the (HI LO US PS) form for backward compatibility. */ return (EQ (hz, make_fixnum (1)) ? ticks - : (!CURRENT_TIME_LIST + : (!current_time_list || aform == TIMEFORM_TICKS_HZ || bform == TIMEFORM_TICKS_HZ || !trillion_factor (hz)) @@ -1716,7 +1716,7 @@ usage: (encode-time TIME &rest OBSOLESCENT-ARGUMENTS) */) time_error (mktime_errno); if (EQ (hz, make_fixnum (1))) - return (CURRENT_TIME_LIST + return (current_time_list ? list2 (hi_time (value), lo_time (value)) : INT_TO_INTEGER (value)); else @@ -1747,7 +1747,7 @@ bits, and USEC and PSEC are the microsecond and picosecond counts. */) struct lisp_time t; enum timeform input_form = decode_lisp_time (time, false, &t, 0); if (NILP (form)) - form = CURRENT_TIME_LIST ? Qlist : Qt; + form = current_time_list ? Qlist : Qt; if (EQ (form, Qlist)) return ticks_hz_list4 (t.ticks, t.hz); if (EQ (form, Qinteger)) @@ -1762,14 +1762,15 @@ bits, and USEC and PSEC are the microsecond and picosecond counts. */) 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 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. */) +If the variable `current-time-list' is nil, the time is returned as a +pair of integers (TICKS . HZ), where TICKS counts clock ticks and HZ +is the clock ticks per second. Otherwise, the time is returned as a +list of integers (HIGH LOW USEC PSEC) where HIGH has the most +significant bits of the seconds, LOW has the least significant 16 +bits, and USEC and PSEC are the microsecond and picosecond counts. + +You can use `time-convert' to get a particular timestamp form +regardless of the value of `current-time-list'. */) (void) { return make_lisp_time (current_timespec ()); @@ -2025,6 +2026,19 @@ syms_of_timefns (void) DEFSYM (Qencode_time, "encode-time"); + DEFVAR_BOOL ("current-time-list", current_time_list, + doc: /* Whether `current-time' should return list or (TICKS . HZ) form. + +This boolean variable is a transition aid. If t, `current-time' and +related functions return timestamps in list form, typically +\(HIGH LOW USEC PSEC); otherwise, they use (TICKS . HZ) form. +Currently this variable defaults to t, for behavior compatible with +previous Emacs versions. Developers are encourage to test +timestamp-related code with this variable set to nil, as it will +default to nil in a future Emacs version, and will be removed in some +version after that. */); + current_time_list = CURRENT_TIME_LIST; + defsubr (&Scurrent_time); #ifdef CLOCKS_PER_SEC defsubr (&Scurrent_cpu_time);