ocaml/otherlibs/threads/condition.mli

(***********************************************************************)
(*                                                                     *)
(*                         Caml Special Light                          *)
(*                                                                     *)
(*         Xavier Leroy and Damien Doligez, INRIA Rocquencourt         *)
(*                                                                     *)
(*  Copyright 1995 Institut National de Recherche en Informatique et   *)
(*  Automatique.  Distributed only by permission.                      *)
(*                                                                     *)
(***********************************************************************)

(* $Id$ *)

(* Module [Condition]: condition variables to synchronize between threads *)

(* Condition variables are used when one thread wants to wait until another
   thread has finished doing something: the former thread ``waits'' on the
   condition variable, the latter thread ``signals'' the condition when it
   is done. Condition variables should always be protected by a mutex.
   The typical use is (if [D] is a shared data structure, [m] its mutex,
   and [c] is a condition variable):
   [
     Mutex.lock m;
     while (* some predicate P over D is not satisfied *) do
       Condition.wait c m
     done;
     (* Modify D *)
     if (* the predicate P over D is now satified *) then Condition.signal c;
     Mutex.unlock m
   ]
*)

type t
        (* The type of condition variables. *)
external new: unit -> t = "csl_condition_new"
        (* Return a new condition variable. *)
external wait: t -> Mutex.t -> unit = "csl_condition_wait"
        (* [wait c m] atomically unlocks the mutex [m] and suspends the
           calling process on the condition variable [c]. The process will
           restart after the condition variable [c] has been signalled.
           The mutex [m] is locked again before [wait] returns. *)
external signal: t -> unit = "csl_condition_signal"
        (* [signal c] restarts one of the processes waiting on the 
           condition variable [c]. *)
external broadcast: t -> unit = "csl_condition_broadcast"
        (* [broadcast c] restarts all processes waiting on the 
           condition variable [c]. *)