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 |
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
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.
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 intakeMVar
, and theMVar
becomes full, only one thread will be woken up. The runtime guarantees that the woken thread completes itstakeMVar
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 usingMVar
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 inputMVar
, and theMVar
becomes empty, only one thread will be woken up. The runtime guarantees that the woken thread completes itsputMVar
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 usingMVar
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
if the Just
aMVar
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.
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.