package irmin-pack

  1. Overview
  2. Docs
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.Unix
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.

module Errs : Io_errors.S with module Io = Io
module Mapping_file : Mapping_file.S with module Io = Io
type t
val control : t -> Control.t
val dict : t -> Dict.t
val suffix : t -> Suffix.t
val index : t -> Index.t
val mapping : t -> Mapping_file.t option
val prefix : t -> Io.t option
type create_error := [
  1. | Io.create_error
  2. | Io.write_error
  3. | Io.open_error
  4. | Io.mkdir_error
  5. | `Corrupted_mapping_file of string
  6. | `Not_a_directory of string
  7. | `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. | `Corrupted_mapping_file of string
  3. | `Double_close
  4. | `Closed
  5. | `File_exists of string
  6. | `Index_failure of string
  7. | `Invalid_argument
  8. | `Invalid_layout
  9. | `Io_misc of Control.Io.misc_error
  10. | `Migration_needed
  11. | `No_such_file_or_directory
  12. | `Not_a_directory of string
  13. | `Not_a_file
  14. | `Read_out_of_bounds
  15. | `Ro_not_allowed
  16. | `Sys_error of string
  17. | `V3_store_from_the_future
  18. | `Only_minimal_indexing_strategy_allowed
  19. | `Unknown_major_pack_version of string
  20. | `Index_failure of string
  21. | `Sys_error of string
  22. | `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. | `Corrupted_mapping_file of string
  3. | `File_exists of string
  4. | `Io_misc of Io.misc_error
  5. | `Migration_needed
  6. | `No_such_file_or_directory
  7. | `Not_a_file
  8. | `Closed
  9. | `V3_store_from_the_future
  10. | `Index_failure of string
  11. | `Unknown_major_pack_version of string
  12. | `Inconsistent_store
  13. | `Invalid_argument
  14. | `Read_out_of_bounds
  15. | `Ro_not_allowed
]
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
  5. | `Ro_not_allowed
]
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. | `Closed
]
type flush_stages := [
  1. | `After_dict
  2. | `After_suffix
]
type 'a hook := 'a -> unit
val flush : ?hook:flush_stages hook -> t -> (unit, [> flush_error ]) Stdlib.result
type reload_stages := [
  1. | `After_index
  2. | `After_control
  3. | `After_suffix
]
val reload : ?hook:reload_stages hook -> t -> (unit, [> Errs.t ]) Stdlib.result
val register_mapping_consumer : t -> after_reload:(unit -> (unit, Errs.t) Stdlib.result) -> unit
val register_dict_consumer : t -> after_reload:(unit -> (unit, Errs.t) 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.

val swap : t -> generation:int -> right_start_offset:Optint.Int63.t -> right_end_offset:Optint.Int63.t -> (unit, [> Errs.t ]) Stdlib.result
type write_gc_output_error := [
  1. | `Double_close
  2. | `File_exists of string
  3. | `Io_misc of Io.misc_error
  4. | `Ro_not_allowed
  5. | `Closed
]
val write_gc_output : root:string -> generation:int -> (Optint.Int63.t, Errs.t) Stdlib.result -> (unit, [> write_gc_output_error ]) Stdlib.result

Used by the gc process at the end to write its output in store.<generation>.out.

type read_gc_output_error = [
  1. | `Corrupted_gc_result_file of string
  2. | `Gc_process_error of string
]
val read_gc_output_error_t : read_gc_output_error Irmin.Type.t
val read_gc_output : root:string -> generation:int -> (Optint.Int63.t, [> read_gc_output_error ]) Stdlib.result

Used by the main process, after the gc process finished, to read store.<generation>.out.

val readonly : t -> bool
val generation : t -> int
val gc_allowed : t -> bool