changeset 19469:51a1d1164449

Add extra docs about the performance benefits of operator functions (bug #36439). * func.txi: Document using handles to operator functions rather than anonymous wrapper functions. * vectorize.txi: Document using handles to operator functions when using cellfun, arrayfun, etc.
author Rik <rik@octave.org>
date Sun, 28 Dec 2014 06:58:09 -0800
parents aee5fea8a03e
children 9552138fe6f5
files doc/interpreter/func.txi doc/interpreter/vectorize.txi
diffstat 2 files changed, 35 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/func.txi	Fri Dec 26 14:35:46 2014 -0500
+++ b/doc/interpreter/func.txi	Sun Dec 28 06:58:09 2014 -0800
@@ -1389,6 +1389,32 @@
 are passed to @code{betainc} are inherited from the current
 environment.
 
+Note that for performance reasons it is better to use handles to existing
+Octave functions, rather than to define anonymous functions which wrap an
+existing function.  The integration of @code{sin (x)} is 5X faster if the code
+is written as
+
+@example
+quad (@@sin, 0, pi)
+@end example
+
+rather than using the anonymous function @code{@@(x) sin (x)}.  There are many
+operators which have functional equivalents that may be better choices than an
+anonymous function.  Instead of writing
+
+@example
+f = @@(x, y) x + y 
+@end example
+
+this should be coded as
+
+@example
+f = @@plus
+@end example
+
+@xref{Operator Overloading}, for a list of operators which also have a
+functional form.
+
 @node Inline Functions
 @subsection Inline Functions
 
--- a/doc/interpreter/vectorize.txi	Fri Dec 26 14:35:46 2014 -0500
+++ b/doc/interpreter/vectorize.txi	Sun Dec 28 06:58:09 2014 -0800
@@ -496,6 +496,15 @@
 
 @DOCSTRING(structfun)
 
+Consistent with earlier advice, seek to use Octave built-in functions whenever
+possible for the best performance.  This advice applies especially to the four
+functions above.  For example, when adding two arrays together
+element-by-element one could use a handle to the built-in addition function
+@code{@@plus} or define an anonymous function @code{@@(x,y) x + y}.  But, the
+anonymous function is 60% slower than the first method.
+@xref{Operator Overloading}, for a list of basic functions which might be used
+in place of anonymous ones.
+
 @node Accumulation
 @section Accumulation