current 0.1 · OCaml Package

type 'a or_error = ('a, [ `Msg of string ]) Stdlib.result

module Level : sig ... end

Each operation has a level, giving an estimate of the cost or risk of the operation. When testing a pipeline, it can be useful to set a maximum level, or to require confirmation for more risky operations.

module Config : sig ... end

type job_id = string

class type actions = object ... end

module Step : sig ... end

module Input : sig ... end

module Job_map : Stdlib.Map.S with type key = job_id

val monitor : 
  read:(unit -> 'a or_error Lwt.t) ->
  watch:((unit -> unit) -> (unit -> unit Lwt.t) Lwt.t) ->
  pp:(Stdlib.Format.formatter -> unit) ->
  'a Input.t

monitor ~read ~watch ~pp is an input that uses read to read the current value of some external resource and watch to watch for changes. When the input is needed, it first calls watch refresh to start watching the resource. When this completes, it uses read () to read the current value. Whenever the watch thread calls refresh it marks the value as being out-of-date and will call read to get a new value. When the input is no longer required, it will call the shutdown function returned by watch to stop watching the resource. If it is needed later, it will run watch to start watching it again. This function takes care to perform only one user action (installing the watch, reading the value, or turning off the watch) at a time. For example, if refresh is called while already reading a value then it will wait for the current read to complete and then perform a second one.

include Current_term.S.TERM with type 'a input := 'a Input.t

type +'a t

An 'a t is a term that produces a value of type 'a.

type description

Information about operations hidden behind a bind.

val active : Current_term.Output.active -> 'a t

active x is a term indicating that the result is not determined yet.

val return : ?label:string -> 'a -> 'a t

return x is a term that immediately succeeds with x.

parameter label
Label the constant in the diagrams.

val fail : string -> 'a t

fail m is a term that immediately fails with message m.

val state : 
  ?hidden:bool ->
  'a t ->
  ('a, [ `Active of Current_term.Output.active | `Msg of string ])
    Stdlib.result
    t

state t always immediately returns a successful result giving the current state of t.

parameter hidden
If true, don't show a separate node for this on the diagrams.

val catch : ?hidden:bool -> 'a t -> 'a Current_term.S.or_error t

catch t successfully returns Ok x if t evaluates successfully to x, or successfully returns Error e if t fails with error e. If t is active then catch t will be active too.

parameter hidden
If true, don't show a separate node for this on the diagrams.

val ignore_value : 'a t -> unit t

ignore_value x is map ignore x.

val of_output : 'a Current_term.Output.t -> 'a t

of_output x is a returned, failed or active term.

Sequencing terms

Applicative operations

val map : ('a -> 'b) -> 'a t -> 'b t

map f x is a term that runs x and then transforms the result using f.

val map_error : (string -> string) -> 'a t -> 'a t

map_error f x is a term that runs x and then transforms the error string (if any) using f.

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

pair a b is the pair containing the results of evaluating a and b (in parallel).

val list_map : pp:'a Fmt.t -> ('a t -> 'b t) -> 'a list t -> 'b list t

list_map ~pp f xs adds f to the end of each input term and collects all the results into a single list.

parameter pp
Label the instances.

val list_iter : pp:'a Fmt.t -> ('a t -> unit t) -> 'a list t -> unit t

Like list_map but for the simpler case when the result is unit.

val list_seq : 'a t list -> 'a list t

list_seq x evaluates to a list containing the results of evaluating each element in x, once all elements of x have successfully completed.

val option_map : ('a t -> 'b t) -> 'a option t -> 'b option t

option_map f x is a term that evaluates to Some (f y) if x evaluates to Some y, or to None otherwise.

val option_seq : 'a t option -> 'a option t

option_seq None is Current.return None and option_seq (Some x) is Current.map some x. This is useful for handling optional arguments that are currents.

val all : unit t list -> unit t

all xs is a term that succeeds if every term in xs succeeds.

val all_labelled : (string * unit t) list -> unit t

all xs is a term that succeeds if every term in xs succeeds. The labels are used if some terms fail, to indicate which ones are failing.

val gate : on:unit t -> 'a t -> 'a t

gate ~on:ctrl x is the same as x, once ctrl succeeds.

Monadic operations

N.B. these operations create terms that cannot be statically analysed until after they are executed.

val bind : ?info:description -> ('a -> 'b t) -> 'a t -> 'b t

bind f x is a term that first runs x to get y and then behaves as the term f y. Static analysis cannot look inside the f function until x is ready, so using bind makes static analysis less useful. You can use the info argument to provide some information here.

val bind_input : info:description -> ('a -> 'b Input.t) -> 'a t -> 'b t

bind_input ~info f x is a term that first runs x to get y and then behaves as the input f y. info is used to describe the operation in the analysis result.

val component : 
  ('a, Stdlib.Format.formatter, unit, description) Stdlib.format4 ->
  'a

component name is used to annotate binds, so that the system can show a name for the operations hidden inside the bind's function. name is used as the label for the bind in the generated dot diagrams. For convenience, name can also be a format string.

module Syntax : sig ... end

type 'a term = 'a t

An alias of t to make it easy to refer to later in this file.

module Analysis : 
  Current_term.S.ANALYSIS with type 'a term := 'a t and type job_id := job_id

module Engine : sig ... end

module Var (T : Current_term.S.T) : sig ... end

val state_dir : string -> Fpath.t

state_dir name is a directory under which state (build results, logs) can be stored. name identifies the sub-component of OCurrent, each of which gets its own subdirectory.

module String : sig ... end

module Unit : sig ... end

Missing from the OCaml standard library.

module Switch : sig ... end

Like Lwt_switch, but the cleanup functions are called in sequence, not in parallel.

module Pool : sig ... end

module Job : sig ... end

module Process : sig ... end

module Db : sig ... end

module Log_matcher : sig ... end

package current

Sequencing terms

Applicative operations

Monadic operations