[m-dev.] For review: Add implementation of reference types (global heap)

[Warwick Harvey]

Fergus writes:
> > extras/references/nb_reference.m:
> > 	Implements references which are not backtracked on failure.
> > 
> > extras/references/reference.m:
> > 	Implements references which *are* backtracked on failure.
> 
> In other parts of the Mercury library/extras, the convention has
> been to use `foo.m' for the non-trailed version and `tr_foo.m'
> for the trailed version.  (Specifically library/array.m
> and extras/trailed_update/tr_array.m, and library/store.m and 
> extras/trailed_update/tr_store.m.) 
> I think it would be good to adopt a consistent convention.

But they're not quite the same thing are they?  With array/tr_array and 
store/tr_store, the two versions give the same result after backtracking, do 
they not?  Here, they are explicitly different: with one, changes are *not* 
undone on backtracking.

(I don't mind renaming them if you think they should be: "You the boss."  
;-)  Just let me know.)

> Hmm, "partially permanent" sounds like a bit of a contraction.
> How about calling it `MR_make_long_lived', or perhaps `MR_extend_lifetime'?

Contra(di)ction?

I've made it MR_make_long_lived.

> Our standard naming convention for type names in C is to use
> "MixedCaseIdentifiers".  So this should be `ScopeHandle'
> rather than `scope_handle'.

MixedCaseIdentifiers like MR_untrail_reason?  ;-)

(Sorry, I've *really* got to stop stirring).

Anyway, fixed.

> > :- pragma c_code(exit_scope(Handle::mdi), will_not_call_mercury, "
> > 	exit_scope((scope_handle) Handle);
> > ").
> 
> I suggest you use `pragma import' here:
> 
> 	:- pragma import(exit_scope(mdi), will_not_call_mercury, "exit_scope").

Is this documented anywhere?  I can't find a pragma import in the info files.

How about I just put the body of ME_exit_scope() into the pragma c_code/3, 
like I did with enter_scope (which was so the heap pointer wouldn't be 
screwed up by the function call)?


Thanks for the useful advice.  I'm currently rebuilding the compiler to 
check my changes, and will post another diff once it's passed (and after 
I've made any other changes based on further feedback).

Warwick