GHC.MVar

base-4.16.0.0: Basic libraries

Copyright | (c) The University of Glasgow 2008
License | see libraries/base/LICENSE
Maintainer | cvs-ghc@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | Unsafe
Language | Haskell2010

GHC.MVar

Contents

- MVars

Description

The MVar type

Synopsis

- data MVar a = MVar (MVar# RealWorld a)
- newMVar :: a -> IO (MVar a)
- newEmptyMVar :: IO (MVar a)
- takeMVar :: MVar a -> IO a
- readMVar :: MVar a -> IO a
- putMVar :: MVar a -> a -> IO ()
- tryTakeMVar :: MVar a -> IO (Maybe a)
- tryPutMVar :: MVar a -> a -> IO Bool
- tryReadMVar :: MVar a -> IO (Maybe a)
- isEmptyMVar :: MVar a -> IO Bool
- addMVarFinalizer :: MVar a -> IO () -> IO ()

# MVars

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 box, which may be empty or full.

Constructors

MVar (MVar# RealWorld a) |

#### Instances

Instances details

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 #

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

Create an `MVar` which contains the supplied value.

newEmptyMVar :: IO (MVar a) Source #

Create an `MVar` which is initially empty.

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.

readMVar :: MVar a -> IO a Source #

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

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.

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.

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

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.

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.