Module Stdlib.Weak

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 the Marshal module.

Weak.create n returns a new weak array of length n. All the pointers are initially empty.

• raises Invalid_argument

  if n is not comprised between zero and Obj.Ephemeron.max_ephe_length (limits included).

Weak.length ar returns the length (number of elements) of ar.

Weak.set ar n (Some el) sets the nth cell of ar to be a (full) pointer to el; Weak.set ar n None sets the nth cell of ar to empty.

• raises Invalid_argument

  if n is not in the range 0 to Weak.length a - 1.

Weak.get ar n returns None if the nth cell of ar is empty, Some x (where x is the value) if it is full.

• raises Invalid_argument

  if n is not in the range 0 to Weak.length a - 1.

Weak.get_copy ar n returns None if the nth cell of ar is empty, Some x (where x is a (shallow) copy of the value) if it is full. In addition to pitfalls with mutable values, the interesting difference with get is that get_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).

• raises Invalid_argument

  if n is not in the range 0 to Weak.length a - 1.

  If the element is a custom block it is not copied.

Weak.check ar n returns true if the nth cell of ar is full, false if it is empty. Note that even if Weak.check ar n returns true, a subsequent Weak.get ar n can return None.

Weak.fill ar ofs len el sets to el all pointers of ar from ofs to ofs + len - 1.

• raises Invalid_argument

  if ofs and len do not designate a valid subarray of a.

Weak.blit ar1 off1 ar2 off2 len copies len weak pointers from ar1 (starting at off1) to ar2 (starting at off2). It works correctly even if ar1 and ar2 are the same.

• raises Invalid_argument

  if off1 and len do not designate a valid subarray of ar1, or if off2 and len do not designate a valid subarray of ar2.

The output signature of the functor Weak.Make.

Functor building an implementation of the weak hash set structure. H.equal can't be the physical equality, since only shallow copies of the elements in the set are given to it.