From: Aaron Ecay <aaronecay@gmail.com>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-orgmode@gnu.org
Subject: Re: problems with export and :cache
Date: Wed, 04 Nov 2015 12:01:04 +0000 [thread overview]
Message-ID: <877flyvurj.fsf@gmail.com> (raw)
In-Reply-To: <87io5ll45q.fsf@nicolasgoaziou.fr>
[-- Attachment #1: Type: text/plain, Size: 2743 bytes --]
Hi Nicolas,
2015ko azaroak 1an, Nicolas Goaziou-ek idatzi zuen:
>
> Hello,
>
> Aaron Ecay <aaronecay@gmail.com> writes:
>
>> If this means “can it ever work?” then I think the answer is “yes it
>> can”. But I think the current implementation is broken and likely to
>> remain so for the foreseeable future. The issues are:
>>
>> 1. :cache only works for code which is a pure function of its header args
>> 2. When combined with :session, the environment that the code is evaluated
>> in is not created anew each time it is run. This makes it much easier
>> to leak references to (e.g.) variables defined in other blocks
>> 3. The proper notion of purity is not easily defined when the code does
>> things like modifying the emacs environment, touching the filesystem,
>> or accessing the language’s RNG.
>> 4. We (org devs) don’t actually understand how the semantics of cache
>> interacts with other babel features. See:
>> <http://mid.gmane.org/86fvqqc8jb.fsf@somewhere.org>.
>>
>> 1-3 are likely to be extremely confusing for users, especially less
>> technically sophisticated ones (what’s a “pure function” anyway)? The
>> inability to give a clear introductory explanation of the feature in
>> combination with 4 indicating we don’t actually understand it ourselves
>> makes me feel like we should not be advertising, let alone recommending,
>> it.
>>
>> The only other literate programming environment that I know of that
>> implements such a feature is knitr (for R). They address these issues
>> by providing (optional) free-variable analysis to construct a dependency
>> graph between code blocks. There is also some handling of RNG seed
>> values. The documentation <http://yihui.name/knitr/demo/cache/> is much
>> more comprehensive, including a prominent statement about the dangers of
>> side effect-ful code and a nuanced discussion of several issues,
>> including the RNG.
>
> Thank you for the explanations.
>
> Assuming the user knows what s?he is doing (so I'm not bothered by
> issues 2 and 3), :cache is still a somewhat useful feature. I don't mind
> advertising it. Though, I agree we could include big fat warnings about
> it in the manual.
See the attached patch. I’ve tried to put all my experience and best
practices in there; comments are welcome of course.
>
> Also, :cache might be a bit misleading as it implies more than what this
> feature offer, i.e., a dumb "don't update results if contents didn't
> change". I cannot think of a better name, tho.
There are backwards compatibility implications to renaming the header,
of course. (And I can’t think of a better name either).
Thanks,
--
Aaron Ecay
[-- Attachment #2: 0001-babel-update-the-manual-wrt-cache-header-arg.patch --]
[-- Type: text/x-diff, Size: 2947 bytes --]
From bb0f43948384448225323abcfe7a662d110d1389 Mon Sep 17 00:00:00 2001
From: Aaron Ecay <aaronecay@gmail.com>
Date: Wed, 4 Nov 2015 11:57:49 +0000
Subject: [PATCH] babel: update the manual wrt :cache header arg
* doc/org.texi (cache): Update manual section.
---
doc/org.texi | 36 +++++++++++++++++++++++++++++++-----
1 file changed, 31 insertions(+), 5 deletions(-)
diff --git a/doc/org.texi b/doc/org.texi
index ba402bf..48ae017 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -16166,11 +16166,37 @@ used.
The @code{:cache} header argument controls the use of in-buffer caching of
the results of evaluating code blocks. It can be used to avoid re-evaluating
-unchanged code blocks. Note that the @code{:cache} header argument will not
-attempt to cache results when the @code{:session} header argument is used,
-because the results of the code block execution may be stored in the session
-outside of the Org mode buffer. The @code{:cache} header argument can have
-one of two values: @code{yes} or @code{no}.
+unchanged code blocks. When the cache is active, a source block is not
+re-evaluated if a result for it is present in the buffer and neither the
+header arguments (including the value of @code{:var} references) nor the text
+of the block itself has changed since the result was computed. The feature
+helps avoid re-running long calculations. However, there are edge cases and
+you should not rely on the cache to behave reliably in all circumstances.
+
+The caching feature works best when a babel block is a pure function of its
+arguments (see @ref{var}). That is, the function always returns the same
+results when given the same arguments, and does not touch external resources
+(like the filesystem or the language’s RNG) in any way.
+
+The documentation of the knitr reproducible research package for the R
+language has some good discussion of issues that may arise when using the
+cache in such a context. See @uref{http://yihui.name/knitr/demo/cache/},
+especially the sections “Even more stuff for cache?” and “Reproducibility
+with RNG”. (Obviously, you will have to abstract away from the knitr
+implementation details which the documentation also discusses.)
+
+Note that the @code{:cache} header argument will attempt to cache results
+when the @code{:session} header argument is used, even though the results of
+the code block execution stored in the session may lead to unexpected
+results.
+
+Noweb references (see @ref{Noweb reference syntax}) are currently not
+expanded when calculating whether the text of the code block has changed.
+Perhaps in principle they ought to be, but this could introduce unexpected
+complexity. See @uref{http://thread.gmane.org/gmane.emacs.orgmode/79046}.
+
+The @code{:cache} header argument can have one of two values: @code{yes} or
+@code{no}.
@itemize @bullet
@item @code{no}
--
2.6.2
next prev parent reply other threads:[~2015-11-04 12:01 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-10-28 21:37 problems with export and :cache Andreas Leha
2015-10-28 21:45 ` Andreas Leha
2015-10-29 13:34 ` Aaron Ecay
2015-10-29 14:22 ` Nicolas Goaziou
2015-10-29 15:14 ` Aaron Ecay
2015-10-29 16:42 ` Nicolas Goaziou
2015-10-29 17:05 ` Aaron Ecay
2015-10-29 17:16 ` Nicolas Goaziou
2015-10-29 19:11 ` Aaron Ecay
2015-10-30 23:40 ` Andreas Leha
2015-11-07 16:37 ` Achim Gratz
2015-11-07 20:33 ` Aaron Ecay
2015-11-07 22:43 ` Achim Gratz
2015-10-29 14:58 ` Andreas Leha
2015-10-29 15:17 ` Aaron Ecay
2015-10-29 16:51 ` Nicolas Goaziou
2015-10-29 19:05 ` Aaron Ecay
2015-10-29 20:32 ` Thomas S. Dye
2015-10-29 23:01 ` Andreas Leha
2015-11-01 22:56 ` Nicolas Goaziou
2015-11-04 12:01 ` Aaron Ecay [this message]
2015-11-04 22:41 ` Nicolas Goaziou
2015-11-05 14:51 ` Aaron Ecay
2015-11-05 14:55 ` Nicolas Goaziou
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=877flyvurj.fsf@gmail.com \
--to=aaronecay@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).