Portability | non-portable (concurrency) |
---|---|
Stability | experimental |
Maintainer | libraries@haskell.org |
Synchronising variables
- data MVar a
- newEmptyMVar :: IO (MVar a)
- newMVar :: a -> IO (MVar a)
- takeMVar :: MVar a -> IO a
- putMVar :: MVar a -> a -> IO ()
- readMVar :: MVar a -> IO a
- swapMVar :: MVar a -> a -> IO a
- tryTakeMVar :: MVar a -> IO (Maybe a)
- tryPutMVar :: MVar a -> a -> IO Bool
- isEmptyMVar :: MVar a -> IO Bool
- withMVar :: MVar a -> (a -> IO b) -> IO b
- modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
- modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b
- addMVarFinalizer :: MVar a -> IO () -> IO ()
MVar
s
An MVar
(pronounced "em-var") is a synchronising variable, used
for communication between concurrent threads. It can be thought of
as a a box, which may be empty or full.
newEmptyMVar :: IO (MVar a)Source
Create an MVar
which is initially empty.
takeMVar :: MVar a -> IO aSource
Return the contents of the MVar
. If the MVar
is currently
empty, takeMVar
will wait until it is full. After a takeMVar
,
the MVar
is left empty.
There are two further important properties of takeMVar
:
-
takeMVar
is single-wakeup. That is, if there are multiple threads blocked intakeMVar
, and theMVar
becomes full, only one thread will be woken up. The runtime guarantees that the woken thread completes itstakeMVar
operation. - When multiple threads are blocked on an
MVar
, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built usingMVar
s.
putMVar :: MVar a -> a -> IO ()Source
Put a value into an MVar
. If the MVar
is currently full,
putMVar
will wait until it becomes empty.
There are two further important properties of putMVar
:
-
putMVar
is single-wakeup. That is, if there are multiple threads blocked inputMVar
, and theMVar
becomes empty, only one thread will be woken up. The runtime guarantees that the woken thread completes itsputMVar
operation. - When multiple threads are blocked on an
MVar
, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built usingMVar
s.
tryTakeMVar :: MVar a -> IO (Maybe a)Source
A non-blocking version of takeMVar
. The tryTakeMVar
function
returns immediately, with Nothing
if the MVar
was empty, or
if the Just
aMVar
was full with contents a
. After tryTakeMVar
,
the MVar
is left empty.
tryPutMVar :: MVar a -> a -> IO BoolSource
A non-blocking version of putMVar
. The tryPutMVar
function
attempts to put the value a
into the MVar
, returning True
if
it was successful, or False
otherwise.
isEmptyMVar :: MVar a -> IO BoolSource
Check whether a given MVar
is empty.
Notice that the boolean value returned is just a snapshot of
the state of the MVar. By the time you get to react on its result,
the MVar may have been filled (or emptied) - so be extremely
careful when using this operation. Use tryTakeMVar
instead if possible.
withMVar :: MVar a -> (a -> IO b) -> IO bSource
withMVar
is a safe wrapper for operating on the contents of an
MVar
. This operation is exception-safe: it will replace the
original contents of the MVar
if an exception is raised (see
Control.Exception).
modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()Source
A safe wrapper for modifying the contents of an MVar
. Like withMVar
,
modifyMVar
will replace the original contents of the MVar
if an
exception is raised during the operation.
modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO bSource
A slight variation on modifyMVar_
that allows a value to be
returned (b
) in addition to the modified value of the MVar
.
addMVarFinalizer :: MVar a -> IO () -> IO ()Source
Add a finalizer to an MVar
(GHC only). See Foreign.ForeignPtr and
System.Mem.Weak for more about finalizers.