# HG changeset patch
# User jwe
# Date 1189783073 0
# Node ID 110c5782fe3b0153ce0181f86c98eb35f886bcb3
# Parent  f4e1bdb66535cae34183888ccbc2ee1509d889cc
[project @ 2007-09-14 15:17:53 by jwe]

diff -r f4e1bdb66535 -r 110c5782fe3b doc/interpreter/func.txi
--- a/doc/interpreter/func.txi	Fri Sep 14 05:21:57 2007 +0000
+++ b/doc/interpreter/func.txi	Fri Sep 14 15:17:53 2007 +0000
@@ -727,11 +727,69 @@
 
 It is sometime desirable to lock a function into memory with the
 @code{mlock} function. This is typically used for dynamically linked
-functions in Oct-files or mex-files, that contain some initialization,
-and it is desireable that a @code{clear} does not remove this
+functions in Oct-files or mex-files that contain some initialization,
+and it is desirable that calling @code{clear} does not remove this
 initialization.
 
-This might equally be used to prevent changes to a function from having
+As an example,
+
+@example
+mlock ("my_function");
+@end example
+
+@noindent
+prevents @code{my_function} from being removed from memory, even if
+@code{clear} is called.  It is possible to determine if a function is
+locked into memory with the @code{mislocked}, and to unlock a function
+with @code{munlock}, which the following illustrates.
+
+@example
+@group
+mlock ("my_function");
+mislocked ("my_function")
+@result{} ans = 1
+munlock ("my_function");
+mislocked ("my_function")
+@result{} ans = 0
+@end group
+@end example
+
+A common use of @code{mlock} is to prevent persistent variables from
+being removed from memory, as the following example shows.
+
+@example
+@group
+function count_calls()
+  persistent calls = 0;
+  printf ("'count_calls' has been called %d times\n", ++calls);
+endfunction
+mlock ("count_calls");
+
+count_calls ();
+@print{} 'count_calls' has been called 1 times
+
+clear count_calls
+count_calls ();
+@print{} 'count_calls' has been called 2 times
+@end group
+@end example
+
+@noindent
+It is, however, often inconvenient to lock a function from the prompt,
+so it is also possible to lock a function from within its body.  This
+is simply done by calling @code{mlock} from within the function.
+
+@example
+@group
+function count_calls ()
+  mlock ();
+  persistent calls = 0;
+  printf ("'count_calls' has been called %d times\n", ++calls);
+endfunction
+@end group
+@end example
+
+@code{mlock} might equally be used to prevent changes to a function from having
 effect in Octave, though a similar effect can be had with the
 @code{ignore_function_time_stamp} function.
 
diff -r f4e1bdb66535 -r 110c5782fe3b doc/interpreter/plot.txi
--- a/doc/interpreter/plot.txi	Fri Sep 14 05:21:57 2007 +0000
+++ b/doc/interpreter/plot.txi	Fri Sep 14 15:17:53 2007 +0000
@@ -44,7 +44,7 @@
 @end example
 
 @noindent
-displays a sine wave shown in @xref{fig:plot}.  On most systems, this
+displays a sine wave shown in @ref{fig:plot}.  On most systems, this
 command will open a separate plot window to display the graph.
 
 @float Figure,fig:plot
@@ -91,7 +91,7 @@
 
 @noindent
 produces the histogram of 10,000 normally distributed random numbers
-shown in @xref{fig:hist}.
+shown in @ref{fig:hist}.
 
 @float Figure,fig:hist
 @image{hist,8cm}
@@ -128,7 +128,7 @@
 @end example
 
 @noindent
-produces the figure shown in @xref{fig:errorbar}.
+produces the figure shown in @ref{fig:errorbar}.
 
 @float Figure,fig:errorbar
 @image{errorbar,8cm}
@@ -152,7 +152,7 @@
 @end example
 
 @noindent
-produces the spiral plot shown in @xref{fig:polar}.
+produces the spiral plot shown in @ref{fig:polar}.
 
 @float Figure,fig:polar
 @image{polar,8cm}
@@ -182,7 +182,7 @@
 @end example
 
 @noindent
