1 (** Mark objects as 'ancient' so they are taken out of the OCaml heap.
2 * $Id: ancient.mli,v 1.7 2006-10-09 14:43:00 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 val is_ancient : 'a -> bool
34 (** [is_ancient ptr] returns true if [ptr] is an object on the ancient
38 (** {6 Shared memory mappings} *)
41 (** Memory descriptor handle. *)
43 val attach : Unix.file_descr -> nativeint -> md
44 (** [attach fd baseaddr] attaches to a new or existing file
45 * which may contain shared objects.
47 * Initially [fd] should be a read/writable, zero-length file
48 * (for example you could create this using {!Unix.openfile} and
49 * passing the flags [O_RDWR], [O_TRUNC], [O_CREAT]).
50 * One or more objects can then be shared in this file
51 * using {!Unix.share}.
53 * For new files, [baseaddr] specifies the virtual address to
54 * map the file. Specifying [Nativeint.zero] ([0n]) here lets [mmap(2)]
55 * choose this, but on some platforms (notably Linux/AMD64)
56 * [mmap] chooses very unwisely, tending to map the memory
57 * just before [libc] with hardly any headroom to grow. If
58 * you encounter this sort of problem (usually a segfault or
59 * illegal instruction inside libc), then look at [/proc/PID/maps]
60 * and choose a more suitable address.
62 * If the file was created previously, then the [baseaddr] is
63 * ignored. The underlying [mmalloc] library will map the
64 * file in at the same place as before.
67 val detach : md -> unit
68 (** [detach md] detaches from an existing file, and closes it.
71 val share : md -> int -> 'a -> 'a ancient
72 (** [share md key obj] does the same as {!Ancient.mark} except
73 * that instead of copying the object into local memory, it
74 * writes it into memory which is backed by the attached file.
76 * Shared mappings created this way may be shared between
77 * other OCaml processes which can access the underlying
78 * file. See {!Ancient.attach}, {!Ancient.detach}.
80 * More than one object can be stored in a file. They are
81 * indexed using integers in the range [0..max_key] (the limit
82 * is hard-coded in [mmalloc/mmprivate.h]). The [key] parameter
83 * controls which object is written/overwritten by [share].
84 * If you do not wish to use this feature, just pass [0]
87 * Do not call {!Ancient.delete} on a mapping created like this.
88 * Instead, call {!Ancient.detach} and, if necessary, delete the
91 * Caution when sharing files/objects between processes:
92 * The underlying [mmalloc] library does not do any sort of
93 * locking, so all calls to [share] must ensure that they have
94 * exclusive access to the underlying file while in progress.
95 * (Other processes should not even call {!Ancient.get} while
96 * this is happening, but it seems safe to be just reading an
97 * ancient object from the file).
100 val get : md -> int -> 'a ancient
101 (** [get md key] returns the object indexed by [key] in the
104 * The key is in the range [0..max_key] (the limit is hard-coded in
105 * [mmalloc/mmprivate.h]). If you do not wish to use this feature,
106 * just pass [0] as the key when sharing / getting.
108 * You need to annotate the returned object with the correct
109 * type. As with the Marshal module, there is no type checking,
110 * and setting the wrong type will likely cause a segfault
111 * or undefined behaviour. Note that the returned object has
112 * type [sometype ancient], not just [sometype].
114 * @raises [Not_found] if no object is associated with the key.
119 (** {6 Additional information} *)
122 i_size : int; (** Allocated size, bytes. *)
124 (** Extra information fields. See {!Ancient.mark_info} and
125 * {!Ancient.share_info}.
128 val mark_info : 'a -> 'a ancient * info
129 (** Same as {!Ancient.mark}, but also returns some extra information. *)
131 val share_info : md -> int -> 'a -> 'a ancient * info
132 (** Same as {!Ancient.share}, but also returns some extra information. *)