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
31       finalisation functions are run before the  weak  pointers  are  erased,
32       because  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.   Raise  Invalid_argument  if n is not comprised
53       between zero and Obj.Ephemeron.max_ephe_length (limits included).
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
79       "Weak.get" 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
92       to 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
112       designate 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"
122       if off1 and len do not designate a valid subarray of ar1 , or  if  off2
123       and len do not designate a valid subarray of ar2 .
124
125
126
127
128   Weak hash sets
129       A  weak  hash  set is a hashed set of values.  Each value may magically
130       disappear from the set when it is not used by the rest of  the  program
131       any  more.   This  is  normally  used  to share data structures without
132       inducing memory leaks.  Weak hash sets are defined  on  values  from  a
133       Hashtbl.HashedType  module;  the  equal  relation and hash function are
134       taken from that module.  We will say that v is  an  instance  of  x  if
135       equal x v is true .
136
137       The equal relation must be able to work on a shallow copy of the values
138       and give the same result as with the values themselves.
139
140       module type S = sig end
141
142
143       The output signature of the functor Weak.Make .
144
145
146       module Make : functor (H : Hashtbl.HashedType) -> sig end
147
148
149       Functor building an implementation of  the  weak  hash  set  structure.
150       H.equal  can't  be  the physical equality, since only shallow copies of
151       the elements in the set are given to it.
152
153
154
155
156
157OCamldoc                          2020-02-27                           Weak(3)