-produces the familiar ``sombrero'' plot shown in @xref{fig:mesh}.  Note
+produces the familiar ``sombrero'' plot shown in @ref{fig:mesh}.  Note
 the use of the function @code{meshgrid} to create matrices of X and Y
 coordinates to use for plotting the Z data.  The @code{ndgrid} function
 is similar to @code{meshgrid}, but works for N-dimensional matrices.
@@ -208,7 +208,7 @@
 @end example
 
 @noindent
-displays the spiral in three dimensions shown in @xref{fig:plot3}.
+displays the spiral in three dimensions shown in @ref{fig:plot3}.
 
 @float Figure,fig:plot3
 @image{plot3,8cm}
diff -r f4e1bdb66535 -r 110c5782fe3b doc/interpreter/var.txi
--- a/doc/interpreter/var.txi	Fri Sep 14 05:21:57 2007 +0000
+++ b/doc/interpreter/var.txi	Fri Sep 14 15:17:53 2007 +0000
@@ -171,9 +171,29 @@
 variables is that persistent variables are local in scope to a
 particular function and are not visible elsewhere.
 
-A variable may be declared persistent using a @code{persistent}
-declaration statement.  The following statements are all persistent
-declarations.
+The following example uses a persistent variable to create a function
+that prints the number of times it has been called.
+
+@example
+@group
+function count_calls ()
+  persistent calls = 0;
+  printf ("'count_calls' has been called %d times\n", ++calls);
+endfunction
+
+for i = 1:3
+  count_calls ();
+endfor
+
+@print{} 'count_calls' has been called 1 times
+@print{} 'count_calls' has been called 2 times
+@print{} 'count_calls' has been called 3 times
+@end group
+@end example
+
+As the example shows, a variable may be declared persistent using a
+@code{persistent} declaration statement.  The following statements are
+all persistent declarations.
 
 @example
 @group
@@ -186,8 +206,9 @@
 
 The behavior of persistent variables is equivalent to the behavior of
 static variables in C. The command @code{static} in octave is also
-recognized and is equivalent to @code{persistent}. Like global
-variables, a persistent variable may only be initialized once.
+recognized and is equivalent to @code{persistent}.
+
+Like global variables, a persistent variable may only be initialized once.
 For example, after executing the following code
 
 @example
@@ -200,6 +221,72 @@
 @noindent
 the value of the persistent variable @code{pvar} is 1, not 2.
 
+If a persistent variable is declared but not initialized to a specific
+value, it will contain an empty matrix.  So, it is also possible to
+initialize a persistent variable by checking whether it is empty, as the
+following example illustrates.
+
+@example
+@group
+function count_calls ()
+  persistent calls;
+  if (isempty (calls))
+    calls = 0;
+  endif
+  printf ("'count_calls' has been called %d times\n", ++calls);
+endfunction
+@end group
+@end example
+
+@noindent
+This implementation behaves in exactly the same way as the previous
+implementation of @code{count_calls}.
+
+The value of a persistent variable is kept in memory until it is
+explicitly cleared.  Assuming that the implementation of @code{count_calls}
+is saved on disc, we get the following behaviour.
+
+@example
+@group
+for i = 1:2
+  count_calls ();
+endfor
+@print{} 'count_calls' has been called 1 times
+@print{} 'count_calls' has been called 2 times
+
+clear
+for i = 1:2
+  count_calls();
+endfor
+@print{} 'count_calls' has been called 3 times
+@print{} 'count_calls' has been called 4 times
+
+clear all
+for i = 1:2
+  count_calls();
+endfor
+@print{} 'count_calls' has been called 1 times
+@print{} 'count_calls' has been called 2 times
+
+clear count_calls
+for i = 1:2
+  count_calls();
+endfor
+@print{} 'count_calls' has been called 1 times
+@print{} 'count_calls' has been called 2 times
+@end group
+@end example
+
+@noindent
+That is, the persistent variable is only removed from memory when the
+function containing the variable is removed.  Note that if the function
+definition is typed directly into the Octave prompt, the persistent
+variable will be cleared by a simple @code{clear} command as the entire
+function definition will be removed from memory.  If you do not want
+a persistent variable to be removed from memory even if the function is
+cleared, you should use the @code{mlock} function as described in
+@xref{Function Locking}.
+
 @node Status of Variables
 @section Status of Variables