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