Variable: org-element-use-cache

org-element-use-cache is a variable defined in org-element.el.gz.

Value

t

Documentation

Non-nil when Org parser should cache its results.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-element.el.gz
;;; Cache
;;
;; Implement a caching mechanism for `org-element-at-point', `org-element-context', and for
;; fast mapping across Org elements in `org-element-cache-map', which see.
;;
;; When cache is enabled, the elements returned by `org-element-at-point' and
;; `org-element-context' are returned by reference.  Altering these elements will
;; also alter their cache representation.  The same is true for
;; elements passed to mapping function in `org-element-cache-map'.
;;
;; Public functions are: `org-element-cache-reset', `org-element-cache-refresh', and
;; `org-element-cache-map'.
;;
;; Cache can be controlled using `org-element-use-cache' and `org-element-cache-persistent'.
;;  `org-element-cache-sync-idle-time', `org-element-cache-sync-duration' and
;; `org-element-cache-sync-break' can be tweaked to control caching behavior.
;;
;; Internally, parsed elements are stored in an AVL tree,
;; `org-element--cache'.  This tree is updated lazily: whenever
;; a change happens to the buffer, a synchronization request is
;; registered in `org-element--cache-sync-requests' (see
;; `org-element--cache-submit-request').  During idle time, requests
;; are processed by `org-element--cache-sync'.  Synchronization also
;; happens when an element is required from the cache.  In this case,
;; the process stops as soon as the needed element is up-to-date.
;;
;; A synchronization request can only apply on a synchronized part of
;; the cache.  Therefore, the cache is updated at least to the
;; location where the new request applies.  Thus, requests are ordered
;; from left to right and all elements starting before the first
;; request are correct.  This property is used by functions like
;; `org-element--cache-find' to retrieve elements in the part of the
;; cache that can be trusted.
;;
;; A request applies to every element, starting from its original
;; location (or key, see below).  When a request is processed, it
;; moves forward and may collide the next one.  In this case, both
;; requests are merged into a new one that starts from that element.
;; As a consequence, the whole synchronization complexity does not
;; depend on the number of pending requests, but on the number of
;; elements the very first request will be applied on.
;;
;; Elements cannot be accessed through their beginning position, which
;; may or may not be up-to-date.  Instead, each element in the tree is
;; associated to a key, obtained with `org-element--cache-key'.  This
;; mechanism is robust enough to preserve total order among elements
;; even when the tree is only partially synchronized.
;;
;; The cache code debugging is fairly complex because cache request
;; state is often hard to reproduce.  An extensive diagnostics
;; functionality is built into the cache code to assist hunting bugs.
;; See `org-element--cache-self-verify', `org-element--cache-self-verify-frequency',
;; `org-element--cache-diagnostics', `org-element--cache-diagnostics-level',
;; `org-element--cache-diagnostics-ring-size', `org-element--cache-map-statistics',
;; `org-element--cache-map-statistics-threshold'.

;;;###autoload
(defvar org-element-use-cache t
  "Non-nil when Org parser should cache its results.")