package irmin-pack

  1. Overview
  2. Docs
package irmin-pack
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 'hash state = private
  1. | Direct of {
    1. hash : 'hash;
    2. offset : Optint.Int63.t;
    3. length : int;
    }
    (*

    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 of 'hash
    (*

    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.

    *)

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).

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 : hash:'h -> offset:Optint.Int63.t -> length:int -> 'h t
val v_indexed : 'h -> 'h t
val promote_exn : 'h t -> offset:Optint.Int63.t -> length:int -> unit
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