Copyright | (c) The University of Glasgow 2001 |
---|---|
License | BSD-style (see the file libraries/base/LICENSE) |
Maintainer | [email protected] |
Stability | experimental |
Portability | non-portable (concurrency) |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
An MVar t
is mutable location that is either empty or contains a value of type t
. 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:
takeMVar
and putMVar
as receive and send, andMVar ()
, with takeMVar
and putMVar
as 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.)
MVar
s offer more flexibility than IORef
s, but less flexibility than STM
. They are appropriate for building synchronization primitives and performing simple interthread communication; however they are very simple and susceptible to race conditions, deadlocks or uncaught exceptions. Do not use them if you need perform larger atomic operations such as reading from multiple variables: use STM
instead.
In particular, the "bigger" functions in this module (readMVar
, swapMVar
, withMVar
, modifyMVar_
and modifyMVar
) are simply the composition of a takeMVar
followed by a putMVar
with exception safety. These only have atomicity guarantees if all other threads perform a takeMVar
before a putMVar
as well; otherwise, they may block.
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, but this is not guaranteed in the semantics.
Like many other Haskell data structures, MVar
s 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.
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.
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 MVar
s. 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 MVar
s being used to build higher-level synchronization primitives, see Chan
and QSem
.
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.
newMVar :: a -> IO (MVar a) Source
Create an MVar
which contains the supplied value.
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
:
takeMVar
is single-wakeup. That is, if there are multiple threads blocked in takeMVar
, and the MVar
becomes full, only one thread will be woken up. The runtime guarantees that the woken thread completes its takeMVar
operation.MVar
, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built using MVar
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 in putMVar
, and the MVar
becomes empty, only one thread will be woken up. The runtime guarantees that the woken thread completes its putMVar
operation.MVar
, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built using MVar
s.readMVar :: MVar a -> IO a Source
Atomically read the contents of an MVar
. If the MVar
is currently empty, readMVar
will wait until its 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.
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
.
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 a
if the MVar
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
.
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: 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
.
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: 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: 4.6.0.0
tryReadMVar :: MVar a -> IO (Maybe a) Source
A non-blocking version of readMVar
. The tryReadMVar
function returns immediately, with Nothing
if the MVar
was empty, or Just a
if the MVar
was full with contents a
.
Since: 4.7.0.0
mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a)) Source
Make a Weak
pointer to an MVar
, using the second argument as a finalizer to run when MVar
is garbage-collected
Since: 4.6.0.0
addMVarFinalizer :: MVar a -> IO () -> IO () Source
Deprecated: use mkWeakMVar
instead
© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/8.2.1/docs/html/libraries/base-4.10.0.0/Control-Concurrent-MVar.html