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
26
27       type 'a t
28
29
30       The type of arrays of weak pointers (weak arrays).  A weak pointer is a
31       value that the garbage collector may erase whenever the  value  is  not
32       used  any  more  (through  normal  pointers) by the program.  Note that
33       finalisation functions are run after the weak pointers are erased.
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 Pervasives.output_value nor the
43       functions 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.   Raise  Invalid_argument  if  n  is negative or
53       greater than Sys.max_array_length -1 .
54
55
56
57       val length : 'a t -> int
58
59
60       Weak.length ar returns the length (number of elements) of ar .
61
62
63
64       val set : 'a t -> int -> 'a option -> unit
65
66
67       Weak.set ar n (Some el) sets the n th cell of ar to be a (full) pointer
68       to  el  ;  Weak.set ar n None sets the n th cell of ar to empty.  Raise
69       Invalid_argument Weak.set if n is not in the range 0 to Weak.length a -
70       1 .
71
72
73
74       val get : 'a t -> int -> 'a option
75
76
77       Weak.get  ar  n  returns  None  if the n th cell of ar is empty, Some x
78       (where x is the value) if it is full.  Raise Invalid_argument  Weak.get
79       if n is not in the range 0 to Weak.length a - 1 .
80
81
82
83       val get_copy : 'a t -> int -> 'a option
84
85
86       Weak.get_copy ar n returns None if the n th cell of ar is empty, Some x
87       (where x is a (shallow) copy of the value) if it is full.  In  addition
88       to pitfalls with mutable values, the interesting difference with get is
89       that get_copy does not prevent the  incremental  GC  from  erasing  the
90       value  in  its current cycle ( get may delay the erasure to the next GC
91       cycle).  Raise Invalid_argument Weak.get if n is not in the range 0  to
92       Weak.length a - 1 .
93
94       If the element is a custom block it is not copied.
95
96
97
98       val check : 'a t -> int -> bool
99
100
101       Weak.check  ar  n returns true if the n th cell of ar is full, false if
102       it is empty.  Note that even if Weak.check ar n returns true , a subse‐
103       quent Weak.get ar n can return None .
104
105
106
107       val fill : 'a t -> int -> int -> 'a option -> unit
108
109
110       Weak.fill ar ofs len el sets to el all pointers of ar from ofs to ofs +
111       len - 1 .  Raise Invalid_argument Weak.fill if ofs and len do not  des‐
112       ignate a valid subarray of a .
113
114
115
116       val blit : 'a t -> int -> 'a t -> int -> int -> unit
117
118
119       Weak.blit  ar1  off1  ar2  off2  len  copies len weak pointers from ar1
120       (starting at off1 ) to ar2 (starting at off2  ).   It  works  correctly
121       even  if ar1 and ar2 are the same.  Raise Invalid_argument Weak.blit if
122       off1 and len do not designate a valid subarray of ar1 , or if off2  and
123       len do not designate a valid subarray of ar2 .
124
125
126
127
128       === Weak hash sets ===
129
130
131       === A weak hash set is a hashed set of values. Each value may magically
132       disappear from the set when it is not used by the rest of  the  program
133       any more. This is normally used to share data structures without induc‐
134       ing memory leaks.   Weak  hash  sets  are  defined  on  values  from  a
135       Hashtbl.HashedType  module;  the  equal  relation and hash function are
136       taken from that module. We will say that v is an instance of x if equal
137       x v is true.  The equal relation must be able to work on a shallow copy
138       of the values and give the same result as with the  values  themselves.
139       ===
140
141
142       module type S = sig end
143
144
145       The output signature of the functor Weak.Make .
146
147
148       module Make : functor (H : Hashtbl.HashedType) -> sig end
149
150
151       Functor  building  an  implementation  of  the weak hash set structure.
152       H.equal can't be the physical equality, since only  shallow  copies  of
153       the elements in the set are given to it.
154
155
156
157
158
159OCamldoc                          2019-02-02                           Weak(3)