Copyright	(c) The University of Glasgow 2001
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	libraries@haskell.org
Stability	experimental
Portability	non-portable (concurrency)
Safe Haskell	Trustworthy
Language	Haskell2010

Control.Concurrent.MVar

Contents

MVars

Description

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:

As synchronized mutable variables,
As channels, with takeMVar and putMVar as receive and send, and
As a binary semaphore MVar (), 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.)

Applicability

MVars offer more flexibility than IORefs, 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 (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.

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, 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 ()

`MVar`s

data MVar a #

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.

Instances

Eq (MVar a) #	Since: base-4.1.0.0
Instance details Defined in GHC.MVar Methods (==) :: MVar a -> MVar a -> Bool Source # (/=) :: MVar a -> MVar a -> Bool Source #

newEmptyMVar :: IO (MVar a) #

Create an MVar which is initially empty.

newMVar :: a -> IO (MVar a) #

Create an MVar which contains the supplied value.

takeMVar :: MVar a -> IO a #

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.
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 using MVars.

putMVar :: MVar a -> a -> IO () #

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.
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 using MVars.

readMVar :: MVar a -> IO a #

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.

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 #

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) #

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 #

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 #

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 #

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 #

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 () #

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 #

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 () #

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 #

Like modifyMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

Since: base-4.6.0.0

tryReadMVar :: MVar a -> IO (Maybe a) #

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: base-4.7.0.0

mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a)) #

Make a Weak pointer to an MVar, using the second argument as a finalizer to run when MVar is garbage-collected

Since: base-4.6.0.0

addMVarFinalizer :: MVar a -> IO () -> IO () #

Deprecated: use mkWeakMVar instead

Applicability

Fairness

Gotchas

Ordering

Example

MVars

`MVar`s