master 1110d7326f: Add new function current-cpu-time

[Lars Ingebrigtsen]

branch: master
commit 1110d7326f8b2b94f473244c5d2111324d06cd29
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Add new function current-cpu-time
    
    * doc/lispref/os.texi (Time of Day): Document it.
    * src/timefns.c (Fcurrent_cpu_time): New function (bug#44674).
---
 doc/lispref/os.texi |  7 +++++++
 etc/NEWS            |  5 +++++
 src/timefns.c       | 15 +++++++++++++++
 3 files changed, 27 insertions(+)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 9e87b3840e..89ddf164a1 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1434,6 +1434,13 @@ as @samp{0.1} but is slightly greater than 1/10.
 @code{time-to-seconds} is an alias for this function.
 @end defun
 
+@defun current-cpu-time
+Return the current @acronym{CPU} time along with its resolution.  The
+return value is a pair @code{(CPU-TICKS . TICKS-PER-SEC)}.  The
+@var{CPU-TICKS} counter can wrap around, so values cannot be
+meaningfully compared if too much time has passed between them.
+@end defun
+
 @node Time Zone Rules
 @section Time Zone Rules
 @cindex time zone rules
diff --git a/etc/NEWS b/etc/NEWS
index 2ecad81b11..526afe27a5 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1513,6 +1513,11 @@ functions.
 
 * Lisp Changes in Emacs 29.1
 
+---
+** New function 'current-cpu-time'.
+It gives access to the CPU time used by the Emacs process, for
+example for benchmarking purposes.
+
 ---
 ** New function 'string-edit'.
 This is meant to be used when the user has to edit a (potentially)
diff --git a/src/timefns.c b/src/timefns.c
index e7a2cd368e..651e0760e8 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -1775,6 +1775,18 @@ if you need this older timestamp form.  */)
   return make_lisp_time (current_timespec ());
 }
 
+#ifdef CLOCKS_PER_SEC
+DEFUN ("current-cpu-time", Fcurrent_cpu_time, Scurrent_cpu_time, 0, 0, 0,
+       doc: /* Return the current CPU time along with its resolution.
+The return value is a pair (CPU-TICKS . TICKS-PER-SEC).
+The CPU-TICKS counter can wrap around, so values cannot be meaningfully
+compared if too much time has passed between them.  */)
+  (void)
+{
+  return Fcons (make_int (clock ()), make_int (CLOCKS_PER_SEC));
+}
+#endif
+
 DEFUN ("current-time-string", Fcurrent_time_string, Scurrent_time_string,
        0, 2, 0,
        doc: /* Return the current local time, as a human-readable string.
@@ -2014,6 +2026,9 @@ syms_of_timefns (void)
   DEFSYM (Qencode_time, "encode-time");
 
   defsubr (&Scurrent_time);
+#ifdef CLOCKS_PER_SEC
+  defsubr (&Scurrent_cpu_time);
+#endif
   defsubr (&Stime_convert);
   defsubr (&Stime_add);
   defsubr (&Stime_subtract);