[m-dev.] for review: document c_code & static vars

[Fergus Henderson]

On 02-Jan-1998, Christopher Rodd SPEIRS <crs at students.cs.mu.oz.au> wrote:
> > doc/reference_manual.texi:
> > 	Document restrictions on the use of static variables
> > 	in `pragma c_code' declarations.
...
> > +The C code fragment may declare local variables, but it should
> > +not declare static variables, because the Mercury implementation
> > +may duplicate the C code fragment for each call, which would result
> > +in the program having multiple instances of the static variable,
> > +rather than a single shared instance.
> 
> Is this still true if `pragma no_inline' is declared on the C code
> fragment?

No, at least not for the current implementation.

> If it isn't true, then shouldnt we document that so that
> people can use static variables if required? 

Yes, I suppose so.

OK, how about the following?

cvs diff: Diffing .
Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.80
diff -u -u -r1.80 reference_manual.texi
--- reference_manual.texi	1997/12/09 04:02:17	1.80
+++ reference_manual.texi	1998/01/03 10:16:29
@@ -2765,10 +2765,17 @@
 
 @noindent
 means that any calls to the specified mode of @var{Pred} or @var{Func}
-will be replaced by the C code given in @var{C_Code}.
+will result in execution of the C code given in @var{C_Code}.
 The C code fragment may refer to the specified variables
 (@var{Var1}, @var{Var2}, @dots{}, and @var{Var})
 directly by name.
+
+The C code fragment may declare local variables, but it should not
+declare any static variables unless there is also a Mercury
+ at samp{pragma no_inline} declaration (@pxref{Inlining}) for the procedure.
+The reason for this is that otherwise the Mercury implementation may
+inline the procedure by duplicating the C code fragment for each call,
+which would result in the program having multiple instances of the
+static variable, rather than a single shared instance.
 
 If there is a @code{pragma c_code} declaration for a mode of a predicate
 or function, then that mode of the predicate may not have determinism

-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.