Function: timeout-throttled-func

timeout-throttled-func is an autoloaded and byte-compiled function defined in timeout.el.gz.

Signature

(timeout-throttled-func FUNC &optional THROTTLE)

Documentation

Return a throttled version of function FUNC.

The throttled function runs no more frequently than once every THROTTLE seconds. THROTTLE defaults to 1 second. THROTTLE can be a number, a symbol (whose value is a number), or a function (that evaluates to a number). When passed a symbol or function, it is evaluated at runtime for dynamic duration.

When FUNC does not run because of the throttle, the result from the previous successful call is returned.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/timeout.el.gz
;;;###autoload
(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.  THROTTLE can be a number, a
symbol (whose value is a number), or a function (that evaluates to a
number).  When passed a symbol or function, it is evaluated at runtime
for dynamic duration.

When FUNC does not run because of the throttle, the result from the
previous successful call is returned."
  (let ((throttle-timer nil)
        (throttle-value (or throttle 1))
        (result))
    (if (commandp func)
        ;; INTERACTIVE version
        (lambda (&rest args)
          (:documentation
           (concat
            (documentation func)
            "\n\nThrottle calls to this function"))
          (interactive (advice-eval-interactive-spec
                        (cadr (interactive-form func))))
          (progn
            (unless (and throttle-timer (timerp throttle-timer))
              (setq result (apply func args))
              (setq throttle-timer
                    (run-with-timer
                     (timeout--eval-value throttle-value) nil
                     (lambda ()
                       (cancel-timer throttle-timer)
                       (setq throttle-timer nil)))))
            result))
      ;; NON-INTERACTIVE version
      (lambda (&rest args)
        (:documentation
         (concat
          (documentation func)
          "\n\nThrottle calls to this function"))
        (progn
          (unless (and throttle-timer (timerp throttle-timer))
            (setq result (apply func args))
            (setq throttle-timer
                  (run-with-timer
                   (timeout--eval-value throttle-value) nil
                   (lambda ()
                     (cancel-timer throttle-timer)
                     (setq throttle-timer nil)))))
          result)))))