[m-dev.] for review: document dl__close caveats

[Fergus Henderson]

On 01-Feb-2001, Adrian Pellas-Rice <apell at students.cs.mu.oz.au> wrote:
> 
> On Wed, 31 Jan 2001, Fergus Henderson wrote:
> 
> > On 31-Jan-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> > > 
> > > You might want to add that only implementors will know all this stuff.
> 
> [snip]
> 
> > On the other hand, the fact that copy/2 won't work is perhaps a good
> > reason to document it.  
> 
> Yes.  It is at least worth mentioning that "copy/2 will not work in some
> cases."  
> 
> To me, the name `copy' suggests that copy/2 is the ideal work-around to
> try -- no implementation knowledge exercised. Unless attention is drawn to
> the fact, it's likely someone will end up assuming that the copy/2 method
> works in the general case on the basis of a few successful trials.

OK, how about this?

browser/dl.m:
	Mention the danger of trying to use builtin__copy
	as a solution to the dangers of dl__close.

Workspace: /home/hg/fjh/mercury
Index: browser/dl.m
===================================================================
RCS file: /home/mercury1/repository/mercury/browser/dl.m,v
retrieving revision 1.5.4.2
diff -u -d -r1.5.4.2 dl.m
--- browser/dl.m	2001/02/06 09:14:15	1.5.4.2
+++ browser/dl.m	2001/02/06 09:25:42
@@ -71,6 +71,9 @@
 % any references to types or instances defined in the dynamically loaded
 % module, as might be the case if you're using existentially quantified
 % data types, since they too can contain references to static data.
+%
+% (Note that using builtin__copy/2, to make copies rather than
+% keeping references, is *not* guaranteed to work in all cases.)
 % 
 :- pred dl__close(handle::in, dl__result::out,
 	io__state::di, io__state::uo) is det.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
                                    |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------