>From cc5646ae517f0792e5acd721f4f2f6dec7a602b3 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Wed, 17 Apr 2019 16:34:47 +0100 Subject: [PATCH 1/2] Improve pure and side-effect-free docs For discussion, see thread starting at: https://lists.gnu.org/archive/html/emacs-devel/2019-04/msg00316.html * doc/lispref/customize.texi (Composite Types): Do not overspecify :match-alternatives predicates. * doc/lispref/functions.texi (What Is a Function): Define what a pure function is. * doc/lispref/internals.texi (Writing Emacs Primitives): Describe currently preferred approach to marking primitives as pure and side-effect-free. * doc/lispref/macros.texi (Eval During Expansion): Index under 'side effect'. * doc/lispref/symbols.texi (Standard Properties): Expand description of pure and side-effect-free properties. --- doc/lispref/customize.texi | 8 ++++---- doc/lispref/functions.texi | 5 +++++ doc/lispref/internals.texi | 14 ++++++++++---- doc/lispref/macros.texi | 1 + doc/lispref/symbols.texi | 15 +++++++++++---- 5 files changed, 31 insertions(+), 12 deletions(-) diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index f71dedfd8b..02eefe0f58 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -950,10 +950,10 @@ Composite Types @itemize @bullet @item -A predicate---that is, a function of one argument that has no side -effects, and returns either @code{nil} or address@hidden according to -the argument. Using a predicate in the list says that objects for which -the predicate returns address@hidden are acceptable. +A predicate---that is, a function of one argument that returns either address@hidden or address@hidden according to the argument. Using a +predicate in the list says that objects for which the predicate +returns address@hidden are acceptable. @item A quoted constant---that is, @code{'@var{object}}. This sort of element diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 222f863c98..0f9c977268 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -38,11 +38,16 @@ What Is a Function @cindex return value @cindex value of function @cindex argument address@hidden side effect address@hidden pure function In a general sense, a function is a rule for carrying out a computation given input values called @dfn{arguments}. The result of the computation is called the @dfn{value} or @dfn{return value} of the function. The computation can also have side effects, such as lasting changes in the values of variables or the contents of data structures. +A @dfn{pure function} is a function which, in addition to having no +side effects, always returns the same value for the same combination +of arguments, regardless of external factors such as machine type. In most computer languages, every function has a name. But in Lisp, a function in the strictest sense has no name: it is an object which diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 8ebe47d9ad..9947e37ca1 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1031,10 +1031,16 @@ Writing Emacs Primitives @file{lisp.h} contains the definitions for some important macros and functions. - If you define a function which is side-effect free, update the code -in @file{byte-opt.el} that binds @code{side-effect-free-fns} and address@hidden so that the compiler optimizer -knows about it. address@hidden @code{side-effect-free} address@hidden @code{pure} address@hidden side-effect-free-fns address@hidden side-effect-and-error-free-fns + If you define a function which is side-effect free and/or pure, give +it a address@hidden @code{side-effect-free} and/or @code{pure} +property, respectively (@pxref{Standard Properties}). Alternatively, +you can update the code in @file{byte-opt.el} that binds address@hidden and @code{side-effect-and-error-free-fns}, +but this approach is less modular and no longer encouraged. @node Writing Dynamic Modules @section Writing Dynamically-Loaded Modules diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index a422ba9750..bcee5b1078 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -523,6 +523,7 @@ Eval During Expansion @node Repeated Expansion @subsection How Many Times is the Macro Expanded? address@hidden side effect Occasionally problems result from the fact that a macro call is expanded each time it is evaluated in an interpreted function, but is diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index a214a2d3fd..e49c500701 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -558,9 +558,12 @@ Standard Properties modes. @xref{Setting Hooks}. @item pure address@hidden @code{pure} If the value is address@hidden, the named function is considered to be -side-effect free. Calls with constant arguments can be evaluated at -compile time. This may shift run time errors to compile time. +side-effect free and pure (@pxref{What Is a Function}). Calls with +constant arguments can be evaluated at compile time. This may shift +run time errors to compile time. Not to be confused with pure storage +(@pxref{Pure Storage}). @item risky-local-variable If the value is address@hidden, the named variable is considered risky @@ -579,9 +582,13 @@ Standard Properties for the named variable. @xref{File Local Variables}. @item side-effect-free address@hidden @code{side-effect-free} A address@hidden value indicates that the named function is free of -side-effects, for determining function safety (@pxref{Function -Safety}) as well as for byte compiler optimizations. Do not set it. +side effects (@pxref{What Is a Function}), so the byte compiler may +ignore calls whose value is unused. If the property's value is address@hidden, the byte compiler may even delete such unused +calls. In addition to byte compiler optimizations, this property is +also used for determining function safety (@pxref{Function Safety}). @item variable-documentation If address@hidden, this specifies the named variable's documentation -- 2.20.1