Module Import0.Weak
Arrays of weak pointers and hash sets of weak pointers.
Low-level functions
type 'a t
The type of arrays of weak pointers (weak arrays). A weak pointer is a value that the garbage collector may erase whenever the value is not used any more (through normal pointers) by the program. Note that finalisation functions are run before the weak pointers are erased, because the finalisation functions can make values alive again (before 4.03 the finalisation functions were run after).
A weak pointer is said to be full if it points to a value, empty if the value was erased by the GC.
Notes:
- Integers are not allocated and cannot be stored in weak arrays.
- Weak arrays cannot be marshaled using
Stdlib.output_value
nor the functions of theMarshal
module.
val create : int -> 'a t
Weak.create n
returns a new weak array of lengthn
. All the pointers are initially empty. RaiseInvalid_argument
ifn
is not comprised between zero andObj.Ephemeron.max_ephe_length
(limits included).
val length : 'a t -> int
Weak.length ar
returns the length (number of elements) ofar
.
val set : 'a t -> int -> 'a option -> unit
Weak.set ar n (Some el)
sets then
th cell ofar
to be a (full) pointer toel
;Weak.set ar n None
sets then
th cell ofar
to empty. RaiseInvalid_argument "Weak.set"
ifn
is not in the range 0 toWeak.length
a - 1
.
val get : 'a t -> int -> 'a option
Weak.get ar n
returns None if then
th cell ofar
is empty,Some x
(wherex
is the value) if it is full. RaiseInvalid_argument "Weak.get"
ifn
is not in the range 0 toWeak.length
a - 1
.
val get_copy : 'a t -> int -> 'a option
Weak.get_copy ar n
returns None if then
th cell ofar
is empty,Some x
(wherex
is a (shallow) copy of the value) if it is full. In addition to pitfalls with mutable values, the interesting difference withget
is thatget_copy
does not prevent the incremental GC from erasing the value in its current cycle (get
may delay the erasure to the next GC cycle). RaiseInvalid_argument "Weak.get"
ifn
is not in the range 0 toWeak.length
a - 1
.If the element is a custom block it is not copied.
val check : 'a t -> int -> bool
Weak.check ar n
returnstrue
if then
th cell ofar
is full,false
if it is empty. Note that even ifWeak.check ar n
returnstrue
, a subsequentWeak.get
ar n
can returnNone
.
val fill : 'a t -> int -> int -> 'a option -> unit
Weak.fill ar ofs len el
sets toel
all pointers ofar
fromofs
toofs + len - 1
. RaiseInvalid_argument "Weak.fill"
ifofs
andlen
do not designate a valid subarray ofa
.
val blit : 'a t -> int -> 'a t -> int -> int -> unit
Weak.blit ar1 off1 ar2 off2 len
copieslen
weak pointers fromar1
(starting atoff1
) toar2
(starting atoff2
). It works correctly even ifar1
andar2
are the same. RaiseInvalid_argument "Weak.blit"
ifoff1
andlen
do not designate a valid subarray ofar1
, or ifoff2
andlen
do not designate a valid subarray ofar2
.