1Weak(3) OCamldoc Weak(3)
2
6 Weak - Arrays of weak pointers and hash sets of weak pointers.
7
9 Module Weak
10
12 Module Weak
13 : sig end
14 Arrays of weak pointers and hash sets of weak pointers.
17 === Low-level functions ===
25 type 'a t
28 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 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 Notes:
39 -Integers are not allocated and cannot be stored in weak arrays.
41 -Weak arrays cannot be marshaled using Pervasives.output_value nor the
43 functions of the Marshal module.
44 val create : int -> 'a t
49 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 val length : 'a t -> int
58 Weak.length ar returns the length (number of elements) of ar .
61 val set : 'a t -> int -> 'a option -> unit
65 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 val get : 'a t -> int -> 'a option
75 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 val get_copy : 'a t -> int -> 'a option
84 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 If the element is a custom block it is not copied.
95 val check : 'a t -> int -> bool
99 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 val fill : 'a t -> int -> int -> 'a option -> unit
108 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 val blit : 'a t -> int -> 'a t -> int -> int -> unit
117 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 === Weak hash sets ===
129 === 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 module type S = sig end
143 The output signature of the functor Weak.Make .
146 module Make : functor (H : Hashtbl.HashedType) -> sig end
149 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.
1542018-04-14 source: Weak(3)