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

NAME

6       Stdlib.Weak - no description
7

Module

9       Module   Stdlib.Weak
10

Documentation

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 a - 1
74       .
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 a - 1
86       .
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 a - 1
102       .
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
117       val fill : 'a t -> int -> int -> 'a option -> unit
118
119
120       Weak.fill ar ofs len el sets to el all pointers of ar from ofs to ofs +
121       len - 1 .
122
123
124       Raises  Invalid_argument if ofs and len do not designate a valid subar‐
125       ray of a .
126
127
128
129       val blit : 'a t -> int -> 'a t -> int -> int -> unit
130
131
132       Weak.blit ar1 off1 ar2 off2 len  copies  len  weak  pointers  from  ar1
133       (starting  at  off1  )  to ar2 (starting at off2 ).  It works correctly
134       even if ar1 and ar2 are the same.
135
136
137       Raises Invalid_argument if off1 and len do not designate a valid subar‐
138       ray  of  ar1  , or if off2 and len do not designate a valid subarray of
139       ar2 .
140
141
142
143
144   Weak hash sets
145       A weak hash set is a hashed set of values.  Each  value  may  magically
146       disappear  from  the set when it is not used by the rest of the program
147       any more.  This is normally used to share data structures  without  in‐
148       ducing  memory  leaks.   Weak  hash  sets  are defined on values from a
149       Hashtbl.HashedType module; the equal relation  and  hash  function  are
150       taken  from  that  module.   We  will say that v is an instance of x if
151       equal x v is true .
152
153       The equal relation must be able to work on a shallow copy of the values
154       and give the same result as with the values themselves.
155
156       module type S = sig end
157
158
159       The output signature of the functor Weak.Make .
160
161
162       module Make : functor (H : Hashtbl.HashedType) -> sig end
163
164
165       Functor  building  an  implementation  of  the weak hash set structure.
166       H.equal can't be the physical equality, since only  shallow  copies  of
167       the elements in the set are given to it.
168
169
170
171
172
173OCamldoc                          2022-07-22                    Stdlib.Weak(3)
Impressum