Merge pull request #34 from hannesm/add-allocate

RW: add a new function "allocate" which reserves some space for a new file

mirage-kv.opam

@@ -19,6 +19,7 @@ depends: [
   "fmt" {>= "0.8.7"}
   "lwt" {>= "4.0.0"}
   "optint" {>= "0.2.0"}
+  "ptime" {>= "1.0.0"}
   "alcotest" {with-test}
 ]
 synopsis: "MirageOS signatures for key/value devices"

src/dune

@@ -1,4 +1,4 @@
 (library
   (name        mirage_kv)
   (public_name mirage-kv)
-  (libraries   fmt optint lwt))
+  (libraries   fmt optint lwt ptime))

src/mirage_kv.ml

@@ -68,24 +68,26 @@ module type RO = sig
   val get: t -> key -> (string, error) result Lwt.t
   val get_partial: t -> key -> offset:Optint.Int63.t -> length:int -> (string, error) result Lwt.t
   val list: t -> key -> ((key * [`Value | `Dictionary]) list, error) result Lwt.t
-  val last_modified: t -> key -> (int * int64, error) result Lwt.t
+  val last_modified: t -> key -> (Ptime.t, error) result Lwt.t
   val digest: t -> key -> (string, error) result Lwt.t
   val size: t -> key -> (Optint.Int63.t, error) result Lwt.t
 end
 
-type write_error = [ error | `No_space | `Rename_source_prefix of Key.t * Key.t ]
+type write_error = [ error | `No_space | `Rename_source_prefix of key * key | `Already_present of key ]
 
 let pp_write_error ppf = function
   | #error as e -> pp_error ppf e
   | `No_space   -> Fmt.string ppf "No space left on device"
   | `Rename_source_prefix (src, dest) ->
     Fmt.pf ppf "Rename: source %a is prefix of destination %a"
       Key.pp src Key.pp dest
+  | `Already_present k -> Fmt.pf ppf "Key %a is already present" Key.pp k
 
 module type RW = sig
   include RO
   type nonrec write_error = private [> write_error]
   val pp_write_error: write_error Fmt.t
+  val allocate : t -> key -> ?last_modified:Ptime.t -> Optint.Int63.t -> (unit, write_error) result Lwt.t
   val set: t -> key -> string -> (unit, write_error) result Lwt.t
   val set_partial: t -> key -> offset:Optint.Int63.t -> string -> (unit, write_error) result Lwt.t
   val remove: t -> key -> (unit, write_error) result Lwt.t

src/mirage_kv.mli

@@ -152,15 +152,10 @@ module type RO = sig
       The result is [Error (`Dictionary_expected k)] if [k] refers to a
      value in [t]. *)
 
-  val last_modified: t -> key -> (int * int64, error) result Lwt.t
+  val last_modified: t -> key -> (Ptime.t, error) result Lwt.t
   (** [last_modified t k] is the last time the value bound to [k] in
      [t] has been modified.
 
-      The modification time [(d, ps)] is a span for the signed POSIX
-     picosecond span [d] * 86_400e12 + [ps]. [d] is a signed number of
-     POSIX days and [ps] a number of picoseconds in the range
-     \[[0];[86_399_999_999_999_999L]\].
-
       When the value bound to [k] is a dictionary, the modification
      time is the latest modification of all entries in that
      dictionary. This behaviour is only one level deep and not recursive. *)
@@ -182,6 +177,7 @@ type write_error = [
   | error
   | `No_space (** No space left on the device. *)
   | `Rename_source_prefix of key * key (** The source is a prefix of destination in rename. *)
+  | `Already_present of key (** The key is already present. *)
 ]
 
 val pp_write_error: write_error Fmt.t
@@ -203,6 +199,15 @@ module type RW = sig
   val pp_write_error: write_error Fmt.t
   (** The pretty-printer for [pp_write_error]. *)
 
+  val allocate : t -> key -> ?last_modified:Ptime.t -> Optint.Int63.t ->
+    (unit, write_error) result Lwt.t
+  (** [allocate t key ~last_modified size] allocates space for [key] in [t] with
+      the provided [size] and [last_modified]. This is useful for e.g.
+      append-only backends that could still use {!set_partial}. The data will
+      be filled with 0. If [key] already exists, [Error (`Already_present key)]
+      is returned. If there's not enough space, [Error `No_space] is returned.
+  *)
+
   val set: t -> key -> string -> (unit, write_error) result Lwt.t
   (** [set t k v] replaces the binding [k -> v] in [t].