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

[Tyson Dowd]

You might want to add that only implementors will know all this stuff.

Also mention that if you copy/2 the arguments you should be able to
avoid these problems (but this is untested).

On 31-Jan-2001, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> 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
> --------------------------------------------------------------------------

-- 
       Tyson Dowd           # 
                            #  Surreal humour isn't everyone's cup of fur.
     trd at cs.mu.oz.au        # 
http://www.cs.mu.oz.au/~trd #
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------