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     Jobs are grouped.  You call [new_group] to create a new
  23     group of jobs, initially empty.  Then add jobs to it.  Then
  24     wait for all the jobs in the group to complete.
  25
  26     To submit a job to a group use [start group key f].  [group]
  27     is an existing group of jobs to which this is added.  [key] is
  28     a key which ensures that two identical jobs cannot be running
  29     at the same time (across all groups).  If two or more jobs
  30     with the same key are submitted then only one will run and
  31     the others will wait until the first finishes, and then another
  32     will be picked to run and so on.  Jobs with different keys run
  33     freely in parallel, assuming there are enough threads available
  34     to run them.
  35
  36     Goals uses the goal (name + parameters) as the key to
  37     ensure you cannot have two jobs running at the same time
  38     which would interfere with each other by trying to build
  39     the same target.
  40
  41     To wait for a group of jobs to complete, call [wait group].
  42  *)
  43
  44 module type Key = sig
  45   type t
  46   val compare : t -> t -> int
  47   val to_string : t -> string
  48 end
  49
  50 module type Jobs = sig
  51   type key
  52   type group
  53
  54   val new_group : unit -> group
  55   (** Create a new empty jobs group. *)
  56
  57   val start : group -> key -> (unit -> unit) -> unit
  58   (** [start group key f] submits a job to run in the background.
  59       The [key] ensures that two jobs with the same key cannot run
  60       at the same time (across all groups). *)
  61
  62   val wait : group -> unit
  63   (** [wait group] waits for all of the jobs in the group to finish. *)
  64 end
  65
  66 module Make (K : Key) : Jobs with type key = K.t