extensions/ocsipersist.mli

   1 (* Ocsigen
   2  * http://www.ocsigen.org
   3  * Module ocsipersist.mli
   4  * Copyright (C) 2007 Vincent Balat - Gabriel Kerneis - CNRS - Université Paris Diderot
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU Lesser General Public License as published by
   8  * the Free Software Foundation, with linking exception;
   9  * either version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  19  *)
  20
  21
  22 (** Persistent data on hard disk. *)
  23
  24 (**
  25    There are currently two implementations of this module,
  26    one using a DBM database, and the other using SQLITE.
  27    Link the one your want with your program.
  28  *)
  29
  30
  31 (*****************************************************************************)
  32 (** {2 Persistent references} *)
  33 (** When launching the program, if the value exists on hard disk,
  34     it is loaded, otherwise it is initialised to the default value *)
  35
  36 (** Type of persistent data *)
  37 type 'a t
  38
  39 (** Data are divided into stores.
  40    Create one store for your project, where you will save all your data. *)
  41 type store
  42
  43 (** Open a store (and create it if it does not exist)  *)
  44 val open_store : string -> store
  45
  46 val make_persistent :
  47     store:store -> name:string -> default:'a -> 'a t Lwt.t
  48 (** [make_persistent store name default] find a persistent value
  49     named [name] in store [store]
  50     from database, or create it with the default value [default] if it
  51     does not exist. *)
  52
  53 val make_persistent_lazy :
  54     store:store -> name:string -> default:(unit -> 'a) -> 'a t Lwt.t
  55 (** Same as make_persistent but the default value is evaluated only
  56     if needed
  57 *)
  58
  59 val get : 'a t -> 'a Lwt.t
  60 (** [get pv] gives the value of [pv] *)
  61
  62 val set : 'a t -> 'a -> unit Lwt.t
  63 (** [set pv value] sets a persistent value [pv] to [value] *)
  64
  65 (*****************************************************************************)
  66 (** {2 Persistent tables} *)
  67
  68 (** Type of persistent table *)
  69 type 'value table
  70
  71 (** returns the name of the table  *)
  72 val table_name : 'value table -> string Lwt.t
  73
  74 (** Open a table (and create it if it does not exist)  *)
  75 val open_table : string -> 'value table
  76
  77 val find : 'value table -> string -> 'value Lwt.t
  78 (** [find table key] gives the value associated to [key].
  79   Fails with [Not_found] if not found. *)
  80
  81 val add : 'value table -> string -> 'value -> unit Lwt.t
  82 (** [add table key value] associates [value] to [key].
  83    If the database already contains data associated with [key],
  84    that data is discarded and silently replaced by the new data.
  85  *)
  86
  87 val replace_if_exists : 'value table -> string -> 'value -> unit Lwt.t
  88 (** [replace_if_exists table key value]
  89    associates [value] to [key] only if [key] is already bound.
  90    If the database does not contain any data associated with [key],
  91    fails with [Not_found].
  92  *)
  93
  94 val remove : 'value table -> string -> unit Lwt.t
  95 (** [remove table key] removes the entry in the table if it exists *)
  96
  97 val length : 'value table -> int Lwt.t
  98 (** Size of a table. *)
  99
 100 val iter_step : (string -> 'a -> unit Lwt.t) -> 'a table -> unit Lwt.t
 101 (** Important warning: this iterator may not iter on all data of the table
 102     if another thread is modifying it in the same time. Nonetheless, it should
 103     not miss more than a very few data from time to time, except if the table
 104     is very old (at least 9 223 372 036 854 775 807 insertions).
 105  *)
 106
 107 val iter_table : (string -> 'a -> unit Lwt.t) -> 'a table -> unit Lwt.t
 108 (** Legacy interface for iter_step *)
 109
 110 val fold_step : (string -> 'a -> 'b -> 'b Lwt.t) ->
 111   'a table -> 'b -> 'b Lwt.t
 112 (** Important warning: this iterator may not iter on all data of the table
 113     if another thread is modifying it in the same time. Nonetheless, it should
 114     not miss more than a very few data from time to time, except if the table
 115     is very old (at least 9 223 372 036 854 775 807 insertions).
 116  *)
 117
 118 val fold_table : (string -> 'a -> 'b -> 'b Lwt.t) ->
 119   'a table -> 'b -> 'b Lwt.t
 120 (** Legacy interface for fold_step *)
 121
 122 (**/**)
 123 val iter_block : (string -> 'a -> unit) -> 'a table -> unit Lwt.t
 124 (** MAJOR WARNING: Unlike iter_step, this iterator won't miss any
 125     entry and will run in one shot. It is therefore more efficient, BUT:
 126     it will lock the WHOLE database during its execution,
 127     thus preventing ANYBODY from accessing it (including the function f
 128     which is iterated).
 129     As a consequence : you MUST NOT use any function from ocsipersist in f,
 130     otherwise you would lock yourself and everybody else ! Be VERY cautious.
 131 *)