irmin-tezos
  1. Overview
  2. Docs

GC

type stats = {
  1. duration : float;
  2. finalisation_duration : float;
  3. read_gc_output_duration : float;
  4. transfer_latest_newies_duration : float;
  5. swap_duration : float;
}

Stats for a successful GC run. Times are in seconds.

val stats_t : stats Irmin.Type.t
type process_state = [
  1. | `Idle
  2. | `Running
  3. | `Finalised of stats
]

The state of the GC process after calling finalise_exn

Low-level API

val start_exn : ?unlink:bool -> repo -> commit_key -> bool Lwt.t

start_exn tries to start the GC process and returns true if the GC is launched. If a GC is already running, a new one is not started.

The GC process will not be automatically finalised. The caller is responsible for calling finalise_exn.

If unlink is false then temporary files and files from the previous generation will be kept on disk after the GC finished. This option is useful for debugging. The default is true.

TODO: Detail exceptions raised.

val finalise_exn : ?wait:bool -> repo -> process_state Lwt.t

finalise_exn ?wait repo waits for the GC process to finish in order to finalise it. It returns the state of the GC process from the point of view of the function call; subsequent calls of finalise_exn after a return of `Finalised will return `Idle.

Finalising consists of mutating repo so that it points to the new file and to flush the internal caches that could be referencing GCed objects.

If wait = true (the default), the call blocks until the GC process finishes. If wait = false, finalisation will occur if the process has ended.

If there are no running GCs, the call is a no-op and it returns `Idle.

TODO: Detail exceptions raised.

High-level API

type msg = [
  1. | `Msg of string
]

Pretty-print error messages meant for informational purposes, like logging

val run : ?finished:((stats, msg) result -> unit Lwt.t) -> repo -> commit_key -> (bool, msg) result Lwt.t

run repo commit_key attempts to start a GC process for a repo by discarding all data prior to commit_key. If a GC process is already running, a new one will not be started.

run will also finalise the GC process automaticlly. For more detailed control, see start_exn and finalise_exn.

When the GC process is finalised, finished is called with the result of finalisation.

To monitor progress of GC, see wait or is_finished.

Returns whether a GC process successfully started or not.

All exceptions that Irmin_pack knows how to handle are caught and returned as pretty-print error messages; others are re-raised. The error messages should be used only for informational purposes, like logging.

val wait : repo -> (stats option, msg) result Lwt.t

wait repo blocks until GC is finished or is idle.

If a GC finalises, its stats are returned.

All exceptions that Irmin_pack knows how to handle are caught and returned as pretty-print error messages; others are re-raised. The error messages should be used only for informational purposes, like logging.

val is_finished : repo -> bool

is_finished repo is true if a GC is finished (or idle) and false if a GC is running for the given repo.

val is_allowed : repo -> bool

is_allowed repo returns true if a gc can be run on the store.