diff: reference_manual.texi: memory management

[Fergus Henderson]

doc/reference_manual.texi:
	Add some documentation about memory management when using the
	C interface.

Index: reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.62
diff -u -r1.62 reference_manual.texi
--- reference_manual.texi	1997/07/28 10:36:07	1.62
+++ reference_manual.texi	1997/07/28 11:59:17
@@ -2813,11 +2813,8 @@
 list_cons(head,tail)    /* construct a list with the given head and tail */
 @end example
 
-The @samp{list_cons} macro should only be used in C code called
-using the @samp{will_not_call_mercury} calling convention.
- at c XXX I am not sure about this - zs
-
- at c XXX we need a more extensive discussion on memory allocation here
+Note that the use of these macros is subject to some caveats
+(@pxref{Memory management}).
 
 @node Using C pointers
 @subsection Using C pointers
@@ -2857,6 +2854,44 @@
         may_call_mercury,
         "Structure = perform_calculation(Value, Structure0);").
 @end example
+
+ at node Memory management
+ at subsection Memory management
+
+Passing pointers to dynamically-allocated memory from Mercury to code
+written in other languages, or vice versa, is in general
+implementation-dependent.
+
+The current Mercury implementation supports two different methods of memory
+management: conservative garbage collection, or no garbage collection.
+(With the latter method, heap storage is reclaimed only on backtracking.)
+
+Conservative garbage collection makes inter-language calls simplest.
+When using conservative garbage collection, heap storage is reclaimed
+automatically.  Pointers to dynamically-allocated memory can be passed
+to and from C without taking any special precautions.
+
+When using no garbage collection, you must be careful not to retain
+pointers to memory on the Mercury heap after Mercury has backtracked
+to before the point where that memory was allocated.
+You must also avoid the use of the macros
+ at code{list_empty()} and @code{list_cons()}.
+(The reason for this is that they may access Mercury's @samp{hp} register,
+which might not be valid in C code.  Using them in the bodies of
+procedures defined using @samp{pragma c_code} with
+ at samp{will_not_call_mercury} would probably work, but we don't advise it.)
+Instead, you can write Mercury functions to perform these actions
+and use @samp{pragma export} to access them from C.
+This alternative method also works with conservative garbage collection.
+
+Future Mercury implementations may use non-conservative methods
+of garbage collection.  For such implementations, it will be necessary
+to explicitly register pointers passed to C with the garbage collector.
+The mechanism for doing this has not yet been decided on.
+It would be desirable to provide a single memory management interface
+for use when interfacing with other languages that can work for all
+methods of memory management, but more implementation experience is
+needed before we can formulate such an interface.
 
 @node Inlining
 @section Inlining

-- 
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.