'Ancient' generation in garbage collector.
[ocaml-ancient.git] / ancient.mli
1 (** Mark objects as 'ancient' so they are taken out of the OCaml heap.
2   * $Id: ancient.mli,v 1.1 2006-09-27 12:07:07 rich Exp $
3   *)
4
5 type 'a ancient
6
7 val mark : 'a -> 'a ancient
8   (** [mark obj] copies [obj] and all objects referenced
9     * by [obj] out of the OCaml heap.  It returns the proxy
10     * for [obj].
11     *
12     * The copy of [obj] accessed through the proxy MUST NOT be mutated.
13     *
14     * If [obj] represents a large object, then it is a good
15     * idea to call {!Gc.compact} after marking to recover the
16     * OCaml heap memory.
17     *)
18
19 val follow : 'a ancient -> 'a
20   (** Follow proxy link to out of heap object.
21     *
22     * @raise [Invalid_argument "deleted"] if the object has been deleted.
23     *)
24
25 val delete : 'a ancient -> unit
26   (** [delete obj] deletes ancient object [obj].
27     *
28     * @raise [Invalid_argument "deleted"] if the object has been deleted.
29     *
30     * Forgetting to delete an ancient object results in a memory leak.
31     *)