package octez-internal-libs

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

Module Irmin.MergeSource

Merge provides functions to build custom 3-way merge operators for various user-defined contents.

Merge operators.

Sourcetype conflict = [
  1. | `Conflict of string
]

The type for merge errors.

Sourceval conflict_t : conflict Type.t
Sourceval ok : 'a -> ('a, conflict) result Lwt.t

Return Ok x.

Sourceval conflict : ('a, unit, string, ('b, conflict) result Lwt.t) format4 -> 'a

Return Error (Conflict str).

Sourceval bind : ('a, 'b) result Lwt.t -> ('a -> ('c, 'b) result Lwt.t) -> ('c, 'b) result Lwt.t

bind r f is the merge result which behaves as of the application of the function f to the return value of r. If r fails, bind r f also fails, with the same conflict.

Sourceval map : ('a -> 'c) -> ('a, 'b) result Lwt.t -> ('c, 'b) result Lwt.t

map f m maps the result of a merge. This is the same as bind m (fun x -> ok (f x)).

Merge Combinators

Sourcetype 'a promise = unit -> ('a option, conflict) result Lwt.t

An 'a promise is a function which, when called, will eventually return a value type of 'a. A promise is an optional, lazy and non-blocking value.

Sourceval promise : 'a -> 'a promise

promise a is the promise containing a.

Sourceval map_promise : ('a -> 'b) -> 'a promise -> 'b promise

map_promise f a is the promise containing f applied to what is promised by a.

Sourceval bind_promise : 'a promise -> ('a -> 'b promise) -> 'b promise

bind_promise a f is the promise returned by f applied to what is promised by a.

Sourcetype 'a f = old:'a promise -> 'a -> 'a -> ('a, conflict) result Lwt.t

Signature of a merge function. old is the value of the least-common ancestor.

        /----> t1 ----\
----> old              |--> result
        \----> t2 ----/
Sourcetype 'a t

The type for merge combinators.

Sourceval v : 'a Type.t -> 'a f -> 'a t

v dt f create a merge combinator.

Sourceval f : 'a t -> 'a f

f m is m's merge function.

Sourceval seq : 'a t list -> 'a t

Call the merge functions in sequence. Stop as soon as one is not returning a conflict.

Sourceval like : 'a Type.t -> 'b t -> ('a -> 'b) -> ('b -> 'a) -> 'a t

Use the merge function defined in another domain. If the converting functions raise any exception the merge is a conflict.

Sourceval with_conflict : (string -> string) -> 'a t -> 'a t

with_conflict f m is m with the conflict error message modified by f.

Sourceval like_lwt : 'a Type.t -> 'b t -> ('a -> 'b Lwt.t) -> ('b -> 'a Lwt.t) -> 'a t

Same as biject but with blocking domain converting functions.

Basic Merges

Sourceval default : 'a Type.t -> 'a t

default t is the default merge function for values of type t. This is a simple merge function which supports changes in one branch at a time:

  • if t1=old then the result of the merge is OK t2;
  • if t2=old then return OK t1;
  • otherwise the result is Conflict.
Sourceval idempotent : 'a Type.t -> 'a t

idempotent t is the default merge function for values of type t using idempotent operations. It follows the same rules as the default merge function but also adds:

  • if t1=t2 then the result of the merge is OK t1.
Sourceval unit : unit t

unit is the default merge function for unit values.

Sourceval bool : bool t

bool is the default merge function for booleans.

Sourceval char : char t

char is the default merge function for characters.

Sourceval int32 : int32 t

int32 is the default merge function for 32-bits integers.

Sourceval int64 : int64 t

int64 the default merge function for 64-bit integers.

Sourceval float : float t

float is the default merge function for floating point numbers.

Sourceval string : string t

The default string merge function. Do not do anything clever, just compare the strings using the default merge function.

Sourceval option : 'a t -> 'a option t

Lift a merge function to optional values of the same type. If all the provided values are inhabited, then call the provided merge function, otherwise use the same behavior as default.

Sourceval pair : 'a t -> 'b t -> ('a * 'b) t

Lift merge functions to pairs of elements.

Sourceval triple : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t

Lift merge functions to triples of elements.

Counters and Multisets

Sourcetype counter = int64

The type for counter values. It is expected that the only valid operations on counters are increment and decrement. The following merge functions ensure that the counter semantics are preserved: i.e. it ensures that the number of increments and decrements is preserved.

Sourceval counter : counter t

The merge function for mergeable counters.

Sourcemodule MultiSet (K : sig ... end) : sig ... end

Multi-sets.

Maps and Association Lists

We consider the only valid operations for maps and association lists to be:

  • Adding a new bindings to the map.
  • Removing a binding from the map.
  • Replacing an existing binding with a different value.
  • Trying to add an already existing binding is a no-op.

We thus assume that no operation on maps is modifying the key names. So the following merge functions ensures that (i) new bindings are preserved (ii) removed bindings stay removed and (iii) modified bindings are merged using the merge function of values.

Note: We only consider sets of bindings, instead of multisets. Application developers should take care of concurrent addition and removal of similar bindings themselves, by using the appropriate multi-sets.

Sourcemodule Set (E : sig ... end) : sig ... end

Lift merge functions to sets.

Sourceval alist : 'a Type.t -> 'b Type.t -> ('a -> 'b option t) -> ('a * 'b) list t

Lift the merge functions to association lists.

Lift the merge functions to maps.

Sourcemodule Map (K : sig ... end) : sig ... end
Sourcemodule Infix : sig ... end

Infix operators for manipulating merge results and promises.

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