Module Current.Job

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 : ?priority:Pool.priority -> 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 priority

    Passed to the pool when start is called. Default is `Low.

  • parameter label

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

val start : ?timeout:Duration.t -> ?pool:unit 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

    Deprecated. Use start_with instead.

val start_with : ?timeout:Duration.t -> pool:'a Pool.t -> level:Level.t -> t -> 'a Lwt.t

start_with is like start except that it waits for a resource from pool. 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.

val use_pool : ?priority:Pool.priority -> switch:Switch.t -> t -> 'a Pool.t -> 'a Lwt.t

use_pool ~switch t pool gets one resource from pool. The resource is returned to the pool when the switch is turned off. The operation will be aborted if the job is cancelled.