base-4.3.1.0: Basic libraries

Portability | non-portable (concurrency)
Stability | experimental
Maintainer | libraries@haskell.org

Control.Concurrent.MVar

Contents

- `MVar`s

Description

Synchronising variables

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
- modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
- modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b
- 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 a box, which may be empty or full.

Instances

Typeable1 MVar |
Eq (MVar a) |

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 `MVar`s.

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 `MVar`s.

readMVar :: MVar a -> IO a

This is a combination of `takeMVar` and `putMVar`; ie. it takes the value from the `MVar`, puts it back, and also returns it.

swapMVar :: MVar a -> a -> IO a

Take a value from an `MVar`, put a new value into the `MVar` and return the value taken. Note that there is a race condition whereby another process can put something in the `MVar` after the take happens but before the put does.

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

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 b

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

Add a finalizer to an `MVar` (GHC only). See Foreign.ForeignPtr and System.Mem.Weak for more about finalizers.