Add new library 'timeout'

* lisp/emacs-lisp/timeout.el: Add the file.
* etc/NEWS: Mention the library.

See https://mail.gnu.org/archive/html/emacs-devel/2025-07/msg00520.html.

2 files changed, 249 insertions, 0 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 02a556a557d..630d03a1fa0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2729,6 +2729,12 @@ enabled for files named "go.work".
 ** New package 'lua-mode'.
 The 'lua-mode' package from Non-GNU ELPA is now included in Emacs.
 
+** New library 'timeout'.
+This library that provides higher order functions to throttle or
+debounce Elisp functions.  This is useful for corraling over-eager code
+that is slow and blocks Emacs or does not provide customization options
+to limit how often it runs.
+
 
 * Incompatible Lisp Changes in Emacs 31.1
 
diff --git a/lisp/emacs-lisp/timeout.el b/lisp/emacs-lisp/timeout.el
new file mode 100644
index 00000000000..c949e7a912e
--- /dev/null
+++ b/lisp/emacs-lisp/timeout.el
@@ -0,0 +1,243 @@
+;;; timeout.el --- Throttle or debounce Elisp functions  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2023-2025  Free Software Foundation, Inc.
+
+;; Author: Karthik Chikmagalur <karthikchikmagalur@gmail.com>
+;; Maintainer: Karthik Chikmagalur <karthikchikmagalur@gmail.com>
+;; Keywords: convenience, extensions
+;; Version: 2.0
+;; Package-Requires: ((emacs "24.4"))
+;; URL: https://github.com/karthink/timeout
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; timeout is a small Elisp library that provides higher order functions to
+;; throttle or debounce Elisp functions.  This is useful for corralling
+;; over-eager code that:
+;; (i) is slow and blocks Emacs, and
+;; (ii) does not provide customization options to limit how often it runs,
+;;
+;; To throttle a function FUNC to run no more than once every 2 seconds, run
+;; (timeout-throttle 'func 2.0)
+;;
+;; To debounce a function FUNC to run after a delay of 0.3 seconds, run
+;; (timeout-debounce 'func 0.3)
+;;
+;; To create a new throttled or debounced version of FUNC instead, run
+;;
+;; (timeout-throttled-func 'func 2.0)
+;; (timeout-debounced-func 'func 0.3)
+;;
+;; You can bind this via `defalias':
+;;
+;; (defalias 'throttled-func (timeout-throttled-func 'func 2.0))
+;;
+;; The interactive spec and documentation of FUNC is carried over to the new
+;; function.
+
+;;; Code:
+
+(require 'nadvice)
+
+(defun timeout--throttle-advice (&optional timeout)
+  "Return a function that throttles its argument function.
+
+TIMEOUT defaults to 1 second.
+
+When FUNC does not run because of the throttle, the result from the
+previous successful call is returned.
+
+This is intended for use as function advice."
+  (let ((throttle-timer)
+        (timeout (or timeout 1.0))
+        (result))
+    (lambda (orig-fn &rest args)
+      "Throttle calls to this function."
+      (prog1 result
+        (unless (and throttle-timer (timerp throttle-timer))
+          (setq result (apply orig-fn args))
+          (setq throttle-timer
+                (run-with-timer
+                 timeout nil
+                 (lambda ()
+                   (cancel-timer throttle-timer)
+                   (setq throttle-timer nil)))))))))
+
+(defun timeout--debounce-advice (&optional delay default)
+  "Return a function that debounces its argument function.
+
+DELAY defaults to 0.50 seconds.  The function returns immediately with
+value DEFAULT when called the first time.  On future invocations, the
+result from the previous call is returned.
+
+This is intended for use as function advice."
+  (let ((debounce-timer nil)
+        (delay (or delay 0.50)))
+    (lambda (orig-fn &rest args)
+      "Debounce calls to this function."
+      (prog1 default
+        (if (timerp debounce-timer)
+            (timer-set-idle-time debounce-timer delay)
+          (setq debounce-timer
+                (run-with-idle-timer
+                 delay nil
+                 (lambda (buf)
+                   (cancel-timer debounce-timer)
+                   (setq debounce-timer nil)
+                   (setq default
+                         (if (buffer-live-p buf)
+                             (with-current-buffer buf
+                               (apply orig-fn args))
+                           (apply orig-fn args))))
+                 (current-buffer))))))))
+
+(defun timeout-debounce (func &optional delay default)
+  "Debounce FUNC by making it run DELAY seconds after it is called.
+
+This advises FUNC, when called (interactively or from code), to
+run after DELAY seconds.   If FUNC is called again within this time,
+the timer is reset.
+
+DELAY defaults to 0.5 seconds.  Using a delay of 0 removes any
+debounce advice.
+
+The function returns immediately with value DEFAULT when called the
+first time.  On future invocations, the result from the previous call is
+returned."
+  (if (and delay (= delay 0))
+      (advice-remove func 'debounce)
+    (advice-add func :around (timeout--debounce-advice delay default)
+                '((name . debounce)
+                  (depth . -99)))))
+
+(defun timeout-throttle (func &optional throttle)
+  "Make FUNC run no more frequently than once every THROTTLE seconds.
+
+THROTTLE defaults to 1 second.  Using a throttle of 0 removes any
+throttle advice.
+
+When FUNC does not run because of the throttle, the result from the
+previous successful call is returned."
+  (if (and throttle (= throttle 0))
+      (advice-remove func 'throttle)
+    (advice-add func :around (timeout--throttle-advice throttle)
+                '((name . throttle)
+                  (depth . -98)))))
+
+(defun timeout-throttled-func (func &optional throttle)
+  "Return a throttled version of function FUNC.
+
+The throttled function runs no more frequently than once every THROTTLE
+seconds.  THROTTLE defaults to 1 second.
+
+When FUNC does not run because of the throttle, the result from the
+previous successful call is returned."
+  (let ((throttle-timer nil)
+        (throttle (or throttle 1))
+        (result))
+    (if (commandp func)
+        ;; INTERACTIVE version
+        (lambda (&rest args)
+          (:documentation
+           (concat
+            (documentation func)
+            (format "\n\nThrottle calls to this function by %f seconds" throttle)))
+          (interactive (advice-eval-interactive-spec
+                        (cadr (interactive-form func))))
+          (prog1 result
+            (unless (and throttle-timer (timerp throttle-timer))
+              (setq result (apply func args))
+              (setq throttle-timer
+                    (run-with-timer
+                     throttle nil
+                     (lambda ()
+                       (cancel-timer throttle-timer)
+                       (setq throttle-timer nil)))))))
+      ;; NON-INTERACTIVE version
+      (lambda (&rest args)
+        (:documentation
+         (concat
+          (documentation func)
+          (format "\n\nThrottle calls to this function by %f seconds" throttle)))
+        (prog1 result
+          (unless (and throttle-timer (timerp throttle-timer))
+            (setq result (apply func args))
+            (setq throttle-timer
+                  (run-with-timer
+                   throttle nil
+                   (lambda ()
+                     (cancel-timer throttle-timer)
+                     (setq throttle-timer nil))))))))))
+
+(defun timeout-debounced-func (func &optional delay default)
+  "Return a debounced version of function FUNC.
+
+The debounced function runs DELAY seconds after it is called.  DELAY
+defaults to 0.5 seconds.
+
+The function returns immediately with value DEFAULT when called the
+first time.  On future invocations, the result from the previous call is
+returned."
+  (let ((debounce-timer nil)
+        (delay (or delay 0.50)))
+    (if (commandp func)
+        ;; INTERACTIVE version
+        (lambda (&rest args)
+          (:documentation
+           (concat
+            (documentation func)
+            (format "\n\nDebounce calls to this function by %f seconds" delay)))
+          (interactive (advice-eval-interactive-spec
+                        (cadr (interactive-form func))))
+          (prog1 default
+            (if (timerp debounce-timer)
+                (timer-set-idle-time debounce-timer delay)
+              (setq debounce-timer
+                    (run-with-idle-timer
+                     delay nil
+                     (lambda (buf)
+                       (cancel-timer debounce-timer)
+                       (setq debounce-timer nil)
+                       (setq default
+                             (if (buffer-live-p buf)
+                                 (with-current-buffer buf
+                                   (apply func args))
+                               (apply func args))))
+                     (current-buffer))))))
+      ;; NON-INTERACTIVE version
+      (lambda (&rest args)
+        (:documentation
+         (concat
+          (documentation func)
+          (format "\n\nDebounce calls to this function by %f seconds" delay)))
+        (prog1 default
+          (if (timerp debounce-timer)
+              (timer-set-idle-time debounce-timer delay)
+            (setq debounce-timer
+                  (run-with-idle-timer
+                   delay nil
+                   (lambda (buf)
+                     (cancel-timer debounce-timer)
+                     (setq debounce-timer nil)
+                     (setq default
+                           (if (buffer-live-p buf)
+                               (with-current-buffer buf
+                                 (apply func args))
+                             (apply func args))))
+                   (current-buffer)))))))))
+
+(provide 'timeout)
+;;; timeout.el ends here