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