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

[Fergus Henderson]

Estimated hours taken: 0.5

browser/dl.m:
	Document the dangers of calling dl__close.

Workspace: /home/hg/fjh/mercury
Index: browser/dl.m
===================================================================
RCS file: /home/mercury1/repository/mercury/browser/dl.m,v
retrieving revision 1.8
diff -u -d -r1.8 dl.m
--- browser/dl.m	2001/01/29 06:47:12	1.8
+++ browser/dl.m	2001/01/31 08:25:51
@@ -54,6 +54,24 @@
 	io__state::di, io__state::uo) is det.
 
 % interface to the C function dlclose()
+%
+% WARNING: dlclose() is form of manual memory management.
+% You need to make sure that no remaining references to code or
+% static data in the dynamically linked module before you call dl__close,
+% because if you do reference code or static data from the dynamically
+% linked module after dl__close has been called, then the behaviour is
+% undefined (and probably harmful!).
+% 
+% This can be difficult to ensure.  You need to make sure that you
+% don't keep any references to the higher-order terms return by dl__sym.
+% Furthermore you need to make sure that you don't keep any references
+% to terms constructed by procedures in the dynamically loaded module,
+% since such terms may contain references to static data in the
+% dynamically loaded module.  You must also ensure that you don't keep
+% 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.
+% 
 :- 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
--------------------------------------------------------------------------