Implemented share/attach/detach; not tested yet - just checking in

[ocaml-ancient.git] / ancient.mli

diff --git a/ancient.mli b/ancient.mli
index 9f574db..8740706 100644 (file)
--- a/ancient.mli
+++ b/ancient.mli
@@ -1,5 +1,5 @@
 (** Mark objects as 'ancient' so they are taken out of the OCaml heap.
-  * $Id: ancient.mli,v 1.1 2006-09-27 12:07:07 rich Exp $
+  * $Id: ancient.mli,v 1.2 2006-09-27 15:36:18 rich Exp $
   *)
 
 type 'a ancient
@@ -29,3 +29,42 @@ val delete : 'a ancient -> unit
     *
     * Forgetting to delete an ancient object results in a memory leak.
     *)
+
+(** {6 Shared memory mappings} *)
+
+val share : Unix.file_descr -> 'a -> 'a ancient
+  (** [share fd obj] does the same as {!Ancient.mark} except
+    * that instead of copying the object into local memory, it
+    * writes it into memory which is backed by the file [fd].
+    * [fd] should be a writable, zero-length file (see
+    * {!Unix.openfile}).
+    *
+    * Shared mappings created this way may be shared between
+    * other OCaml processes which can access the underlying
+    * file.  See {!Ancient.attach}, {!Ancient.detach}.
+    *
+    * Do not call {!Ancient.delete} on a mapping created like this.
+    * Instead, call {!Ancient.detach} and, if necessary, delete the
+    * underlying file.
+    *)
+
+val attach : Unix.file_descr -> 'a ancient
+  (** [attach fd] takes an existing file which was created by
+    * {!Ancient.share} and accesses the object contained
+    * in it.
+    *
+    * You need to force the return type to be the correct type
+    * for the object contained in the file.  As with Marshal,
+    * the type is not checked, and if it is wrong a segfault
+    * is likely.
+    *
+    * Do not call {!Ancient.delete} on a mapping created like this.
+    * Instead, call {!Ancient.detach} and, if necessary, delete the
+    * underlying file.
+    *)
+
+val detach : 'a ancient -> unit
+  (** [detach obj] detaches from a shared mapping.
+    *
+    * @raise [Invalid_argument "detached"] if the object has been detached.
+    *)