package irmin-pack

  1. Overview
  2. Docs
package irmin-pack
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Source file lower_intf.ml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
(*
 * Copyright (c) 2023 Tarides <contact@tarides.com>
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *)

open! Import

type volume_identifier = string [@@deriving irmin]

module type Volume = sig
  module Io : Io.S
  module Errs : Io_errors.S
  module Sparse : Sparse_file.S

  type t

  type open_error =
    [ Io.open_error
    | `Closed
    | `Double_close
    | `Corrupted_control_file of string
    | `Unknown_major_pack_version of string ]

  val v : string -> (t, [> open_error ]) result
  (** [v path] loads the volume at [path] in read-only. *)

  val path : t -> string
  (** [path t] is the directory that contains the volume. *)

  val is_empty : t -> bool
  (** [is_empty t] returns whether [t] is empty or not. *)

  val control : t -> Control_file.Payload.Volume.Latest.t option
  (** [control t] returns the control file payload for the volume. *)

  val identifier : t -> volume_identifier
  (** [identifier t] is a unique idendifier for the volume. *)
end

module type S = sig
  module Io : Io.S
  module Errs : Io_errors.S
  module Volume : Volume with module Io = Io

  type t
  type open_error = [ Volume.open_error | `Volume_missing of string ]
  type close_error = [ | Io.close_error ]
  type nonrec volume_identifier = volume_identifier [@@deriving irmin]

  type add_error =
    [ open_error
    | `Ro_not_allowed
    | `Multiple_empty_volumes
    | `File_exists of string
    | `Invalid_parent_directory ]

  val v :
    readonly:bool -> volume_num:int -> string -> (t, [> open_error ]) result
  (** [v ~readonly ~volume_num lower_root] loads all volumes located in the
      directory [lower_root].

      [volume_num] is the number of volumes that are expected in [lower_root]. 0
      is valid for an empty lower.

      [Error `Volume_missing path] is returned if an expected volume is not on
      disk, with the path to first volume that is missing. This can happen if
      [volume_num] is larger than the number of volumes on disk, or if one of
      the volume directories has been renamed accidentally.

      If [readonly] is false, no write operations are allowed. *)

  val reload : volume_num:int -> t -> (unit, [> open_error ]) result
  (** [reload ~volume_num t] reloads volumes located in the root directory of
      [t], using [volume_num] as the expected number of volumes. *)

  val close : t -> (unit, [> close_error ]) result
  (** [close t] closes all resources opened by [t]. *)

  val volume_num : t -> int
  (** [volume_num t] returns the number of volumes in the lower [t]. *)

  val add_volume : t -> (Volume.t, [> add_error ]) result
  (** [add_volume t] adds a new empty volume to [t].

      If there is already an empty volume, [Error `Multiple_empty_volumes] is
      returned. Only one empty volume is allowed.

      If [t] is read-only, [Error `Ro_not_allowed] is returned. *)

  val find_volume : off:int63 -> t -> Volume.t option
  (** [find_volume ~off t] returns the {!Volume} that contains [off]. *)

  val read_exn :
    off:int63 ->
    len:int ->
    ?volume:volume_identifier ->
    t ->
    bytes ->
    volume_identifier
  (** [read_exn ~off ~len ~volume t b] will read [len] bytes from a global [off]
      located in the volume with identifier [volume]. The volume identifier of
      the volume where the read occurs is returned.

      If [volume] is not provided, {!find_volume} will be used to attempt to
      locate the correct volume for the read. *)

  val set_readonly : t -> bool -> unit
  (** [set_readonly t flag] changes the writing permission of the lower layer
      (where [true] is read only). This should only be called by the GC worker
      to temporarily allow RW before calling {!archive_seq_exn}. *)

  val archive_seq_exn :
    upper_root:string ->
    generation:int ->
    to_archive:(int63 * string Seq.t) list ->
    t ->
    volume_identifier
  (** [archive_seq ~upper_root ~generation ~to_archive t] is called by the GC
      worker during the creation of the new [generation] to archive [to_archive]
      in the lower layer and returns the identifier of the volume where data was
      appended.

      It is the only write operation allowed on the lower layer, and it makes no
      observable change as the control file is left untouched : instead new
      changes are written to volume.gen.control, which is swapped during GC
      finalization. *)

  val read_range_exn :
    off:int63 ->
    min_len:int ->
    max_len:int ->
    ?volume:volume_identifier ->
    t ->
    bytes ->
    int * volume_identifier
  (** Same as [read_exn] but will read at least [min_len] bytes and at most
      [max_len]. Returns the read length and the volume identifier from which
      the data was fetched. *)

  type create_error :=
    [ open_error | close_error | add_error | `Sys_error of string ]

  val create_from :
    src:string ->
    dead_header_size:int ->
    size:Int63.t ->
    string ->
    (unit, [> create_error ]) result
  (** [create_from ~src ~dead_header_size ~size lower_root] initializes the
      first lower volume in the directory [lower_root] by moving the suffix file
      [src] with end offset [size]. *)

  val swap :
    volume:volume_identifier ->
    generation:int ->
    volume_num:int ->
    t ->
    ( unit,
      [> `Volume_not_found of string | `Sys_error of string | open_error ] )
    result
  (** [swap ~volume ~generation ~volume_num t] will rename a new volume control
      file in [volume] for [generation] of GC and then reload the lower with
      [volume_num] volumes. *)

  val cleanup : generation:int -> t -> (unit, [> `Sys_error of string ]) result
  (** [cleanup ~generation t] will attempt to cleanup the appendable volume if a
      GC crash has occurred. *)
end

module type Sigs = sig
  module type S = S

  type nonrec volume_identifier = volume_identifier [@@deriving irmin]

  module Make_volume (Io : Io.S) (Errs : Io_errors.S with module Io = Io) :
    Volume with module Io = Io and module Errs = Errs

  module Make (Io : Io.S) (Errs : Io_errors.S with module Io = Io) :
    S with module Io = Io and module Errs = Errs
end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct