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 type 'a retire = 'a -> unit
  25
  26 type 'a to_string = 'a -> string
  27
  28 val run : (unit -> 'a next) -> 'a retire -> 'a to_string -> unit
  29 (** [run next_job retire_job] runs jobs in parallel.  [next_job]
  30     is called to pick the next available job.  [retire_job] is
  31     called when a job finishes successfully.
  32
  33     If [next_job] returns [Job f] then that function is started
  34     (usually in a thread if -j N > 1).
  35
  36     If [next_job] returns [Complete] then [run] waits until
  37     all parallel jobs are then returns.
  38
  39     If [next_job] returns [Not_ready] then [next_job] will be
  40     called again after a little while.
  41
  42     If any job throws an exception then the exception will be
  43     reraised by [run], usually causing goals to exit with an error.
  44     The exception is delayed until all currently running jobs
  45     finish, but no new jobs will be started during this time. *)