current 0.2 · OCaml Package

Jobs with log files. This is mostly an internal interface - use Current_cache instead.

type t

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

val create : switch:Switch.t -> label:string -> config:Config.t -> unit -> t

create ~switch ~label ~config () is a new job.

parameter switch
Turning this off will cancel the job.

parameter label
A label to use in the job's filename (for debugging).

val start : 
  ?timeout:Duration.t ->
  ?pool:Pool.t ->
  level:Level.t ->
  t ->
  unit Lwt.t

start t ~level marks t as running. This can only be called once per job. If confirmation has been configured for level, then this will wait for confirmation first.

parameter timeout
If given, the job will be cancelled automatically after this period of time.

parameter pool
If given, the job cannot start until a pool resource is available. The resource is freed when the job finishes.

val start_time : t -> float Lwt.t

start_time t is the time when start was called, or an unresolved promise for it if start hasn't been called yet.

val write : t -> string -> unit

write t data appends data to the log.

val log : t -> ('a, Stdlib.Format.formatter, unit, unit) Stdlib.format4 -> 'a

log t fmt appends a formatted message to the log, with a newline added at the end.

val id : t -> job_id

id t is the unique identifier for this job.

val log_path : job_id -> Fpath.t or_error

log_path id is the path of the log for job id, if valid.

val pp_id : job_id Fmt.t

val is_running : t -> bool

is_running t is true if the log file is still open.

val wait_for_log_data : t -> unit Lwt.t

wait_for_log_data t is a promise that resolves the next time log data is written or the log is closed.

val lookup_running : job_id -> t option

If lookup_running job_id is the job j with id job_id, if is_running j.

val jobs : unit -> t Map.t

jobs () is the set of active jobs, whether they are currently used in a pipeline or not. This is any job which is running or ready to run (i.e. every job which hasn't closed its log file).

val approve_early_start : t -> unit

approve_early_start t marks the job as approved to start even if the global confirmation threshold would otherwise prevent it. Calling this more than once has no effect.

val is_waiting_for_confirmation : t -> bool

Indicates whether the job would benefit from approve_early_start being called.

val on_cancel : t -> (string -> unit Lwt.t) -> unit Lwt.t

on_cancel t fn calls fn reason if the job is cancelled. If the job has already been cancelled, fn is called immediately. If a job finishes without being cancelled, the cancel hooks are run at the end anyway.

val with_handler : 
  t ->
  on_cancel:(string -> unit Lwt.t) ->
  (unit -> 'a Lwt.t) ->
  'a Lwt.t

with_handler t ~on_cancel fn is like fn (), but if the job is cancelled while fn is running then on_cancel reason is called. Even if cancelled, fn is still run to completion. If the job has already been cancelled then on_cancel reason is called immediately (but fn still runs).

val cancel : t -> string -> unit

cancel msg requests that t be cancelled. This runs all registered cancel hooks and marks the job as cancelled. If the job is already cancelled, this has no effect.

val cancelled_state : t -> unit or_error

cancelled_state t is Ok () if the job hasn't been cancelled, or Error (`Msg reason) if it has. This should not be used after the switch has been turned off.

val register_actions : job_id -> actions -> unit

register_actions job_id actions is used to register handlers for e.g. rebuilding jobs.

package current