Mercurial > hg > octave-nkf
changeset 6899:110c5782fe3b
[project @ 2007-09-14 15:17:53 by jwe]
author | jwe |
---|---|
date | Fri, 14 Sep 2007 15:17:53 +0000 |
parents | f4e1bdb66535 |
children | e2d560e5a58d |
files | doc/interpreter/func.txi doc/interpreter/plot.txi doc/interpreter/var.txi |
diffstat | 3 files changed, 159 insertions(+), 14 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/func.txi +++ b/doc/interpreter/func.txi @@ -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.
--- a/doc/interpreter/plot.txi +++ b/doc/interpreter/plot.txi @@ -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}
--- a/doc/interpreter/var.txi +++ b/doc/interpreter/var.txi @@ -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