package irmin-pack

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

Abstraction that governs the lifetime of the various files that are part of a pack store (except the branch store).

The file manager handles the files one by one and makes explicit all the interactions between them (except the index which is handled at a high level).

module Io : Io.S

Low level IO abstraction. A typical implementation is unix. This abstraction is meant to be dead simple. Not a lot of documentation is required.

module Control : Control_file.S with module Io = Io

Abstraction for irmin-pack's control file.

module Dict : Append_only_file.S with module Io = Io

Abstraction for irmin-pack's append only files (i.e. suffix and dict).

module Suffix : Append_only_file.S with module Io = Io

Abstraction for irmin-pack's append only files (i.e. suffix and dict).

module Index : sig ... end

An abstraction on top of the index library that exposes an API that better fits the irmin-pack use case.

type t
val control : t -> Control.t
val dict : t -> Dict.t
val suffix : t -> Suffix.t
val index : t -> Index.t
type create_error := [
  1. | Io.create_error
  2. | Io.write_error
  3. | Io.open_error
  4. | Io.mkdir_error
  5. | `Not_a_directory of string
  6. | `Index_failure of string
]
val create_rw : overwrite:bool -> Irmin.Backend.Conf.t -> (t, [> create_error ]) Stdlib.result

Note on SWMR consistency: It is undefined for a reader to attempt an opening before create_rw is over.

Note on crash consistency: Crashing during create_rw leaves the storage in an undefined state.

Note on errors: If create_rw returns an error, the storage is left in an undefined state and some file descriptors might not be closed.

type open_rw_error := [
  1. | `Corrupted_control_file
  2. | `Double_close
  3. | `File_exists of string
  4. | `Index_failure of string
  5. | `Invalid_argument
  6. | `Invalid_layout
  7. | `Io_misc of Control.Io.misc_error
  8. | `Migration_needed
  9. | `No_such_file_or_directory
  10. | `Not_a_directory of string
  11. | `Not_a_file
  12. | `Read_on_closed
  13. | `Read_out_of_bounds
  14. | `Ro_not_allowed
  15. | `Sys_error of string
  16. | `V3_store_from_the_future
  17. | `Write_on_closed
  18. | `Index_failure of string
  19. | `Unknown_major_pack_version of string
  20. | `Inconsistent_store
]
val open_rw : Irmin.Backend.Conf.t -> (t, [> open_rw_error ]) Stdlib.result

Note on SWMR consistency: It is undefined for a reader to attempt and opening during an open_rw.

Note on crash consistency: If open_rw crashes during open_rw_migrate_from_v1_v2, the storage is left in an undefined state. Otherwise the storage is unaffected.

Note on errors: If open_rw returns an error during open_rw_migrate_from_v1_v2, the storage is left in an undefined state. Otherwise the storage is unaffected. Anyhow, some file descriptors might not be closed.

type open_ro_error := [
  1. | `Corrupted_control_file
  2. | `File_exists of string
  3. | `Io_misc of Io.misc_error
  4. | `Migration_needed
  5. | `No_such_file_or_directory
  6. | `Not_a_file
  7. | `Read_on_closed
  8. | `V3_store_from_the_future
  9. | `Index_failure of string
  10. | `Unknown_major_pack_version of string
  11. | `Inconsistent_store
  12. | `Read_out_of_bounds
  13. | `Invalid_argument
  14. | `Inconsistent_store
]
val open_ro : Irmin.Backend.Conf.t -> (t, [> open_ro_error ]) Stdlib.result

Note on SWMR consistency: TODO: doc

Note on crash consistency: The storage is never mutated.

Note on errors: The storage is never mutated. Some file descriptors might not be closed.

type close_error := [
  1. | `Double_close
  2. | `Index_failure of string
  3. | `Io_misc of Io.misc_error
  4. | `Pending_flush
]
val close : t -> (unit, [> close_error ]) Stdlib.result

Close all the files.

This call fails if the append buffers are not in a flushed stated. This situation will most likely never occur because the append buffers will contain data only during the scope of a batch function.

After

type flush_error := [
  1. | `Index_failure of string
  2. | `Io_misc of Io.misc_error
  3. | `Ro_not_allowed
  4. | `Write_on_closed
]
val flush : t -> (unit, [> flush_error ]) Stdlib.result
type reload_error := [
  1. | `Corrupted_control_file
  2. | `Index_failure of string
  3. | `Invalid_argument
  4. | `Io_misc of Io.misc_error
  5. | `Read_on_closed
  6. | `Read_out_of_bounds
  7. | `Rw_not_allowed
  8. | `Unknown_major_pack_version of string
]
val reload : t -> (unit, [> reload_error ]) Stdlib.result
val register_dict_consumer : t -> after_reload:(unit -> (unit, Io.read_error) Stdlib.result) -> unit
val register_suffix_consumer : t -> after_flush:(unit -> unit) -> unit
type version_error := [
  1. | `Corrupted_control_file
  2. | `Corrupted_legacy_file
  3. | `Invalid_layout
  4. | `Io_misc of Io.misc_error
  5. | `No_such_file_or_directory
  6. | `Not_a_directory of string
  7. | `Unknown_major_pack_version of string
]
val version : root:string -> (Irmin_pack.Version.t, [> version_error ]) Stdlib.result

version ~root is the version of the files at root.

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