src/jobs.mli

   1 (* Goals parallel jobs.
   2  * Copyright (C) 2020 Richard W.M. Jones
   3  * Copyright (C) 2020 Red Hat Inc.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  *)
  19
  20 (** This module manages parallel jobs. *)
  21
  22 type 'a next = Job of 'a * (unit -> unit) | Complete | Not_ready
  23
  24 val run : (unit -> 'a next) -> ('a -> unit) -> ('a -> unit) ->
  25           ('a -> string) -> unit
  26 (** [run next_job retire_job fail_job to_string] runs jobs in parallel.
  27
  28     [next_job] is called to pick the next available job.
  29     [retire_job] is called when a job finishes successfully.
  30     [fail_job] is called when a job fails (only in keep-going
  31     -k mode).  All jobs that depend on this one must be marked
  32     failed by the caller.
  33     [to_string] is called if we need to print the job name.
  34
  35     If [next_job] returns [Job f] then that function is started
  36     (usually in a thread if -j N > 1).
  37
  38     If [next_job] returns [Complete] then [run] waits until
  39     all parallel jobs are finished then returns.
  40
  41     If [next_job] returns [Not_ready] then [next_job] will be
  42     called again after a little while.
  43
  44     If any job throws an exception then the exception will be
  45     reraised by [run], usually causing goals to exit with an error.
  46     The exception is delayed until all currently running jobs
  47     finish.  In normal mode no new jobs will be started during
  48     this time.  In keep-going -k mode new jobs may be started. *)