1 (** Mark objects as 'ancient' so they are taken out of the OCaml heap.
2 * $Id: ancient.mli,v 1.3 2006-09-27 18:39:44 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} *)
36 (** Memory descriptor handle. *)
38 val attach : Unix.file_descr -> md
39 (** [attach fd] attaches to a new or existing file which may contain
42 * Initially [fd] should be a read/writable, zero-length file
43 * (see {!Unix.openfile}). One or more objects can then be
44 * shared in this file using {!Unix.share}.
47 val detach : md -> unit
48 (** [detach md] detaches from an existing file, and closes it.
51 val share : md -> int -> 'a -> 'a ancient
52 (** [share md key obj] does the same as {!Ancient.mark} except
53 * that instead of copying the object into local memory, it
54 * writes it into memory which is backed by the attached file.
56 * Shared mappings created this way may be shared between
57 * other OCaml processes which can access the underlying
58 * file. See {!Ancient.attach}, {!Ancient.detach}.
60 * More than one object can be stored in a file. They are
61 * indexed using integers in the range [0..1023] (the limit
62 * is hard-coded in [mmalloc/mmprivate.h]). The [key] parameter
63 * controls which object is written/overwritten by [share].
64 * If you do not wish to use this feature, just pass [0]
67 * Do not call {!Ancient.delete} on a mapping created like this.
68 * Instead, call {!Ancient.detach} and, if necessary, delete the
71 * Caution when sharing files/objects between processes:
72 * The underlying [mmalloc] library does not do any sort of
73 * locking, so all calls to [share] must ensure that they have
74 * exclusive access to the underlying file while in progress.
77 val get : md -> int -> 'a ancient
78 (** [get md key] returns the object indexed by [key] in the
81 * The key is in the range [0..1023] (the limit is hard-coded in
82 * [mmalloc/mmprivate.h]).
84 * You need to annotate the returned object with the correct
85 * type. As with the Marshal module, there is no type checking,
86 * and setting the wrong type will likely cause a segfault
87 * or undefined behaviour.
89 * @raises [Not_found] if no object is associated with the key.