Function: jit-lock-mode

jit-lock-mode is a byte-compiled function defined in jit-lock.el.gz.

Signature

(jit-lock-mode ARG)

Documentation

Toggle Just-in-time Lock mode.

Turn Just-in-time Lock mode on if and only if ARG is non-nil. Enable it automatically by customizing group font-lock.

When Just-in-time Lock mode is enabled, fontification is different in the following ways:

- Demand-driven buffer fontification triggered by Emacs C code.
  This means initial fontification of the whole buffer does not occur.
  Instead, fontification occurs when necessary, such as when scrolling
  through the buffer would otherwise reveal unfontified areas. This is
  useful if buffer fontification is too slow for large buffers.

- Stealthy buffer fontification if jit-lock-stealth-time is non-nil.
  This means remaining unfontified areas of buffers are fontified if Emacs has
  been idle for jit-lock-stealth-time seconds, while Emacs remains idle.
  This is useful if any buffer has any deferred fontification.

- Deferred context fontification if jit-lock-contextually is
  non-nil. This means fontification updates the buffer corresponding to
  true syntactic context, after jit-lock-context-time seconds of Emacs
  idle time, while Emacs remains idle. Otherwise, fontification occurs
  on modified lines only, and subsequent lines can remain fontified
  corresponding to previous syntactic contexts. This is useful where
  strings or comments span lines.

Stealth fontification only occurs while the system remains unloaded. If the system load rises above jit-lock-stealth-load percent, stealth fontification is suspended. Stealth fontification intensity is controlled via the variable jit-lock-stealth-nice.

jit-lock-mode(var)/jit-lock-mode(fun) is not a regular minor mode, and it doesn't follow the regular conventions to switch the functionality on or off. Instead, an ARG of nil will switch it off, and non-nil will switch it on.

If you need to debug code run from jit-lock, see jit-lock-debug-mode(var)/jit-lock-debug-mode(fun).

Probably introduced at or before Emacs version 21.1.

Source Code

;; Defined in /usr/src/emacs/lisp/jit-lock.el.gz
(defun jit-lock-mode (arg)
  "Toggle Just-in-time Lock mode.
Turn Just-in-time Lock mode on if and only if ARG is non-nil.
Enable it automatically by customizing group `font-lock'.

When Just-in-time Lock mode is enabled, fontification is different in the
following ways:

- Demand-driven buffer fontification triggered by Emacs C code.
  This means initial fontification of the whole buffer does not occur.
  Instead, fontification occurs when necessary, such as when scrolling
  through the buffer would otherwise reveal unfontified areas.  This is
  useful if buffer fontification is too slow for large buffers.

- Stealthy buffer fontification if `jit-lock-stealth-time' is non-nil.
  This means remaining unfontified areas of buffers are fontified if Emacs has
  been idle for `jit-lock-stealth-time' seconds, while Emacs remains idle.
  This is useful if any buffer has any deferred fontification.

- Deferred context fontification if `jit-lock-contextually' is
  non-nil.  This means fontification updates the buffer corresponding to
  true syntactic context, after `jit-lock-context-time' seconds of Emacs
  idle time, while Emacs remains idle.  Otherwise, fontification occurs
  on modified lines only, and subsequent lines can remain fontified
  corresponding to previous syntactic contexts.  This is useful where
  strings or comments span lines.

Stealth fontification only occurs while the system remains unloaded.
If the system load rises above `jit-lock-stealth-load' percent, stealth
fontification is suspended.  Stealth fontification intensity is controlled via
the variable `jit-lock-stealth-nice'.

`jit-lock-mode' is not a regular minor mode, and it doesn't
follow the regular conventions to switch the functionality on or
off.  Instead, an ARG of nil will switch it off, and non-nil will
switch it on.

If you need to debug code run from jit-lock, see `jit-lock-debug-mode'."
  (setq jit-lock-mode arg)
  (cond
   ((and (buffer-base-buffer)
         jit-lock-mode)
    ;; We're in an indirect buffer, and we're turning the mode on.
    ;; This doesn't work because jit-lock relies on the `fontified'
    ;; text-property which is shared with the base buffer.
    (setq jit-lock-mode nil)
    (message "Not enabling jit-lock: it does not work in indirect buffer"))

   (jit-lock-mode ;; Turn Just-in-time Lock mode on.

    ;; Mark the buffer for refontification.
    (jit-lock-refontify)

    ;; Install an idle timer for stealth fontification.
    (when (and jit-lock-stealth-time (null jit-lock-stealth-timer))
      (setq jit-lock-stealth-timer
            (run-with-idle-timer jit-lock-stealth-time t
                                 #'jit-lock-stealth-fontify)))

    ;; Create, but do not activate, the idle timer for repeated
    ;; stealth fontification.
    (when (and jit-lock-stealth-time (null jit-lock-stealth-repeat-timer))
      (setq jit-lock-stealth-repeat-timer (timer-create))
      (timer-set-function jit-lock-stealth-repeat-timer
                          #'jit-lock-stealth-fontify '(t)))

    ;; Init deferred fontification timer.
    (when (and jit-lock-defer-time (null jit-lock-defer-timer))
      (setq jit-lock-defer-timer
            (run-with-idle-timer jit-lock-defer-time t
                                 #'jit-lock-deferred-fontify)))

    ;; Initialize contextual fontification if requested.
    (when (eq jit-lock-contextually t)
      (unless jit-lock-context-timer
        (setq jit-lock-context-timer
              (run-with-idle-timer jit-lock-context-time t #'jit-lock-context--update)))
      (add-hook 'post-command-hook #'jit-lock--antiblink-post-command nil t)
      (setq jit-lock-context-unfontify-pos
            (or jit-lock-context-unfontify-pos (point-max))))

    ;; Setup our hooks.
    (add-hook 'after-change-functions #'jit-lock-after-change nil t)
    (add-hook 'fontification-functions #'jit-lock-function nil t))

   ;; Turn Just-in-time Lock mode off.
   (t
    ;; Cancel our idle timers.
    (when (and (or jit-lock-stealth-timer jit-lock-defer-timer
                   jit-lock-context-timer)
               ;; Only if there's no other buffer using them.
               (not (catch 'found
                      (dolist (buf (buffer-list))
                        (with-current-buffer buf
                          (when jit-lock-mode (throw 'found t)))))))
      (when jit-lock-stealth-timer
        (cancel-timer jit-lock-stealth-timer)
        (setq jit-lock-stealth-timer nil))
      (when jit-lock-context-timer
        (cancel-timer jit-lock-context-timer)
        (setq jit-lock-context-timer nil))
      (when jit-lock-defer-timer
        (cancel-timer jit-lock-defer-timer)
        (setq jit-lock-defer-timer nil)))

    ;; Remove hooks.
    (remove-hook 'post-command-hook #'jit-lock--antiblink-post-command t)
    (remove-hook 'after-change-functions #'jit-lock-after-change t)
    (remove-hook 'fontification-functions #'jit-lock-function))))