package irmin-pack

  1. Overview
  2. Docs
package irmin-pack
Legend:
Library
Module
Module type
Parameter
Class
Class type
type process_state = [
  1. | `Idle
  2. | `Running
  3. | `Finalised of Stats.Latest_gc.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. What is done with the discarded data depends on behaviour.

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.Latest_gc.stats, msg) Stdlib.result -> unit Lwt.t) -> repo -> commit_key -> (bool, msg) Stdlib.result Lwt.t

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

run will also finalise the GC process automatically. 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.Latest_gc.stats option, msg) Stdlib.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 cancel : repo -> bool

cancel repo aborts the current GC and returns true, or returns false if no GC was running.

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 behaviour : repo -> [ `Archive | `Delete ]

behaviour repo returns the behaviour that the GC will have during finalization.

This depends on the presence of a lower layer in the store: if a lower layer is present, the GC will archive old data into that lower layer. Else, it will delete that data.

val is_allowed : repo -> bool

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

val latest_gc_target : repo -> commit_key option

latest_gc_target returns the commit key on which the latest, finished gc was called on.

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