package octez-internal-libs

  1. Overview
  2. Docs
package octez-internal-libs
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Source file sparse_file_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
(*
 * Copyright (c) 2022 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

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

  type t
  type open_error := [ Io.open_error | `Corrupted_mapping_file of string ]

  val open_ro :
    mapping_size:int ->
    mapping:string ->
    data:string ->
    (t, [> open_error ]) result
  (** [open_ro ~mapping_size ~mapping ~data] returns a new read-only view of the
      sparse file, represented on disk by two files named [mapping] and [data].
      The mapping file is expected to have size at least [mapping_size] (and the
      rest is ignored if the file is larger). *)

  val close : t -> (unit, [> Io.close_error ]) result
  (** Close the underlying files. *)

  val read_exn : t -> off:int63 -> len:int -> bytes -> unit
  (** [read_exn t ~off ~len buffer] writes into [buffer] the bytes from [off] to
      [off+len]. *)

  val read_range_exn :
    t -> off:int63 -> min_len:int -> max_len:int -> bytes -> int
  (** Same as [read_exn], the amount read is [max_len] if possible or at least
      [min_len] if reading more would step over a hole in the sparse file.

      Returns the actually read length. *)

  val next_valid_offset : t -> off:int63 -> int63 option
  (** [next_valid_offset t ~off] returns [Some off'] such that [off'] is the
      smallest readable offset larger or equal to [off]. This enables jumping
      over a sparse hole to the next compact range of data. *)

  val iter : t -> (off:int63 -> len:int -> unit) -> (unit, Errs.t) result
  (** [iter t f] calls [f] on each [(off,len)] pair in [mapping]. Only used for
      testing and debugging.

      It is guaranteed for the offsets to be iterated in monotonic order.

      It is guaranteed that entries don't overlap.

      The exceptions raised by [f] are caught and returned (as long as they are
      known by [Errs]). *)

  module Wo : sig
    type t

    val open_wo :
      mapping_size:int ->
      mapping:string ->
      data:string ->
      (t, [> open_error ]) result
    (** [open_wo ~mapping_size ~mapping ~data] returns a write-only instance of
        the sparse file.

        Note: This is unsafe and is only used by the GC to mark the parent
        commits as dangling. One must ensure that no read-only instance is
        opened at the same time, as otherwise the writes would be observable by
        it. *)

    val write_exn : t -> off:int63 -> len:int -> string -> unit
    (** [write_exn t ~off ~len str] writes the first [len] bytes of [str] to [t]
        at the virtual offset [off]. *)

    val fsync : t -> (unit, [> Io.write_error ]) result
    (** [fsync t] persists to the file system the effects of previous writes. *)

    val close : t -> (unit, [> Io.close_error ]) result
    (** Close the underlying files. *)

    val create_from_data :
      mapping:string ->
      dead_header_size:int ->
      size:Int63.t ->
      data:string ->
      (int63, [> Io.create_error | Io.write_error | Io.close_error ]) result
    (** [create_from_data ~mapping ~dead_header_size ~size ~data] initializes a
        new sparse file on disk from the existing file [data], by creating the
        corresponding [mapping] file. The first [dead_header_size] bytes are
        ignored and the remaining [size] bytes of [data] are made available.

        On success, returns the size of the [mapping] file to be stored in the
        control file for consistency checking on open. *)
  end

  module Ao : sig
    type t

    val end_off : t -> Int63.t
    (** [end_off t] returns the largest virtual offset contained in the sparse
        file [t]. Attempting to append with a strictly smaller virtual offset
        will fail. *)

    val mapping_size : t -> Int63.t
    (** [end_off t] returns the current size of the mapping file associated to
        the sparse file [t] including additions not yet flushed to the file
        system. It can be passed to {!open_ao} as [mapping_size] when opening
        the file again. *)

    val create :
      mapping:string -> data:string -> (t, [> Io.create_error ]) result
    (** [create ~mapping ~data] initializes a new empty sparse file, represented
        on disk by two files named [mapping] and [data]. *)

    val open_ao :
      mapping_size:Int63.t ->
      mapping:string ->
      data:string ->
      ( t,
        [> Io.open_error
        | `Closed
        | `Invalid_argument
        | `Read_out_of_bounds
        | `Inconsistent_store ] )
      result
    (** [open_ao ~mapping_size ~mapping ~data] returns an append-only instance
        of the sparse file. *)

    val append_seq_exn : t -> off:int63 -> string Seq.t -> unit
    (** [append_seq_exn t ~off seq] appends the sequence of strings [seq] to the
        sparse file [t], at the virtual offset [off] which must be larger than
        the previously appended offsets. *)

    val flush : t -> (unit, [> Io.write_error ]) result
    (** Flush the append buffer. Does not call [fsync]. *)

    val close : t -> (unit, [> Io.close_error | `Pending_flush ]) result
    (** Close the underlying files. *)
  end
end

module type Sigs = sig
  module type S = S

  module Make (Io : Io.S) : S with module Io = Io
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