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 functors 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 functors Ephemeron.K1.MakeSeeded and Ephemeron.K2.MakeSeeded .

       module K1 : sig end

       Ephemerons with one key.

       module K2 : sig end

       Ephemerons with two keys.

       module Kn : sig end

       Ephemerons with arbitrary number of keys of the same type.

       module GenHashTable : sig end

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

OCamldoc                                           2023-10-26                                      Ephemeron(3o)