[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: new snapshot soon
From: |
Søren Hauberg |
Subject: |
Re: new snapshot soon |
Date: |
Fri, 14 Sep 2007 11:27:57 +0200 |
User-agent: |
Thunderbird 1.5.0.13 (X11/20070824) |
John W. Eaton skrev:
On 13-Sep-2007, Søren Hauberg wrote:
| P.S. I'll send a patch to fix the problem with the persistent variables
| documentation tomorrow. I'm just saying it, so that nobody else will
| waste their time on it...
I've already made a change for that, but if you can further improve
it, go ahead.
The attached patch adds a little bit more information and some examples.
Søren
Index: var.txi
===================================================================
RCS file: /cvs/octave/doc/interpreter/var.txi,v
retrieving revision 1.32
diff -u -r1.32 var.txi
--- var.txi 13 Sep 2007 18:49:15 -0000 1.32
+++ var.txi 14 Sep 2007 09:24:54 -0000
@@ -171,9 +171,27 @@
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.
+
address@hidden
+function count_calls()
+ persistent calls = 0;
+ printf("'count_calls' has been called %d times\n", ++calls);
+endfunction
+
+for i = 1:3
+ count_calls();
+endfor
+
address@hidden 'count_calls' has been called 1 times
address@hidden 'count_calls' has been called 2 times
address@hidden 'count_calls' has been called 3 times
address@hidden example
+
+As the example shows, a variable may be declared persistent using a
address@hidden declaration statement. The following statements are
+all persistent declarations.
@example
@group
@@ -186,8 +204,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 +219,68 @@
@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 be contain an empty matrix. So, it is also possible to
+initialize a persistent variable by checking if it is empty, as the
+following example illustrates.
+
address@hidden
+function count_calls()
+ persistent calls;
+ if (isempty(calls))
+ calls = 0;
+ endif
+ printf("'count_calls' has been called %d times\n", ++calls);
+endfunction
address@hidden example
+
address@hidden
+This implementation behaves in the exact 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.
+
address@hidden
+for i = 1:2
+ count_calls();
+endfor
address@hidden 'count_calls' has been called 1 times
address@hidden 'count_calls' has been called 2 times
+
+clear
+for i = 1:2
+ count_calls();
+endfor
address@hidden 'count_calls' has been called 3 times
address@hidden 'count_calls' has been called 4 times
+
+clear all
+for i = 1:2
+ count_calls();
+endfor
address@hidden 'count_calls' has been called 1 times
address@hidden 'count_calls' has been called 2 times
+
+clear count_calls
+for i = 1:2
+ count_calls();
+endfor
address@hidden 'count_calls' has been called 1 times
address@hidden 'count_calls' has been called 2 times
address@hidden example
+
address@hidden
+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
address@hidden Locking}.
+
@node Status of Variables
@section Status of Variables
Index: func.txi
===================================================================
RCS file: /cvs/octave/doc/interpreter/func.txi,v
retrieving revision 1.27
diff -u -r1.27 func.txi
--- func.txi 18 Jul 2007 17:03:10 -0000 1.27
+++ func.txi 14 Sep 2007 09:24:54 -0000
@@ -731,7 +731,59 @@
and it is desireable that a @code{clear} does not remove this
initialization.
-This might equally be used to prevent changes to a function from having
+As an example
+
address@hidden
+mlock("my_function");
address@hidden example
+
address@hidden
+prevents @code{my_function} from being removed from memory, even if
address@hidden 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.
+
address@hidden
+mlock("my_function");
+mislocked("my_function")
address@hidden ans = 1
+munlock("my_function");
+mislocked("my_function")
address@hidden ans = 0
address@hidden example
+
+A common use of @code{mlock} is to prevent persistent variables from
+being removed from memory, as the following example shows.
+
address@hidden
+function count_calls()
+ persistent calls = 0;
+ printf("'count_calls' has been called %d times\n", ++calls);
+endfunction
+mlock("count_calls");
+
+count_calls();
address@hidden 'count_calls' has been called 1 times
+
+clear count_calls
+count_calls();
address@hidden 'count_calls' has been called 2 times
address@hidden example
+
address@hidden
+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.
+
address@hidden
+function count_calls()
+ mlock;
+ persistent calls = 0;
+ printf("'count_calls' has been called %d times\n", ++calls);
+endfunction
address@hidden example
+
address@hidden 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.
- new snapshot soon, John W. Eaton, 2007/09/13
- Re: new snapshot soon, kahacjde, 2007/09/13
- Re: new snapshot soon, David Bateman, 2007/09/14
- Re: new snapshot soon, Jean-Francois Cardoso, 2007/09/14
- Re: new snapshot soon, Tatsuro MATSUOKA, 2007/09/14