NAME

       Ephemeron - Ephemerons and weak hash tables.

Module

       Module   Ephemeron

Documentation

       Module Ephemeron
        : sig end

       Ephemerons and weak hash tables.

       Ephemerons  and  weak  hash  tables  are  useful  when  one wants to cache or memorize the
       computation of a function, as long as the arguments and the  function  are  used,  without
       creating  memory leaks by continuously keeping old computation results that are not useful
       anymore because one argument or the function is freed. An implementation  using  Hashtbl.t
       is  not  suitable  because  all  associations  would  keep the arguments and the result in
       memory.

       Ephemerons can also be used for "adding" a field to an arbitrary boxed  OCaml  value:  you
       can  attach  some  information  to  a  value created by an external library without memory
       leaks.

       Ephemerons hold some keys and one or no data. They are all boxed OCaml values. The keys of
       an  ephemeron  have the same behavior as weak pointers according to the garbage collector.
       In fact OCaml weak pointers are implemented as ephemerons without data.

       The keys and data of an ephemeron are said to be full if they point to a value,  or  empty
       if  the value has never been set, has been unset, or was erased by the GC. In the function
       that accesses the keys or data these two states are represented by the option type.

       The data is considered by the garbage collector alive if all the full keys are  alive  and
       if the ephemeron is alive. When one of the keys is not considered alive anymore by the GC,
       the data is emptied from the ephemeron. The data could be alive for another reason and  in
       that case the GC will not free it, but the ephemeron will not hold the data anymore.

       The  ephemerons  complicate the notion of liveness of values, because it is not anymore an
       equivalence with the reachability from root value by usual  pointers  (not  weak  and  not
       ephemerons).  With  ephemerons the notion of liveness is constructed by the least fixpoint
       of: A value is alive if:

       -it is a root value

       -it is reachable from alive value by usual pointers

       -it is the data of an alive ephemeron with all its full keys alive

       Notes:

       -All the types defined in this module  cannot  be  marshaled  using  output_value  or  the
       functions of the Marshal module.

       Ephemerons  are  defined in a language agnostic way in this paper: B. Hayes, Ephemerons: A
       New Finalization Mechanism, OOPSLA'97

       Since 4.03.0

       module type S = sig end

       The output signature of the functor Ephemeron.K1.Make and Ephemeron.K2.Make .  These  hash
       tables  are  weak in the keys. If all the keys of a binding are alive the binding is kept,
       but if one of the keys of the binding is dead then the binding is removed.

       module type SeededS = sig end

       The output signature of the functor Ephemeron.K1.MakeSeeded and Ephemeron.K2.MakeSeeded .

       module K1 : sig end

       Ephemerons with one key.

       module K2 : sig end

       Emphemerons with two keys.

       module Kn : sig end

       Emphemerons with arbitrary number of keys of the same type.

       module GenHashTable : sig end

       Hash tables on generic containers with notion of death and aliveness.