From mboxrd@z Thu Jan 1 00:00:00 1970 From: Aaron Ecay Subject: Re: problems with export and :cache Date: Wed, 04 Nov 2015 12:01:04 +0000 Message-ID: <877flyvurj.fsf@gmail.com> References: <87vb9pyf0l.fsf@gmail.com> <87oafhoby4.fsf@nicolasgoaziou.fr> <877fm5xzpm.fsf@gmail.com> <87io5ll45q.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:45168) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ztwke-0005Zm-Ig for emacs-orgmode@gnu.org; Wed, 04 Nov 2015 07:01:21 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZtwkY-0004ly-7I for emacs-orgmode@gnu.org; Wed, 04 Nov 2015 07:01:16 -0500 Received: from mail-wm0-x233.google.com ([2a00:1450:400c:c09::233]:34624) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZtwkX-0004lk-VD for emacs-orgmode@gnu.org; Wed, 04 Nov 2015 07:01:10 -0500 Received: by wmff134 with SMTP id f134so108402451wmf.1 for ; Wed, 04 Nov 2015 04:01:09 -0800 (PST) In-Reply-To: <87io5ll45q.fsf@nicolasgoaziou.fr> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Nicolas Goaziou Cc: emacs-orgmode@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi Nicolas, 2015ko azaroak 1an, Nicolas Goaziou-ek idatzi zuen: >=20 > Hello, >=20 > Aaron Ecay writes: >=20 >> If this means =E2=80=9Ccan it ever work?=E2=80=9D then I think the answe= r is =E2=80=9Cyes it >> can=E2=80=9D. But I think the current implementation is broken and like= ly to >> remain so for the foreseeable future. The issues are: >>=20 >> 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 evaluat= ed >> 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=E2=80=99s RNG. >> 4. We (org devs) don=E2=80=99t actually understand how the semantics of = cache >> interacts with other babel features. See: >> . >>=20 >> 1-3 are likely to be extremely confusing for users, especially less >> technically sophisticated ones (what=E2=80=99s a =E2=80=9Cpure function= =E2=80=9D anyway)? The >> inability to give a clear introductory explanation of the feature in >> combination with 4 indicating we don=E2=80=99t actually understand it ou= rselves >> makes me feel like we should not be advertising, let alone recommending, >> it. >>=20 >> 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 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. >=20 > Thank you for the explanations. >=20 > 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=E2=80=99ve tried to put all my experience and be= st practices in there; comments are welcome of course. >=20 > 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=E2=80=99t think of a better name either). Thanks, --=20 Aaron Ecay --=-=-= Content-Type: text/x-diff; charset=utf-8 Content-Disposition: inline; filename=0001-babel-update-the-manual-wrt-cache-header-arg.patch Content-Transfer-Encoding: quoted-printable >From bb0f43948384448225323abcfe7a662d110d1389 Mon Sep 17 00:00:00 2001 From: Aaron Ecay 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. =20 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-evaluat= ing -unchanged code blocks. Note that the @code{:cache} header argument will n= ot -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 sessi= on -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 t= ext +of the block itself has changed since the result was computed. The feature +helps avoid re-running long calculations. However, there are edge cases a= nd +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 resourc= es +(like the filesystem or the language=E2=80=99s 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 =E2=80=9CEven more stuff for cache?=E2=80=9D and = =E2=80=9CReproducibility +with RNG=E2=80=9D. (Obviously, you will have to abstract away from the kn= itr +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}. =20 @itemize @bullet @item @code{no} --=20 2.6.2 --=-=-=--