ocamlbuild/ocamlbuild_executor.mli

   1 (***********************************************************************)
   2 (*                             ocamlbuild                              *)
   3 (*                                                                     *)
   4 (*  Nicolas Pouillard, Berke Durak, projet Gallium, INRIA Rocquencourt *)
   5 (*                                                                     *)
   6 (*  Copyright 2007 Institut National de Recherche en Informatique et   *)
   7 (*  en Automatique.  All rights reserved.  This file is distributed    *)
   8 (*  under the terms of the Q Public License version 1.0.               *)
   9 (*                                                                     *)
  10 (***********************************************************************)
  11
  12 (* $Id$ *)
  13 (* Original author: Berke Durak *)
  14 (* Ocamlbuild_executor *)
  15
  16 (** UNIX-specific module for running tasks in parallel and properly multiplexing their outputs. *)
  17
  18 type error =
  19   | Subcommand_failed
  20   | Subcommand_got_signal
  21   | Io_error
  22   | Exceptionl_condition
  23
  24 (** [execute ~ticker ~period ~display ~exit commands] will execute the commands
  25     in [commands] in parallel, correctly multiplexing their outputs.
  26
  27     A  command  is  a function that given a unit [()] returns the shell command
  28     string  to  execute,  commands  are  functions in order to do some job just
  29     before  executing  the  command.  These  functions  will be called once. If
  30     specified,  it  will  call  [ticker]  at  least  every [period] seconds. If
  31     specified,  it  will  call  [display  f] when it wishes to print something;
  32     [display]  should  then  call  [f]  with  then  channel on which [f] should
  33     print.
  34
  35     Note  that  if  the shell command to execute is the empty string [""], it's
  36     considered as a no-op.
  37
  38     Note  that  [f] must be idempotent as it may well be called twice, once for
  39     the log file, once for the actual output.
  40
  41     If  one of the commands fails, it will exit with an appropriate error code,
  42     calling [cleanup] before.
  43
  44     All  exits  are  done  trough the call to the given [exit] function, if not
  45     supplied Pervasives.exit is used.
  46 *)
  47 val execute :
  48   ?max_jobs:int ->
  49   ?ticker:(unit -> unit) ->
  50   ?period:float ->
  51   ?display:((out_channel -> unit) -> unit) ->
  52    exit:(error -> unit) ->
  53     ((unit -> string) list list) ->
  54     (bool list * exn) option