.TH "Mutex" 3o 2023-09-20 OCamldoc "OCaml library"
.SH NAME
Mutex \- Locks for mutual exclusion.
.SH Module
Module   Mutex
.SH Documentation
.sp
Module
.BI "Mutex"
 : 
.B sig end

.sp
Locks for mutual exclusion\&.
.sp
Mutexes (mutual\-exclusion locks) are used to implement critical sections
and protect shared mutable data structures against concurrent accesses\&.
The typical use is (if 
.ft B
m
.ft R
is the mutex associated with the data structure
.ft B
D
.ft R
):
.EX
.ft B
.br
\&     Mutex\&.lock m;
.br
\&     (* Critical section that operates over D *);
.br
\&     Mutex\&.unlock m
.br
\&   
.ft R
.EE

.sp

.sp
.sp
.I type t 

.sp
The type of mutexes\&.

.sp

.I val create 
: 
.B unit -> t
.sp
Return a new mutex\&.

.sp

.I val lock 
: 
.B t -> unit
.sp
Lock the given mutex\&. Only one thread can have the mutex locked
at any time\&. A thread that attempts to lock a mutex already locked
by another thread will suspend until the other thread unlocks
the mutex\&.

.sp
.B "Before4.12"

.ft B
Sys_error
.ft R
was not raised for recursive locking
(platform\-dependent behaviour)


.sp
.B "Raises Sys_error"
if the mutex is already locked by the thread calling
.ft B
Mutex\&.lock
.ft R
\&.

.sp

.I val try_lock 
: 
.B t -> bool
.sp
Same as 
.ft B
Mutex\&.lock
.ft R
, but does not suspend the calling thread if
the mutex is already locked: just return 
.ft B
false
.ft R
immediately
in that case\&. If the mutex is unlocked, lock it and
return 
.ft B
true
.ft R
\&.

.sp

.I val unlock 
: 
.B t -> unit
.sp
Unlock the given mutex\&. Other threads suspended trying to lock
the mutex will restart\&.  The mutex must have been previously locked
by the thread that calls 
.ft B
Mutex\&.unlock
.ft R
\&.

.sp
.B "Before4.12"

.ft B
Sys_error
.ft R
was not raised when unlocking an unlocked mutex
or when unlocking a mutex from a different thread\&.


.sp
.B "Raises Sys_error"
if the mutex is unlocked or was locked by another thread\&.

.sp