1 (** Mark objects as 'ancient' so they are taken out of the OCaml heap.
2 * $Id: ancient.mli,v 1.2 2006-09-27 15:36:18 rich Exp $
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
12 * The copy of [obj] accessed through the proxy MUST NOT be mutated.
14 * If [obj] represents a large object, then it is a good
15 * idea to call {!Gc.compact} after marking to recover the
19 val follow : 'a ancient -> 'a
20 (** Follow proxy link to out of heap object.
22 * @raise [Invalid_argument "deleted"] if the object has been deleted.
25 val delete : 'a ancient -> unit
26 (** [delete obj] deletes ancient object [obj].
28 * @raise [Invalid_argument "deleted"] if the object has been deleted.
30 * Forgetting to delete an ancient object results in a memory leak.
33 (** {6 Shared memory mappings} *)
35 val share : Unix.file_descr -> 'a -> 'a ancient
36 (** [share fd obj] does the same as {!Ancient.mark} except
37 * that instead of copying the object into local memory, it
38 * writes it into memory which is backed by the file [fd].
39 * [fd] should be a writable, zero-length file (see
42 * Shared mappings created this way may be shared between
43 * other OCaml processes which can access the underlying
44 * file. See {!Ancient.attach}, {!Ancient.detach}.
46 * Do not call {!Ancient.delete} on a mapping created like this.
47 * Instead, call {!Ancient.detach} and, if necessary, delete the
51 val attach : Unix.file_descr -> 'a ancient
52 (** [attach fd] takes an existing file which was created by
53 * {!Ancient.share} and accesses the object contained
56 * You need to force the return type to be the correct type
57 * for the object contained in the file. As with Marshal,
58 * the type is not checked, and if it is wrong a segfault
61 * Do not call {!Ancient.delete} on a mapping created like this.
62 * Instead, call {!Ancient.detach} and, if necessary, delete the
66 val detach : 'a ancient -> unit
67 (** [detach obj] detaches from a shared mapping.
69 * @raise [Invalid_argument "detached"] if the object has been detached.