Weak(3o)							   OCaml library							  Weak(3o)

NAME

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

Module
       Module	Weak

Documentation
       Module Weak
	: sig end

       Arrays of weak pointers and hash tables 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 after the weak pointers are erased.

       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 Pervasives.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  negative	or
       greater than Sys.max_array_length -1 .

       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 addi-
       tion 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 .

       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 sub-
       sequent 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 tables ===

       === A weak hash table 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 tables 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 table structure.

OCamldoc							    2012-06-26								  Weak(3o)