This is the official manual for the latest Org-mode release.

Table of Contents

Next: , Previous: noweb-sep, Up: Specific header arguments


14.8.2.18 :cache

The :cache header argument is for caching results of evaluating code blocks. Caching results can avoid re-evaluating code blocks that have not changed since the previous run. To benefit from the cache and avoid redundant evaluations, the source block must have a result already present in the buffer, and neither the header arguments (including the value of :var references) nor the text of the block itself has changed since the result was last computed. This feature greatly helps avoid long-running calculations. For some edge cases, however, the cached results may not be reliable.

The caching feature is best for when ‘src’ blocks are pure functions—functions that return the same value for the same input arguments (see var), and that do not have side effects, and do not rely on external variables other than the input arguments. Functions that depend on a timer, file system objects, and random number generators are clearly unsuitable for caching.

A note of warning: when :cache is used for a :session, caching may cause unexpected results.

When the caching mechanism tests for any source code changes, it will not expand “noweb” style references (see Noweb reference syntax). For reasons why, see http://thread.gmane.org/gmane.emacs.orgmode/79046.

The :cache header argument can have one of two values: yes or no.

In this example, both functions are cached. But caller runs only if the result from random has changed since the last run.

      #+NAME: random
      #+BEGIN_SRC R :cache yes
      runif(1)
      #+END_SRC
     
      #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
      0.4659510825295
     
      #+NAME: caller
      #+BEGIN_SRC emacs-lisp :var x=random :cache yes
      x
      #+END_SRC
     
      #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
      0.254227238707244