Commit 3988e93d authored by Basil L. Contovounesios's avatar Basil L. Contovounesios

Backport: 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/eval.texi (Intro Eval): Anchor definition of "side
effect" for cross-referencing...
* doc/lispref/functions.texi (What Is a Function): ...from here.
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/symbols.texi (Standard Properties): Expand description
of pure and side-effect-free properties.

(cherry picked from commit 4430a9b5)
parent 7565d2d2
Pipeline #1403 passed with stage
in 29 minutes and 20 seconds
......@@ -950,10 +950,10 @@ possibilities:
@itemize @bullet
@item
A predicate---that is, a function of one argument that has no side
effects, and returns either @code{nil} or non-@code{nil} according to
the argument. Using a predicate in the list says that objects for which
the predicate returns non-@code{nil} are acceptable.
A predicate---that is, a function of one argument that returns either
@code{nil} or non-@code{nil} according to the argument. Using a
predicate in the list says that objects for which the predicate
returns non-@code{nil} are acceptable.
@item
A quoted constant---that is, @code{'@var{object}}. This sort of element
......
......@@ -86,6 +86,7 @@ also temporarily alter the environment by binding variables
(@pxref{Local Variables}).
@cindex side effect
@anchor{Definition of side effect}
Evaluating a form may also make changes that persist; these changes
are called @dfn{side effects}. An example of a form that produces a
side effect is @code{(setq foo 1)}.
......
......@@ -38,11 +38,16 @@ define them.
@cindex return value
@cindex value of function
@cindex argument
@cindex 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.
changes in the values of variables or the contents of data structures
(@pxref{Definition of side effect}). 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 or system state.
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
......
......@@ -976,10 +976,9 @@ number of arguments. They work by calling @code{Ffuncall}.
@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
@code{side-effect-and-error-free-fns} so that the compiler optimizer
knows about it.
If you define a function which is side-effect free or pure, give it
a non-@code{nil} @code{side-effect-free} or @code{pure} property,
respectively (@pxref{Standard Properties}).
@node Writing Dynamic Modules
@section Writing Dynamically-Loaded Modules
......
......@@ -558,9 +558,12 @@ deleted from the local value of a hook variable when changing major
modes. @xref{Setting Hooks}.
@item pure
@cindex @code{pure} property
If the value is non-@code{nil}, 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.
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 non-@code{nil}, the named variable is considered risky
......@@ -579,9 +582,13 @@ The value specifies a function for determining safe file-local values
for the named variable. @xref{File Local Variables}.
@item side-effect-free
@cindex @code{side-effect-free} property
A non-@code{nil} 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 a call whose value is unused. If the property's value is
@code{error-free}, 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 non-@code{nil}, this specifies the named variable's documentation
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment