Ubuntu Manpage: Weak - Arrays of weak pointers and hash sets of weak pointers.

name
module
documentation

NAME

       Weak - Arrays of weak pointers and hash sets of weak pointers.

Module

       Module   Weak

Documentation

       Module Weak
        : sig end

       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 output_value nor the functions of the Marshal module.

       val create : int -> 'a t

       Weak.create n returns a new weak array of length n .   All  the  pointers  are  initially  empty.   Raise
       Invalid_argument if n is not comprised between zero and Obj.Ephemeron.max_ephe_length (limits included).

       val length : 'a t -> int

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

       val set : 'a t -> int -> 'a option -> unit

       Weak.set  ar  n (Some el) sets the n th cell of ar to be a (full) pointer to el ; Weak.set ar n None sets
       the n th cell of ar to empty.  Raise Invalid_argument Weak.set if n is not in the range 0 to  Weak.length
       a - 1 .

       val get : 'a t -> int -> 'a option

       Weak.get  ar n returns None if the n th cell of ar is empty, Some x (where x is the value) if it is full.
       Raise Invalid_argument Weak.get if n is not in the range 0 to Weak.length a - 1 .

       val get_copy : 'a t -> int -> 'a option

       Weak.get_copy ar n returns None if the n th 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).  Raise Invalid_argument Weak.get if n is not in the
       range 0 to Weak.length a - 1 .

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

       val check : 'a t -> int -> bool

       Weak.check ar n returns true if the n th 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 .

       val fill : 'a t -> int -> int -> 'a option -> unit

       Weak.fill ar ofs len el sets to el all pointers of ar from ofs to ofs + len - 1 .  Raise Invalid_argument
       Weak.fill if ofs and len do not designate a valid subarray of a .

       val blit : 'a t -> int -> 'a t -> int -> int -> unit

       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.  Raise Invalid_argument Weak.blit 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 .

   Weak hash sets
       A  weak  hash  set is a hashed set of values.  Each value may magically disappear from the set when it is
       not used by the rest of the program any more.  This is normally used to  share  data  structures  without
       inducing  memory leaks.  Weak hash sets are defined on values from a Hashtbl.HashedType module; the equal
       relation and hash function are taken from that module.  We will say that v is an instance of x if equal x
       v is true .

       The  equal relation must be able to work on a shallow copy of the values and give the same result as with
       the values themselves.

       module type S = sig end

       The output signature of the functor Weak.Make .

       module Make : functor (H : Hashtbl.HashedType) -> sig end

       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.