package octez-shell-libs

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

Persistent block store with arborescent history

The floating block store is an append-only store where blocks are stored arbitrarily. This structure possess an indexed map Block_hash.t -> (offset × predecessors x resulting_context_hash) which points to its offset in the associated file along with an exponential list of predecessors block hashes (as implemented in Block_store.compute_predecessors) and the block's resulting context hash. The structure access/modification is protected by a mutex (Lwt_idle_waiter) and thus can be manipulated concurrently. Stored blocks may or may not contain metadata. The instance maintains an opened file descriptor. Therefore it must be properly closed or it might lead to a file descriptor leak.

Four different kind of instances are allowed to co-exist for an identical path: - RO, a read-only instance; - RW, a read-write instance - RO_TMP, RW_TMP, read-write instances; - Restore is a generic instance used to wrap leftover instances while fixing a crashed storage. See Block_store.

Invariants

This store is expected to respect the following invariant:

  • Every block stored is correctly indexed.

Files format

The floating block store is composed of the following files:

  • file: /<kind>_floating_block_store, a list of Block_repr.t:

| <block> * |

where <kind> is RO(_TMP), RW(_TMP) (see Naming) and <block>, a Block_repr.t value encoded using Block_repr.encoding (thus prefixed by the its size).

type t

The type of the floating store.

type floating_kind = Tezos_store_shared.Naming.floating_kind =
  1. | RO
  2. | RW
  3. | RW_TMP
  4. | RO_TMP
  5. | Restore of floating_kind

The type for the kind of floating store opened.

type info = {
  1. predecessors : Tezos_base.TzPervasives.Block_hash.t list;
  2. resulting_context_hash : Tezos_base.TzPervasives.Context_hash.t;
}

The type for informations stored in floating store indexes.

val default_floating_blocks_log_size : int

The default value of the floating blocks cache size used by index library.

val kind : t -> floating_kind

kind floating_store returns the floating store's kind.

val mem : t -> Tezos_base.TzPervasives.Block_hash.t -> bool Lwt.t

mem floating_store hash tests whether hash is stored in floating_store.

val find_info : t -> Tezos_base.TzPervasives.Block_hash.t -> info option Lwt.t

find_info floating_store block_hash reads from the index the info of block_hash if the block is stored in floating_store, returns None otherwise.

val find_predecessors : t -> Tezos_base.TzPervasives.Block_hash.t -> Tezos_base.TzPervasives.Block_hash.t list option Lwt.t

find_predecessors floating_store block_hash reads from the index the list of block_hash's predecessors if the block is stored in floating_store, returns None otherwise.

val find_resulting_context_hash : t -> Tezos_base.TzPervasives.Block_hash.t -> Tezos_base.TzPervasives.Context_hash.t option Lwt.t

find_resulting_context_hash floating_store block_hash reads from the index the resulting context hash if the block is stored in floating_store, returns None otherwise.

read_block floating_store hash reads from the file the block of hash if the block is stored in floating_store, returns None otherwise.

val read_block_and_info : t -> Tezos_base.TzPervasives.Block_hash.t -> (Tezos_store_shared.Block_repr.t * info) option Lwt.t

read_block_and_info floating_store hash same as read_block but also returns the block's info. Returns None if it fails to resolve the given hash.

val append_block : t -> ?flush:bool -> ?log_metrics:bool -> info -> Tezos_store_shared.Block_repr.block -> unit Tezos_base.TzPervasives.tzresult Lwt.t

append_block floating_store ?flush ?log_metrics info block stores the block in floating_store updating its index with the given info and flushing if flush is set to true (defaults to true). log_metrics enables logs of the amount of written bytes using the node's metrics.

append_all floating_store chunk stores the chunk of (blocks x info) in floating_store updating its index accordingly.

val iter_s_raw_fd : (Tezos_store_shared.Block_repr.t -> unit Tezos_base.TzPervasives.tzresult Lwt.t) -> Lwt_unix.file_descr -> unit Tezos_base.TzPervasives.tzresult Lwt.t

iter_s_raw_fd f fd unsafe sequential iterator on a file descriptor fd. Applies f on every block encountered.

Warning: should be used for internal use only (e.g. snapshots).

fold_left_s f e floating_store sequential fold left on the floating_store using f on every block and e as initial element. The function f is given the last read block.

val fold_left_with_info_s : ('a -> (Tezos_store_shared.Block_repr.block * info) -> 'a Tezos_base.TzPervasives.tzresult Lwt.t) -> 'a -> t -> 'a Tezos_base.TzPervasives.tzresult Lwt.t

fold_left_with_info_s f e floating_store sequential fold left on the floating_store using f on every block and e as initial element. The function f is given the last read block along with its info.

iter_s f floating_store sequential iterator on the floating_store. Applies f on every block read.

iter_with_info_s f floating_store sequential iterator on the floating_store. Applies f on every block (and its info) read.

val init : [ `Chain_dir ] Tezos_store_shared.Naming.directory -> readonly:bool -> floating_kind -> t Lwt.t

init ~chain_dir ~readonly kind creates or load an existing floating store at path chain_dir with kind.

Warning If readonly is not set, a RO instance is writable.

val close : t -> unit Lwt.t

close floating_store closes floating_store by closing the index and the associated opened file descriptor.

val delete_files : t -> unit Lwt.t

delete_files store closes the store then deletes its content.

val swap : src:t -> dst:t -> unit Lwt.t

swap ~src ~dst closes src and dst then overwrites dst files with src's ones.

Warning Non-atomic swap.

val append_floating_store : from:t -> into:t -> unit Tezos_base.TzPervasives.tzresult Lwt.t

append_floating_store ~from ~into takes two opened floating block stores and appends all blocks contained in from to into.

Integrity checks

val all_files_exists : [ `Chain_dir ] Tezos_store_shared.Naming.directory -> floating_kind -> bool Lwt.t

all_files_exists ~chain_dir kind checks that the files to the associated kind of floating store are present in the chain_dir directory.

val fix_integrity : [ `Chain_dir ] Tezos_store_shared.Naming.directory -> floating_kind -> unit Tezos_base.TzPervasives.tzresult Lwt.t

fix_integrity ~chain_dir kind error fixes the integrity of the floating block stores by removing corrupted data and restoring a consistent state.

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