1 ;;; jit-lock.el --- just-in-time fontification.
3 ;; Copyright (C) 1998 Free Software Foundation, Inc.
5 ;; Author: Gerd Moellmann <gerd@gnu.org>
6 ;; Keywords: faces files
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to the
23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
24 ;; Boston, MA 02111-1307, USA.
28 ;; Just-in-time fontification, triggered by C redisplay code.
36 (defmacro with-buffer-unmodified (&rest body)
37 "Eval BODY, preserving the current buffer's modified state."
38 (let ((modified (make-symbol "modified")))
39 `(let ((,modified (buffer-modified-p)))
43 (restore-buffer-modified-p nil))))))
45 (defmacro with-buffer-prepared-for-jit-lock (&rest body)
46 "Execute BODY in current buffer, overriding several variables.
47 Preserves the `buffer-modified-p' state of the current buffer."
48 `(with-buffer-unmodified
49 (let ((buffer-undo-list t)
51 (inhibit-point-motion-hooks t)
52 (inhibit-modification-hooks t)
62 (defcustom jit-lock-chunk-size 500
63 "*Jit-lock chunks of this many characters, or smaller."
68 (defcustom jit-lock-stealth-time 3
69 "*Time in seconds to wait before beginning stealth fontification.
70 Stealth fontification occurs if there is no input within this time.
71 If nil, means stealth fontification is never performed.
73 The value of this variable is used when JIT Lock mode is turned on."
74 :type '(choice (const :tag "never" nil)
75 (number :tag "seconds"))
79 (defcustom jit-lock-stealth-nice 0.125
80 "*Time in seconds to pause between chunks of stealth fontification.
81 Each iteration of stealth fontification is separated by this amount of time,
82 thus reducing the demand that stealth fontification makes on the system.
83 If nil, means stealth fontification is never paused.
84 To reduce machine load during stealth fontification, at the cost of stealth
85 taking longer to fontify, you could increase the value of this variable.
86 See also `jit-lock-stealth-load'."
87 :type '(choice (const :tag "never" nil)
88 (number :tag "seconds"))
92 (defcustom jit-lock-stealth-load
93 (if (condition-case nil (load-average) (error)) 200)
94 "*Load in percentage above which stealth fontification is suspended.
95 Stealth fontification pauses when the system short-term load average (as
96 returned by the function `load-average' if supported) goes above this level,
97 thus reducing the demand that stealth fontification makes on the system.
98 If nil, means stealth fontification is never suspended.
99 To reduce machine load during stealth fontification, at the cost of stealth
100 taking longer to fontify, you could reduce the value of this variable.
101 See also `jit-lock-stealth-nice'."
102 :type (if (condition-case nil (load-average) (error))
103 '(choice (const :tag "never" nil)
104 (integer :tag "load"))
105 '(const :format "%t: unsupported\n" nil))
109 (defcustom jit-lock-stealth-verbose nil
110 "*If non-nil, means stealth fontification should show status messages."
115 (defcustom jit-lock-defer-contextually 'syntax-driven
116 "*If non-nil, means deferred fontification should be syntactically true.
117 If nil, means deferred fontification occurs only on those lines modified. This
118 means where modification on a line causes syntactic change on subsequent lines,
119 those subsequent lines are not refontified to reflect their new context.
120 If t, means deferred fontification occurs on those lines modified and all
121 subsequent lines. This means those subsequent lines are refontified to reflect
122 their new syntactic context, either immediately or when scrolling into them.
123 If any other value, e.g., `syntax-driven', means deferred syntactically true
124 fontification occurs only if syntactic fontification is performed using the
125 buffer mode's syntax table, i.e., only if `font-lock-keywords-only' is nil.
127 The value of this variable is used when JIT Lock mode is turned on."
128 :type '(choice (const :tag "never" nil)
129 (const :tag "always" t)
130 (other :tag "syntax-driven" syntax-driven))
135 ;;; Variables that are not customizable.
137 (defvar jit-lock-mode nil
138 "Non-nil means Just-in-time Lock mode is active.")
139 (make-variable-buffer-local 'jit-lock-mode)
141 (defvar jit-lock-functions nil
142 "Functions to do the actual fontification.
143 They are called with two arguments: the START and END of the region to fontify.")
145 (defvar jit-lock-first-unfontify-pos nil
146 "Consider text after this position as unfontified.
147 If nil, contextual fontification is disabled.")
148 (make-variable-buffer-local 'jit-lock-first-unfontify-pos)
151 (defvar jit-lock-stealth-timer nil
152 "Timer for stealth fontification in Just-in-time Lock mode.")
154 (defvar jit-lock-saved-fontify-buffer-function nil
155 "Value of `font-lock-fontify-buffer-function' before jit-lock's activation.")
161 (defun jit-lock-mode (arg)
162 "Toggle Just-in-time Lock mode.
163 Turn Just-in-time Lock mode on if and only if ARG is non-nil.
164 Enable it automatically by customizing group `font-lock'.
166 When Just-in-time Lock mode is enabled, fontification is different in the
169 - Demand-driven buffer fontification triggered by Emacs C code.
170 This means initial fontification of the whole buffer does not occur.
171 Instead, fontification occurs when necessary, such as when scrolling
172 through the buffer would otherwise reveal unfontified areas. This is
173 useful if buffer fontification is too slow for large buffers.
175 - Stealthy buffer fontification if `jit-lock-stealth-time' is non-nil.
176 This means remaining unfontified areas of buffers are fontified if Emacs has
177 been idle for `jit-lock-stealth-time' seconds, while Emacs remains idle.
178 This is useful if any buffer has any deferred fontification.
180 - Deferred context fontification if `jit-lock-defer-contextually' is
181 non-nil. This means fontification updates the buffer corresponding to
182 true syntactic context, after `jit-lock-stealth-time' seconds of Emacs
183 idle time, while Emacs remains idle. Otherwise, fontification occurs
184 on modified lines only, and subsequent lines can remain fontified
185 corresponding to previous syntactic contexts. This is useful where
186 strings or comments span lines.
188 Stealth fontification only occurs while the system remains unloaded.
189 If the system load rises above `jit-lock-stealth-load' percent, stealth
190 fontification is suspended. Stealth fontification intensity is controlled via
191 the variable `jit-lock-stealth-nice'."
192 (setq jit-lock-mode arg)
193 (cond (;; Turn Just-in-time Lock mode on.
196 ;; Mark the buffer for refontification
197 ;; (in case spurious `fontified' text-props were left around).
198 (jit-lock-fontify-buffer)
200 ;; Setting `font-lock-fontified' makes font-lock believe the
201 ;; buffer is already fontified, so that it won't highlight
202 ;; the whole buffer or bail out on a large buffer.
203 (set (make-local-variable 'font-lock-fontified) t)
205 ;; Setup JIT font-lock-fontify-buffer.
206 (unless jit-lock-saved-fontify-buffer-function
207 (set (make-local-variable 'jit-lock-saved-fontify-buffer-function)
208 font-lock-fontify-buffer-function)
209 (set (make-local-variable 'font-lock-fontify-buffer-function)
210 'jit-lock-fontify-buffer))
212 ;; Install an idle timer for stealth fontification.
213 (when (and jit-lock-stealth-time
214 (null jit-lock-stealth-timer))
215 (setq jit-lock-stealth-timer
216 (run-with-idle-timer jit-lock-stealth-time
217 jit-lock-stealth-time
218 'jit-lock-stealth-fontify)))
220 ;; Initialize deferred contextual fontification if requested.
221 (when (or (eq jit-lock-defer-contextually 'always)
222 (and (not (eq jit-lock-defer-contextually 'never))
223 (boundp 'font-lock-keywords-only)
224 (null font-lock-keywords-only)))
225 (setq jit-lock-first-unfontify-pos (point-max)))
227 ;; Setup our after-change-function
228 ;; and remove font-lock's (if any).
229 (remove-hook 'after-change-functions 'font-lock-after-change-function t)
230 (add-hook 'after-change-functions 'jit-lock-after-change nil t)
232 ;; Install the fontification hook.
233 (add-hook 'fontification-functions 'jit-lock-function))
235 ;; Turn Just-in-time Lock mode off.
237 ;; Cancel our idle timer.
238 (when jit-lock-stealth-timer
239 (cancel-timer jit-lock-stealth-timer)
240 (setq jit-lock-stealth-timer nil))
242 ;; Restore non-JIT font-lock-fontify-buffer.
243 (when jit-lock-saved-fontify-buffer-function
244 (set (make-local-variable 'font-lock-fontify-buffer-function)
245 jit-lock-saved-fontify-buffer-function)
246 (setq jit-lock-saved-fontify-buffer-function nil))
248 ;; Remove hooks (and restore font-lock's if necessary).
249 (remove-hook 'after-change-functions 'jit-lock-after-change t)
251 (add-hook 'after-change-functions
252 'font-lock-after-change-function nil t))
253 (remove-hook 'fontification-functions 'jit-lock-function))))
256 ;; This function is used to prevent font-lock-fontify-buffer from
257 ;; fontifying eagerly the whole buffer. This is important for
258 ;; things like CWarn mode which adds/removes a few keywords and
259 ;; does a refontify (which takes ages on large files).
260 (defun jit-lock-fontify-buffer ()
261 (with-buffer-prepared-for-jit-lock
264 (add-text-properties (point-min) (point-max) '(fontified nil)))))
267 ;;; On demand fontification.
269 (defun jit-lock-function (start)
270 "Fontify current buffer starting at position START.
271 This function is added to `fontification-functions' when `jit-lock-mode'
274 (jit-lock-function-1 start)))
277 (defun jit-lock-function-1 (start)
278 "Fontify current buffer starting at position START."
279 (with-buffer-prepared-for-jit-lock
283 (let ((end (min (point-max) (+ start jit-lock-chunk-size)))
284 (font-lock-beginning-of-syntax-function nil)
287 ;; Fontify chunks beginning at START. The end of a
288 ;; chunk is either `end', or the start of a region
289 ;; before `end' that has already been fontified.
291 ;; Determine the end of this chunk.
292 (setq next (or (text-property-any start end 'fontified t)
295 ;; Decide which range of text should be fontified.
296 ;; The problem is that START and NEXT may be in the
297 ;; middle of something matched by a font-lock regexp.
298 ;; Until someone has a better idea, let's start
299 ;; at the start of the line containing START and
300 ;; stop at the start of the line following NEXT.
302 (setq next (line-beginning-position 2))
304 (setq start (line-beginning-position))
306 ;; Fontify the chunk, and mark it as fontified.
307 ;; We mark it first, to make sure that we don't indefinitely
308 ;; re-execute this fontification if an error occurs.
309 (add-text-properties start next '(fontified t))
310 (if jit-lock-functions
311 (run-hook-with-args 'jit-lock-functions start next)
312 (font-lock-fontify-region start next))
314 ;; Find the start of the next chunk, if any.
315 (setq start (text-property-any next end 'fontified nil)))))))))
318 ;;; Stealth fontification.
320 (defsubst jit-lock-stealth-chunk-start (around)
321 "Return the start of the next chunk to fontify around position AROUND..
322 Value is nil if there is nothing more to fontify."
323 (if (zerop (buffer-size))
327 (let* ((next (text-property-any around (point-max) 'fontified nil))
328 (prev (previous-single-property-change around 'fontified))
329 (prop (get-text-property (max (point-min) (1- around))
333 ;; There is no property change between AROUND
334 ;; and the start of the buffer. If PROP is
335 ;; non-nil, everything in front of AROUND is
336 ;; fontified, otherwise nothing is fontified.
340 (- around (/ jit-lock-chunk-size 2)))))
342 ;; PREV is the start of a region of fontified
343 ;; text containing AROUND. Start fontifying a
344 ;; chunk size before the end of the unfontified
345 ;; region in front of that.
346 (max (or (previous-single-property-change prev 'fontified)
348 (- prev jit-lock-chunk-size)))
350 ;; PREV is the start of a region of unfontified
351 ;; text containing AROUND. Start at PREV or
352 ;; chunk size in front of AROUND, whichever is
354 (max prev (- around jit-lock-chunk-size)))))
355 (result (cond ((null start) next)
357 ((< (- around start) (- next around)) start)
362 (defun jit-lock-stealth-fontify ()
363 "Fontify buffers stealthily.
364 This functions is called after Emacs has been idle for
365 `jit-lock-stealth-time' seconds."
366 (unless (or executing-kbd-macro
367 (window-minibuffer-p (selected-window)))
368 (let ((buffers (buffer-list))
369 minibuffer-auto-raise
371 (while (and buffers (not (input-pending-p)))
372 (let ((buffer (car buffers)))
373 (setq buffers (cdr buffers))
375 (with-current-buffer buffer
377 ;; This is funny. Calling sit-for with 3rd arg non-nil
378 ;; so that it doesn't redisplay, internally calls
379 ;; wait_reading_process_input also with a parameter
380 ;; saying "don't redisplay." Since this function here
381 ;; is called periodically, this effectively leads to
382 ;; process output not being redisplayed at all because
383 ;; redisplay_internal is never called. (That didn't
384 ;; work in the old redisplay either.) So, we learn that
385 ;; we mustn't call sit-for that way here. But then, we
386 ;; have to be cautious not to call sit-for in a widened
387 ;; buffer, since this could display hidden parts of that
388 ;; buffer. This explains the seemingly weird use of
389 ;; save-restriction/widen here.
391 (with-temp-message (if jit-lock-stealth-verbose
392 (concat "JIT stealth lock "
395 ;; Perform deferred unfontification, if any.
396 (when jit-lock-first-unfontify-pos
399 (when (and (>= jit-lock-first-unfontify-pos (point-min))
400 (< jit-lock-first-unfontify-pos (point-max)))
401 (with-buffer-prepared-for-jit-lock
402 (put-text-property jit-lock-first-unfontify-pos
403 (point-max) 'fontified nil))
404 (setq jit-lock-first-unfontify-pos (point-max)))))
406 ;; In the following code, the `sit-for' calls cause a
407 ;; redisplay, so it's required that the
408 ;; buffer-modified flag of a buffer that is displayed
409 ;; has the right value---otherwise the mode line of
410 ;; an unmodified buffer would show a `*'.
412 (nice (or jit-lock-stealth-nice 0))
414 (while (and (setq start
415 (jit-lock-stealth-chunk-start point))
418 ;; Wait a little if load is too high.
419 (when (and jit-lock-stealth-load
420 (> (car (load-average)) jit-lock-stealth-load))
421 (sit-for (or jit-lock-stealth-time 30)))
423 ;; Unless there's input pending now, fontify.
424 (unless (input-pending-p)
425 (jit-lock-function-1 start))))))))))))
429 ;;; Deferred fontification.
431 (defun jit-lock-after-change (start end old-len)
432 "Mark the rest of the buffer as not fontified after a change.
433 Installed on `after-change-functions'.
434 START and END are the start and end of the changed text. OLD-LEN
435 is the pre-change length.
436 This function ensures that lines following the change will be refontified
437 in case the syntax of those lines has changed. Refontification
438 will take place when text is fontified stealthily."
441 (with-buffer-prepared-for-jit-lock
442 ;; It's important that the `fontified' property be set from the
443 ;; beginning of the line, else font-lock will properly change the
444 ;; text's face, but the display will have been done already and will
445 ;; be inconsistent with the buffer's content.
447 (setq start (line-beginning-position))
448 ;; Make sure we change at least one char (in case of deletions).
449 (setq end (min (max end (1+ start)) (point-max)))
450 ;; Request refontification.
451 (put-text-property start end 'fontified nil))
452 ;; Mark the change for deferred contextual refontification.
453 (when jit-lock-first-unfontify-pos
454 (setq jit-lock-first-unfontify-pos
455 (min jit-lock-first-unfontify-pos start))))))
459 ;; jit-lock.el ends here