| Copyright | (c) The University of Glasgow 2001 |
|---|---|
| License | BSD-style (see the file libraries/base/LICENSE) |
| Maintainer | libraries@haskell.org |
| Stability | stable |
| Portability | non-portable (concurrency) |
| Safe Haskell | Safe |
| Language | Haskell2010 |
Control.Concurrent.MVar
Contents
Description
An MVar tt. It has two fundamental operations: putMVar
which fills an MVar if it is empty and blocks otherwise, and
takeMVar which empties an MVar if it is full and blocks
otherwise. They can be used in multiple different ways:
- As synchronized mutable variables,
- As channels, with
takeMVarandputMVaras receive and send, and - As a binary semaphore
MVar()takeMVarandputMVaras wait and signal.
They were introduced in the paper
"Concurrent Haskell"
by Simon Peyton Jones, Andrew Gordon and Sigbjorn Finne, though
some details of their implementation have since then changed (in
particular, a put on a full MVar used to error, but now merely
blocks.)
Applicability
MVars offer more flexibility than IORefs, but less flexibility
than STM. They are appropriate for building synchronization
primitives and performing simple inter-thread communication; however
they are very simple and susceptible to race conditions, deadlocks or
uncaught exceptions. Do not use them if you need to perform larger
atomic operations such as reading from multiple variables: use STM
instead.
In particular, the "bigger" functions in this module (swapMVar,
withMVar, modifyMVar_ and modifyMVar) are simply
the composition of a takeMVar followed by a putMVar with
exception safety.
These have atomicity guarantees only if all other threads
perform a takeMVar before a putMVar as well; otherwise, they may
block.
Fairness
No thread can be blocked indefinitely on an MVar unless another
thread holds that MVar indefinitely. One usual implementation of
this fairness guarantee is that threads blocked on an MVar are
served in a first-in-first-out fashion (this is what GHC does),
but this is not guaranteed in the semantics.
Gotchas
Like many other Haskell data structures, MVars are lazy. This
means that if you place an expensive unevaluated thunk inside an
MVar, it will be evaluated by the thread that consumes it, not the
thread that produced it. Be sure to evaluate values to be placed
in an MVar to the appropriate normal form, or utilize a strict
MVar provided by the strict-concurrency package.
Ordering
MVar operations are always observed to take place in the order
they are written in the program, regardless of the memory model of
the underlying machine. This is in contrast to IORef operations
which may appear out-of-order to another thread in some cases.
Example
Consider the following concurrent data structure, a skip channel.
This is a channel for an intermittent source of high bandwidth
information (for example, mouse movement events.) Writing to the
channel never blocks, and reading from the channel only returns the
most recent value, or blocks if there are no new values. Multiple
readers are supported with a dupSkipChan operation.
A skip channel is a pair of MVars. The first MVar contains the
current value, and a list of semaphores that need to be notified
when it changes. The second MVar is a semaphore for this particular
reader: it is full if there is a value in the channel that this
reader has not read yet, and empty otherwise.
data SkipChan a = SkipChan (MVar (a, [MVar ()])) (MVar ())
newSkipChan :: IO (SkipChan a)
newSkipChan = do
sem <- newEmptyMVar
main <- newMVar (undefined, [sem])
return (SkipChan main sem)
putSkipChan :: SkipChan a -> a -> IO ()
putSkipChan (SkipChan main _) v = do
(_, sems) <- takeMVar main
putMVar main (v, [])
mapM_ (\sem -> putMVar sem ()) sems
getSkipChan :: SkipChan a -> IO a
getSkipChan (SkipChan main sem) = do
takeMVar sem
(v, sems) <- takeMVar main
putMVar main (v, sem : sems)
return v
dupSkipChan :: SkipChan a -> IO (SkipChan a)
dupSkipChan (SkipChan main _) = do
sem <- newEmptyMVar
(v, sems) <- takeMVar main
putMVar main (v, sem : sems)
return (SkipChan main sem)
This example was adapted from the original Concurrent Haskell paper.
For more examples of MVars being used to build higher-level
synchronization primitives, see Chan and
QSem.
Synopsis
- 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
- withMVarMasked :: MVar a -> (a -> IO b) -> IO b
- modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
- modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b
- modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO ()
- modifyMVarMasked :: MVar a -> (a -> IO (a, b)) -> IO b
- tryReadMVar :: MVar a -> IO (Maybe a)
- mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a))
- addMVarFinalizer :: MVar a -> IO () -> IO ()
MVars
An MVar (pronounced "em-var") is a synchronising variable, used
for communication between concurrent threads. It can be thought of
as a box, which may be empty or full.
takeMVar :: MVar a -> IO a Source #
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:
takeMVaris single-wakeup. That is, if there are multiple threads blocked intakeMVar, and theMVarbecomes full, only one thread will be woken up. The runtime guarantees that the woken thread completes itstakeMVaroperation.- 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 usingMVars.
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:
putMVaris single-wakeup. That is, if there are multiple threads blocked inputMVar, and theMVarbecomes empty, only one thread will be woken up. The runtime guarantees that the woken thread completes itsputMVaroperation.- 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 usingMVars.
readMVar :: MVar a -> IO a Source #
Atomically read the contents of an MVar. If the MVar is
currently empty, readMVar will wait until it is full.
readMVar is guaranteed to receive the next putMVar.
readMVar is multiple-wakeup, so when multiple readers are
blocked on an MVar, all of them are woken up at the same time.
The runtime guarantees that all woken threads complete their readMVar operation.
Compatibility note: Prior to base 4.7, readMVar was a combination
of takeMVar and putMVar. This mean that in the presence of
other threads attempting to putMVar, readMVar could block.
Furthermore, readMVar would not receive the next putMVar if there
was already a pending thread blocked on takeMVar. The old behavior
can be recovered by implementing 'readMVar as follows:
readMVar :: MVar a -> IO a
readMVar m =
mask_ $ do
a <- takeMVar m
putMVar m a
return a
swapMVar :: MVar a -> a -> IO a Source #
Take a value from an MVar, put a new value into the MVar and
return the value taken. This function is atomic only if there are
no other producers for this MVar. In other words, it cannot guarantee
that, by the time swapMVar gets the chance to write to the MVar,
the value of the MVar has not been altered
by a write operation from another thread.
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
Just aMVar was full with contents a. After tryTakeMVar,
the MVar is left empty.
tryPutMVar :: MVar a -> a -> IO Bool Source #
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 Bool Source #
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 b Source #
withMVar is an exception-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). However, it is only atomic if there are no
other producers for this MVar. In other words, it cannot guarantee
that, by the time withMVar gets the chance to write to the MVar,
the value of the MVar has not been altered
by a write operation from another thread.
withMVarMasked :: MVar a -> (a -> IO b) -> IO b Source #
Like withMVar, but the IO action in the second argument is executed
with asynchronous exceptions masked.
Since: base-4.7.0.0
modifyMVar_ :: MVar a -> (a -> IO a) -> IO () Source #
An exception-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. This
function is only atomic if there are no other producers for this
MVar. In other words, it cannot guarantee that, by the time
modifyMVar_ gets the chance to write to the MVar, the value
of the MVar has not been altered by a write operation from another thread.
modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b Source #
A slight variation on modifyMVar_ that allows a value to be
returned (b) in addition to the modified value of the MVar.
modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO () Source #
Like modifyMVar_, but the IO action in the second argument is executed with
asynchronous exceptions masked.
Since: base-4.6.0.0
modifyMVarMasked :: MVar a -> (a -> IO (a, b)) -> IO b Source #
Like modifyMVar, but the IO action in the second argument is executed with
asynchronous exceptions masked.
Since: base-4.6.0.0
addMVarFinalizer :: MVar a -> IO () -> IO () Source #
Deprecated: use mkWeakMVar instead