1Ephemeron(3)                     OCaml library                    Ephemeron(3)
2
3
4

NAME

6       Ephemeron - Ephemerons and weak hash tables.
7

Module

9       Module   Ephemeron
10

Documentation

12       Module Ephemeron
13        : sig end
14
15
16       Ephemerons and weak hash tables.
17
18       Ephemerons  and  weak hash tables are useful when one wants to cache or
19       memorize the computation of a function, as long as  the  arguments  and
20       the  function  are  used, without creating memory leaks by continuously
21       keeping old computation results that are not useful anymore because one
22       argument or the function is freed. An implementation using Hashtbl.t is
23       not suitable because all associations would keep the arguments and  the
24       result in memory.
25
26       Ephemerons  can also be used for "adding" a field to an arbitrary boxed
27       OCaml value: you can attach some information to a value created  by  an
28       external library without memory leaks.
29
30       Ephemerons  hold some keys and one or no data. They are all boxed OCaml
31       values. The keys of an ephemeron have the same behavior as weak  point‐
32       ers according to the garbage collector. In fact OCaml weak pointers are
33       implemented as ephemerons without data.
34
35       The keys and data of an ephemeron are said to be full if they point  to
36       a  value,  or empty if the value has never been set, has been unset, or
37       was erased by the GC. In the function that accesses the  keys  or  data
38       these two states are represented by the option type.
39
40       The  data  is considered by the garbage collector alive if all the full
41       keys are alive and if the ephemeron is alive. When one of the  keys  is
42       not  considered  alive  anymore by the GC, the data is emptied from the
43       ephemeron. The data could be alive for another reason and in that  case
44       the  GC will not free it, but the ephemeron will not hold the data any‐
45       more.
46
47       The ephemerons complicate the notion of liveness of values, because  it
48       is  not anymore an equivalence with the reachability from root value by
49       usual pointers (not weak and not ephemerons). With ephemerons  the  no‐
50       tion  of  liveness  is constructed by the least fixpoint of: A value is
51       alive if:
52
53       -it is a root value
54
55       -it is reachable from alive value by usual pointers
56
57       -it is the data of an alive ephemeron with all its full keys alive
58
59       Notes:
60
61       -All the types defined in this module cannot be  marshaled  using  out‐
62       put_value or the functions of the Marshal module.
63
64       Ephemerons  are  defined  in  a language agnostic way in this paper: B.
65       Hayes, Ephemerons: A New Finalization Mechanism, OOPSLA'97
66
67
68       Since 4.03.0
69
70
71       Alert unsynchronized_access.  Unsynchronized accesses to weak hash  ta‐
72       bles are a programming error.
73
74
75
76
77
78
79
80       Unsynchronized accesses
81
82       Unsynchronized  accesses  to  a  weak hash table may lead to an invalid
83       weak hash table state. Thus, concurrent accesses to a  buffer  must  be
84       synchronized (for instance with a Mutex.t ).
85
86       module type S = sig end
87
88
89       The   output   signature   of   the   functors   Ephemeron.K1.Make  and
90       Ephemeron.K2.Make .  These hash tables are weak in the keys. If all the
91       keys of a binding are alive the binding is kept, but if one of the keys
92       of the binding is dead then the binding is removed.
93
94
95       module type SeededS = sig end
96
97
98       The  output  signature  of  the  functors  Ephemeron.K1.MakeSeeded  and
99       Ephemeron.K2.MakeSeeded .
100
101
102       module K1 : sig end
103
104
105       Ephemerons with one key.
106
107
108       module K2 : sig end
109
110
111       Ephemerons with two keys.
112
113
114       module Kn : sig end
115
116
117       Ephemerons with arbitrary number of keys of the same type.
118
119
120
121
122
123OCamldoc                          2023-07-20                      Ephemeron(3)