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

NAME

6       Weak - Arrays of weak pointers and hash sets of weak pointers.
7

Module

9       Module   Weak
10

Documentation

12       Module Weak
13        : sig end
14
15
16       Arrays of weak pointers and hash sets of weak pointers.
17
18
19
20
21
22
23
24   Low-level functions
25       type 'a t
26
27
28       The type of arrays of weak pointers (weak arrays).  A weak pointer is a
29       value that the garbage collector may erase whenever the  value  is  not
30       used  any more (through normal pointers) by the program.  Note that fi‐
31       nalisation functions are run before the weak pointers are  erased,  be‐
32       cause  the  finalisation  functions can make values alive again (before
33       4.03 the finalisation functions were run after).
34
35       A weak pointer is said to be full if it points to a value, empty if the
36       value was erased by the GC.
37
38       Notes:
39
40       -Integers are not allocated and cannot be stored in weak arrays.
41
42       -Weak  arrays  cannot be marshaled using output_value nor the functions
43       of the Marshal module.
44
45
46
47
48       val create : int -> 'a t
49
50
51       Weak.create n returns a new weak array of length n .  All the  pointers
52       are initially empty.
53
54
55       Raises  Invalid_argument  if  n  is  not  comprised  between  zero  and
56       Obj.Ephemeron.max_ephe_length (limits included).
57
58
59
60       val length : 'a t -> int
61
62
63       Weak.length ar returns the length (number of elements) of ar .
64
65
66
67       val set : 'a t -> int -> 'a option -> unit
68
69
70       Weak.set ar n (Some el) sets the n th cell of ar to be a (full) pointer
71       to el ; Weak.set ar n None sets the n th cell of ar to empty.
72
73
74       Raises  Invalid_argument if n is not in the range 0 to Weak.length ar -
75       1 .
76
77
78
79       val get : 'a t -> int -> 'a option
80
81
82       Weak.get ar n returns None if the n th cell of  ar  is  empty,  Some  x
83       (where x is the value) if it is full.
84
85
86       Raises  Invalid_argument if n is not in the range 0 to Weak.length ar -
87       1 .
88
89
90
91       val get_copy : 'a t -> int -> 'a option
92
93
94       Weak.get_copy ar n returns None if the n th cell of ar is empty, Some x
95       (where  x is a (shallow) copy of the value) if it is full.  In addition
96       to pitfalls with mutable values, the interesting difference with get is
97       that  get_copy  does  not  prevent  the incremental GC from erasing the
98       value in its current cycle ( get may delay the erasure to the  next  GC
99       cycle).
100
101
102       Raises  Invalid_argument if n is not in the range 0 to Weak.length ar -
103       1 .
104
105       If the element is a custom block it is not copied.
106
107
108
109       val check : 'a t -> int -> bool
110
111
112       Weak.check ar n returns true if the n th cell of ar is full,  false  if
113       it is empty.  Note that even if Weak.check ar n returns true , a subse‐
114       quent Weak.get ar n can return None .
115
116
117       Raises Invalid_argument if n is not in the range 0 to Weak.length ar  -
118       1 .
119
120
121
122       val fill : 'a t -> int -> int -> 'a option -> unit
123
124
125       Weak.fill ar ofs len el sets to el all pointers of ar from ofs to ofs +
126       len - 1 .
127
128
129       Raises Invalid_argument if ofs and len do not designate a valid  subar‐
130       ray of ar .
131
132
133
134       val blit : 'a t -> int -> 'a t -> int -> int -> unit
135
136
137       Weak.blit  ar1  off1  ar2  off2  len  copies len weak pointers from ar1
138       (starting at off1 ) to ar2 (starting at off2  ).   It  works  correctly
139       even if ar1 and ar2 are the same.
140
141
142       Raises Invalid_argument if off1 and len do not designate a valid subar‐
143       ray of ar1 , or if off2 and len do not designate a  valid  subarray  of
144       ar2 .
145
146
147
148
149   Weak hash sets
150       A  weak  hash  set is a hashed set of values.  Each value may magically
151       disappear from the set when it is not used by the rest of  the  program
152       any  more.   This is normally used to share data structures without in‐
153       ducing memory leaks.  Weak hash sets  are  defined  on  values  from  a
154       Hashtbl.HashedType  module;  the  equal  relation and hash function are
155       taken from that module.  We will say that v is  an  instance  of  x  if
156       equal x v is true .
157
158       The equal relation must be able to work on a shallow copy of the values
159       and give the same result as with the values themselves.
160
161       Unsynchronized accesses
162
163       Unsynchronized accesses to weak hash sets are a programming error.  Un‐
164       synchronized  accesses  to  a weak hash set may lead to an invalid weak
165       hash set state. Thus, concurrent accesses to weak  hash  sets  must  be
166       synchronized (for instance with a Mutex.t ).
167
168       module type S = sig end
169
170
171       The output signature of the functor Weak.Make .
172
173
174       module Make : functor (H : Hashtbl.HashedType) -> sig end
175
176
177       Functor  building  an  implementation  of  the weak hash set structure.
178       H.equal can't be the physical equality, since only  shallow  copies  of
179       the elements in the set are given to it.
180
181
182
183
184
185OCamldoc                          2023-07-20                           Weak(3)