| base-3.0.1.0: Basic libraries | Source code | Contents | Index

Control.Concurrent.MVar |

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

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 | Source

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
Typeable a => Data (MVar a)
Eq (MVar a)

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

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 | Source

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) | 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 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 b | Source

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.
Produced by Haddock version 0.8