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