[mercury-users] C-Interface (Memory Management)

[Fergus Henderson]

On 09-Nov-1998, Peter Herkenrath <P.Herkenrath at rrz.uni-koeln.de> wrote:
> Hi folks,
> as an old Perl addict I missed pattern matching in Mercury. 
> I wanted to reuse an Sicstus interface to the regex library (prolog-rx
> by Gerd van Noord).
> The C function regex_match should return the matched substrings as a
> list(string) type. Such a case is not mentioned in the Language
> Reference
> and not demonstrated in samples/c_interface.
> After much try and error I finally managed to make a (mostly) working
> interface to the regex library. The strings were allocated via
> make_many(), 4cons4ed by an Mercury function, ... .
> The general questions:
> Is this the 4right4 way to allocate memory for an object which will be
> used by Mercury?
> When (and how) should such Objects be deallocated (via oldmem?)?

The most reliable way of allocating lists and other complex data
structures, if you need to do it in C code rather than in Mercury code,
is to define constructor functions in Mercury and export these to C
using `pragma export':

	:- func cons(T, list(T)) = list(T).
	:- pragma export (cons/2, "cons").
	cons(H, T) = [H | T].

	:- func nil = list(T).
	:- pragma export (nil/0, "nil").
	nil = [].

Then you can allocate memory by just calling the functions cons() and nil()
from your C code.  The memory will be recovered by garbage collection
(if you have GC enabled) or on backtracking (if you're not using
conservative GC).

Strings are a little more complicated.  I suppose the most reliable,
implementation-independent way to allocate strings would be to make
list of characters using the technique above, and then call the Mercury
predicate string__from_char_list/2.  However, that would be rather
inefficient!  Fortunately there are more efficient alternatives.
Unfortunately they are a bit more implementation-specific;
that is, the details of exactly how to do depend on what compilation
grade you select, and they might change a bit in future versions of Mercury.

But nevertheless, here's how to do it.  Rather than using make_many(),
you should use make_aligned_string_copy().  If the string you are
returning is guaranteed to survive for as long as Mercury will need it,
e.g. it is a string literal, then you can use make_aligned_string(),
which will often be more efficient, instead of make_aligned_string_copy(). 
See the comments in mercury_string.h for documentation on these macros.

If you're using conservative GC, that's all you have to worry about.
But if you're not, then there is an additional constraint to observe:
the make_aligned_string() and make_aligned_string_copy() macros should
only be called from `pragma c_code' fragments declared with
`will_not_call_mercury'.

Memory allocated using make_aligned_string_copy() will be allocated on
the Mercury heap and will be recovered on backtracking or garbage
collection as usual.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "Binaries may die
WWW: <http://www.cs.mu.oz.au/~fjh>  |   but source code lives forever"
PGP: finger fjh at 128.250.37.3        |     -- leaked Microsoft memo.