ancient.mli

   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 $
   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 (** {6 Shared memory mappings} *)
  34
  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
  40     * {!Unix.openfile}).
  41     *
  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}.
  45     *
  46     * Do not call {!Ancient.delete} on a mapping created like this.
  47     * Instead, call {!Ancient.detach} and, if necessary, delete the
  48     * underlying file.
  49     *)
  50
  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
  54     * in it.
  55     *
  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
  59     * is likely.
  60     *
  61     * Do not call {!Ancient.delete} on a mapping created like this.
  62     * Instead, call {!Ancient.detach} and, if necessary, delete the
  63     * underlying file.
  64     *)
  65
  66 val detach : 'a ancient -> unit
  67   (** [detach obj] detaches from a shared mapping.
  68     *
  69     * @raise [Invalid_argument "detached"] if the object has been detached.
  70     *)