package octez-internal-libs

  1. Overview
  2. Docs
package octez-internal-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type
type 'hash t

The type of keys referencing values stored in the irmin-pack backend.

type safe =
  1. | SAFE
and unsafe =
  1. | UNSAFE
type ('hash, _) unsafe_state = private
  1. | Direct : {
    1. hash : 'hash;
    2. offset : Optint.Int63.t;
    3. length : int;
    4. volume_identifier : Lower.volume_identifier option;
    } -> ('hash, safe) unsafe_state
    (*

    A "direct" pointer to a value stored at offset in the pack-file (with hash hash and length length). Such keys can be dereferenced from the store with a single IO read, without needing to consult the index.

    They are built in-memory (e.g. after adding a fresh value to the pack file), but have no corresponding encoding format, as the pack format keeps length information with the values themselves.

    When decoding a inode, which references its children as single offsets, we fetch the length information of the child at the same time as fetching its hash (which we must do anyway in order to do an integrity check), creating keys of this form.

    *)
  2. | Indexed : 'hash -> ('hash, safe) unsafe_state
    (*

    A pointer to an object in the pack file that is indexed. Reading the object necessitates consulting the index, after which the key can be promoted to Direct.

    Such keys result from decoding pointers to other store objects (nodes or commits) from commits or from the branch store.

    *)
  3. | Offset : Optint.Int63.t -> ('hash, unsafe) unsafe_state
    (*

    Same as Direct, but the hash and length of the object have not been fetched. Only used to speed up the GC traversal.

    *)

The internal state of a key (read with inspect).

Invariant: keys of the form Indexed always reference values that have entries in the index (as otherwise these keys could not be dereferenced).

type 'hash state = ('hash, safe) unsafe_state

Undereferencable keys

A key k is "undereferencable" with respect to some store handle t if find t k <> Some _. Such keys should not arise during regular operation of a single Irmin repository, but are still technically constructible in the following ways:

  • storage corruption. When decoding a key from disk, we may not immediately check that it is dereferenceable for performance reasons. In this case, any corruption to the key (or the referenced section of the store) will be discovered on attempted find (or mem).
  • passing keys between store handles. Read-only handles on a pack store must explicitly reload to observe recent writes to the store. This means that any keys built by a read-write instance and passed to a read-only instance will be undereferencable until that reader has reloaded.
  • passing keys between repositories. Keys created for one Irmin repository may not be dereferenced with respect to another by design.
val inspect : 'hash t -> 'hash state
val v_direct : offset:Optint.Int63.t -> length:int -> ?volume_identifier:Lower.volume_identifier -> 'h -> 'h t
val v_indexed : 'h -> 'h t
val v_offset : Optint.Int63.t -> 'h t
val promote_exn : offset:Optint.Int63.t -> length:int -> ?volume_identifier:Lower.volume_identifier -> 'h t -> unit
val set_volume_identifier_exn : volume_identifier:Lower.volume_identifier option -> 'h t -> unit
val to_offset : 'h t -> Optint.Int63.t option
val to_hash : 'h t -> 'h
val to_length : 'h t -> int option
module type S = sig ... end
module Make (Hash : Irmin.Hash.S) : S with type hash = Hash.t
module type Store_spec = sig ... 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