| Haskell Hierarchical Libraries (base package) | 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

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)
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
Swap the contents of an `MVar` for a new value.
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.
Produced by Haddock version 0.8