1. Overview
  2. Docs
package datakit-ci
Legend:
Library
Module
Module type
Parameter
Class
Class type

Computation Terms

A term is a unit of computation, which can have various state and a log output. Terms can be short-lived or long-running.

type 'a t

The type for computation terms. A 'a t is a term that evaluates to an 'a, fails, or explains what it's waiting for.

val return : 'a -> 'a t

return x is a term that evaluates successfully to x.

val fail : ('a, Format.formatter, unit, 'b t) Pervasives.format4 -> 'a

fail fmt is a term that fails with message fmt.

val pending : ('a, Format.formatter, unit, 'b t) Pervasives.format4 -> 'a

pending fmt is a term that reports it is waiting because of reason fmt.

val state : 'a t -> ('a, [ `Pending of string | `Failure of string ]) Pervasives.result t

state x immediately and successfully returns the current state of x.

val of_state : ('a, [< `Pending of string | `Failure of string ]) Pervasives.result -> 'a t

of_state x is a term which evaluates to x.

val catch : 'a t -> ('a, [ `Failure of string ]) Pervasives.result t

catch x successfully returns a result showing whether x succeeded or failed.

val of_lwt_quick : 'a Lwt.t -> 'a t

of_lwt_quick x evaluates to the result of x. Note that the result is never pending, so this is only for quick operations.

val of_lwt_slow : (unit -> 'a status Lwt.t) -> 'a t

of_lwt_slow check is a term that evaluates check () to get the current status. If Error (`Pending (message, ready)), another check is scheduled when ready terminates.

val join : 'a t t -> 'a t

join tt is the term to which tt evaluates.

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

pair a b evaluates to the pair of the results of successfully evaluating a and b (in parallel). If a is not successful, the result is the same as a. Otherwise, if b is not successful then the result is the same as b.

val without_logs : 'a t -> 'a t

without_logs t evaluates to the same result as t, but does not link to its logs. This is useful if t's logs are already being reported as part of another job.

module Infix : sig ... end
val list_map_p : ('a -> 'b t) -> 'a list -> 'b list t

list_map_p fn l will map the l list of terms to fn in parallel and return the result list when all of them have completed.

val wait_for : 'a t -> while_pending:string -> on_failure:string -> unit t

wait_for t ~while_pending ~on_failure evaluates successfully to unit if t evaluates successfully. It is pending with reason while_pending while t is pending, and fails with error on_failure if t fails. This is useful in the case where one test case depends on another, to avoid reporting the same status twice. Consider wrapping with without_logs if t's logs will be reported as part of another job.

val wait_for_all : (string * 'a t) list -> unit t

wait_for_all xs evaluates successfully to unit if all terms in the assoc list xs evaluate successfully. Otherwise, it is pending or failed with a suitable message, based on the names of the terms it is waiting for. Consider wrapping with without_logs if xs's logs will be reported as part of another job.

val job_id : job_id t

job_id evaluates to the ID of the worker that evaluates the term. This is useful for logging.

Datakit Connection

val dk : (unit -> DK.t Lwt.t) t

dk is a function for getting the current DataKit connection.

GitHub Integration

val target : Target.t -> Target.v t

target id evaluates to the full metadata of the named target.

head target evaluates to the commit at the head target.

val branch_head : Datakit_github.Repo.t -> string -> Datakit_github.Commit.t t

branch_head repo b evaluates to the commit at the head of branch b in the repository repo.

tag repo t evaluates to the commit of tag t in the repository repo.

val ci_status : string list -> Target.t -> [ `Pending | `Success | `Failure | `Error ] option t

ci_status ci target is the status reported by CI ci for target. Note that even if the CI is e.g. pending, this returns a successful result with the value `Pending, not a pending result.

val ci_target_url : string list -> Target.t -> Uri.t option t

ci_target_url ci target is the target URL reported by CI ci.

val ci_success_target_url : string list -> Target.t -> Uri.t t

ci_success_target_url ci target is the URL of the *successful* build ci. It is pending until a successful URL is available.