NAME

       Ephemeron - Ephemerons and weak hash table

Module

       Module   Ephemeron

Documentation

       Module Ephemeron
        : sig end

       Ephemerons and weak hash table

       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

OCamldoc                                           2020-01-30                                      Ephemeron(3o)