Function: sit-for

sit-for is a byte-compiled function defined in subr.el.gz.

Signature

(sit-for SECONDS &optional NODISP)

Documentation

Redisplay, then wait for SECONDS seconds. Stop when input is available.

SECONDS may be a floating-point value.
(On operating systems that do not support waiting for fractions of a
second, floating-point values are rounded down to the nearest integer.)

If optional arg NODISP is t, don't redisplay, just wait for input. Redisplay does not happen if input is available before it starts.

Value is t if waited the full time with no input arriving, and nil otherwise.

An obsolete, but still supported form is
(sit-for SECONDS &optional MILLISECONDS NODISP)
where the optional arg MILLISECONDS specifies an additional wait period, in milliseconds; this was useful when Emacs was built without floating point support.

Probably introduced at or before Emacs version 1.4.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun sit-for (seconds &optional nodisp obsolete)
  "Redisplay, then wait for SECONDS seconds.  Stop when input is available.
SECONDS may be a floating-point value.
\(On operating systems that do not support waiting for fractions of a
second, floating-point values are rounded down to the nearest integer.)

If optional arg NODISP is t, don't redisplay, just wait for input.
Redisplay does not happen if input is available before it starts.

Value is t if waited the full time with no input arriving, and nil otherwise.

An obsolete, but still supported form is
\(sit-for SECONDS &optional MILLISECONDS NODISP)
where the optional arg MILLISECONDS specifies an additional wait period,
in milliseconds; this was useful when Emacs was built without
floating point support."
  (declare (advertised-calling-convention (seconds &optional nodisp) "22.1"))
  ;; This used to be implemented in C until the following discussion:
  ;; https://lists.gnu.org/r/emacs-devel/2006-07/msg00401.html
  ;; Then it was moved here using an implementation based on an idle timer,
  ;; which was then replaced by the use of read-event.
  (if (numberp nodisp)
      (setq seconds (+ seconds (* 1e-3 nodisp))
            nodisp obsolete)
    (if obsolete (setq nodisp obsolete)))
  (cond
   (noninteractive
    (sleep-for seconds)
    t)
   ((input-pending-p t)
    nil)
   ((or (<= seconds 0)
        ;; We are going to call read-event below, which will record
        ;; the next key as part of the macro, even if that key
        ;; invokes kmacro-end-macro, so if we are recording a macro,
        ;; the macro will recursively call itself.  In addition, when
        ;; that key is removed from unread-command-events, it will be
        ;; recorded the second time, so the macro will have each key
        ;; doubled.  This used to happen if a macro was defined with
        ;; Flyspell mode active (because Flyspell calls sit-for in its
        ;; post-command-hook, see bug #21329.)  To avoid all that, we
        ;; simply disable the wait when we are recording a macro.
        defining-kbd-macro)
    (or nodisp (redisplay)))
   (t
    (or nodisp (redisplay))
    ;; FIXME: we should not read-event here at all, because it's much too
    ;; difficult to reliably "undo" a read-event by pushing it onto
    ;; unread-command-events.
    ;; For bug#14782, we need read-event to do the keyboard-coding-system
    ;; decoding (hence non-nil as second arg under POSIX ttys).
    ;; For bug#15614, we need read-event not to inherit-input-method.
    ;; So we temporarily suspend input-method-function.
    (let ((read (let ((input-method-function nil))
                  (read-event nil t seconds))))
      (or (null read)
	  (progn
            ;; https://lists.gnu.org/r/emacs-devel/2006-10/msg00394.html
            ;; We want `read' appear in the next command's this-command-event
            ;; but not in the current one.
            ;; By pushing (cons t read), we indicate that `read' has not
            ;; yet been recorded in this-command-keys, so it will be recorded
            ;; next time it's read.
            ;; And indeed the `seconds' argument to read-event correctly
            ;; prevented recording this event in the current command's
            ;; this-command-keys.
	    (push (cons t read) unread-command-events)
	    nil))))))