NAME

       Stdlib.Ephemeron - no description

Module

       Module   Stdlib.Ephemeron

Documentation

       Module Ephemeron
        : (module Stdlib__ephemeron)

       Ephemerons  and  weak  hash  table  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 in memory the arguments and the
       result.

       Ephemerons can also be used for "adding" a field to an arbitrary boxed  ocaml  value:  you
       can attach an 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 than 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, empty if
       the value have never been set, have 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'9

       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

       module K2 : sig end

       module Kn : sig end

       module GenHashTable : sig end