Safe Haskell	Safe-Inferred
Language	Haskell2010

Control.Concurrent.Extra

Contents

Lock
Var
Barrier

Description

Extra functions for Control.Concurrent.

This module includes three new types of MVar, namely Lock (no associated value), Var (never empty) and Barrier (filled at most once). See this blog post for examples and justification.

If you need greater control of exceptions and threads see the slave-thread package. If you need elaborate relationships between threads see the async package.

Synopsis

throwTo :: Exception e => ThreadId -> e -> IO ()
data MVar a
putMVar :: MVar a -> a -> IO ()
takeMVar :: MVar a -> IO a
setNumCapabilities :: Int -> IO ()
data ThreadId
forkIO :: IO () -> IO ThreadId
forkIOWithUnmask :: ((forall a. IO a -> IO a) -> IO ()) -> IO ThreadId
forkOn :: Int -> IO () -> IO ThreadId
forkOnWithUnmask :: Int -> ((forall a. IO a -> IO a) -> IO ()) -> IO ThreadId
getNumCapabilities :: IO Int
killThread :: ThreadId -> IO ()
mkWeakThreadId :: ThreadId -> IO (Weak ThreadId)
modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
myThreadId :: IO ThreadId
threadCapability :: ThreadId -> IO (Int, Bool)
withMVar :: MVar a -> (a -> IO b) -> IO b
yield :: IO ()
rtsSupportsBoundThreads :: Bool
forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId
newMVar :: a -> IO (MVar a)
tryTakeMVar :: MVar a -> IO (Maybe a)
readMVar :: MVar a -> IO a
modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b
newEmptyMVar :: IO (MVar a)
tryPutMVar :: MVar a -> a -> IO Bool
tryReadMVar :: MVar a -> IO (Maybe a)
data Chan a
dupChan :: Chan a -> IO (Chan a)
getChanContents :: Chan a -> IO [a]
newChan :: IO (Chan a)
readChan :: Chan a -> IO a
writeChan :: Chan a -> a -> IO ()
writeList2Chan :: Chan a -> [a] -> IO ()
addMVarFinalizer :: MVar a -> IO () -> IO ()
mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a))
modifyMVarMasked :: MVar a -> (a -> IO (a, b)) -> IO b
modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO ()
swapMVar :: MVar a -> a -> IO a
withMVarMasked :: MVar a -> (a -> IO b) -> IO b
data QSem
newQSem :: Int -> IO QSem
signalQSem :: QSem -> IO ()
waitQSem :: QSem -> IO ()
data QSemN
newQSemN :: Int -> IO QSemN
signalQSemN :: QSemN -> Int -> IO ()
waitQSemN :: QSemN -> Int -> IO ()
threadDelay :: Int -> IO ()
threadWaitRead :: Fd -> IO ()
threadWaitReadSTM :: Fd -> IO (STM (), IO ())
threadWaitWrite :: Fd -> IO ()
threadWaitWriteSTM :: Fd -> IO (STM (), IO ())
isEmptyMVar :: MVar a -> IO Bool
forkOS :: IO () -> IO ThreadId
forkOSWithUnmask :: ((forall a. IO a -> IO a) -> IO ()) -> IO ThreadId
isCurrentThreadBound :: IO Bool
runInBoundThread :: IO a -> IO a
runInUnboundThread :: IO a -> IO a
withNumCapabilities :: Int -> IO a -> IO a
once :: IO a -> IO (IO a)
onceFork :: IO a -> IO (IO a)
data Lock
newLock :: IO Lock
withLock :: Lock -> IO a -> IO a
withLockTry :: Lock -> IO a -> IO (Maybe a)
data Var a
newVar :: a -> IO (Var a)
readVar :: Var a -> IO a
writeVar :: Var a -> a -> IO ()
writeVar' :: Var a -> a -> IO ()
modifyVar :: Var a -> (a -> IO (a, b)) -> IO b
modifyVar' :: Var a -> (a -> IO (a, b)) -> IO b
modifyVar_ :: Var a -> (a -> IO a) -> IO ()
modifyVar_' :: Var a -> (a -> IO a) -> IO ()
withVar :: Var a -> (a -> IO b) -> IO b
data Barrier a
newBarrier :: IO (Barrier a)
signalBarrier :: Partial => Barrier a -> a -> IO ()
waitBarrier :: Barrier a -> IO a
waitBarrierMaybe :: Barrier a -> IO (Maybe a)

Documentation

throwTo :: Exception e => ThreadId -> e -> IO () #

data MVar a #

Instances

Instances details

NFData1 MVar
Instance details Defined in Control.DeepSeq Methods liftRnf :: (a -> ()) -> MVar a -> ()
NFData (MVar a)
Instance details Defined in Control.DeepSeq Methods rnf :: MVar a -> ()
Eq (MVar a)
Instance details Defined in GHC.MVar Methods (==) :: MVar a -> MVar a -> Bool (/=) :: MVar a -> MVar a -> Bool

putMVar :: MVar a -> a -> IO () #

takeMVar :: MVar a -> IO a #

setNumCapabilities :: Int -> IO () #

data ThreadId #

Instances

Instances details

Show ThreadId
Instance details Defined in GHC.Conc.Sync Methods showsPrec :: Int -> ThreadId -> ShowS show :: ThreadId -> String showList :: [ThreadId] -> ShowS
NFData ThreadId
Instance details Defined in Control.DeepSeq Methods rnf :: ThreadId -> ()
Eq ThreadId
Instance details Defined in GHC.Conc.Sync Methods (==) :: ThreadId -> ThreadId -> Bool (/=) :: ThreadId -> ThreadId -> Bool
Ord ThreadId
Instance details Defined in GHC.Conc.Sync Methods compare :: ThreadId -> ThreadId -> Ordering (<) :: ThreadId -> ThreadId -> Bool (<=) :: ThreadId -> ThreadId -> Bool (>) :: ThreadId -> ThreadId -> Bool (>=) :: ThreadId -> ThreadId -> Bool max :: ThreadId -> ThreadId -> ThreadId min :: ThreadId -> ThreadId -> ThreadId

forkIO :: IO () -> IO ThreadId #

forkIOWithUnmask :: ((forall a. IO a -> IO a) -> IO ()) -> IO ThreadId #

forkOn :: Int -> IO () -> IO ThreadId #

forkOnWithUnmask :: Int -> ((forall a. IO a -> IO a) -> IO ()) -> IO ThreadId #

getNumCapabilities :: IO Int #

killThread :: ThreadId -> IO () #

mkWeakThreadId :: ThreadId -> IO (Weak ThreadId) #

modifyMVar_ :: MVar a -> (a -> IO a) -> IO () #

myThreadId :: IO ThreadId #

threadCapability :: ThreadId -> IO (Int, Bool) #

withMVar :: MVar a -> (a -> IO b) -> IO b #

yield :: IO () #

rtsSupportsBoundThreads :: Bool #

forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId #

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

tryTakeMVar :: MVar a -> IO (Maybe a) #

readMVar :: MVar a -> IO a #

modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b #

newEmptyMVar :: IO (MVar a) #

tryPutMVar :: MVar a -> a -> IO Bool #

tryReadMVar :: MVar a -> IO (Maybe a) #

data Chan a #

Instances

Instances details

Eq (Chan a)
Instance details Defined in Control.Concurrent.Chan Methods (==) :: Chan a -> Chan a -> Bool (/=) :: Chan a -> Chan a -> Bool

dupChan :: Chan a -> IO (Chan a) #

getChanContents :: Chan a -> IO [a] #

newChan :: IO (Chan a) #

readChan :: Chan a -> IO a #

writeChan :: Chan a -> a -> IO () #

writeList2Chan :: Chan a -> [a] -> IO () #

addMVarFinalizer :: MVar a -> IO () -> IO () #

mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a)) #

modifyMVarMasked :: MVar a -> (a -> IO (a, b)) -> IO b #

modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO () #

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

withMVarMasked :: MVar a -> (a -> IO b) -> IO b #

data QSem #

newQSem :: Int -> IO QSem #

signalQSem :: QSem -> IO () #

waitQSem :: QSem -> IO () #

data QSemN #

newQSemN :: Int -> IO QSemN #

signalQSemN :: QSemN -> Int -> IO () #

waitQSemN :: QSemN -> Int -> IO () #

threadDelay :: Int -> IO () #

threadWaitRead :: Fd -> IO () #

threadWaitReadSTM :: Fd -> IO (STM (), IO ()) #

threadWaitWrite :: Fd -> IO () #

threadWaitWriteSTM :: Fd -> IO (STM (), IO ()) #

isEmptyMVar :: MVar a -> IO Bool #

forkOS :: IO () -> IO ThreadId #

forkOSWithUnmask :: ((forall a. IO a -> IO a) -> IO ()) -> IO ThreadId #

isCurrentThreadBound :: IO Bool #

runInBoundThread :: IO a -> IO a #

runInUnboundThread :: IO a -> IO a #

withNumCapabilities :: Int -> IO a -> IO a Source #

On GHC 7.6 and above with the -threaded flag, brackets a call to setNumCapabilities. On lower versions (which lack setNumCapabilities) this function just runs the argument action.

once :: IO a -> IO (IO a) Source #

Given an action, produce a wrapped action that runs at most once. If the function raises an exception, the same exception will be reraised each time.

let x ||| y = do t1 <- onceFork x; t2 <- onceFork y; t1; t2
\(x :: IO Int) -> void (once x) == pure ()
\(x :: IO Int) -> join (once x) == x
\(x :: IO Int) -> (do y <- once x; y; y) == x
\(x :: IO Int) -> (do y <- once x; y ||| y) == x

onceFork :: IO a -> IO (IO a) Source #

Like once, but immediately starts running the computation on a background thread.

\(x :: IO Int) -> join (onceFork x) == x
\(x :: IO Int) -> (do a <- onceFork x; a; a) == x

Lock

data Lock Source #

Like an MVar, but has no value. Used to guarantee single-threaded access, typically to some system resource. As an example:

lock <- newLock
let output = withLock lock . putStrLn
forkIO $ do ...; output "hello"
forkIO $ do ...; output "world"

Here we are creating a lock to ensure that when writing output our messages do not get interleaved. This use of MVar never blocks on a put. It is permissible, but rare, that a withLock contains a withLock inside it - but if so, watch out for deadlocks.

newLock :: IO Lock Source #

Create a new Lock.

withLock :: Lock -> IO a -> IO a Source #

Perform some operation while holding Lock. Will prevent all other operations from using the Lock while the action is ongoing.

withLockTry :: Lock -> IO a -> IO (Maybe a) Source #

Like withLock but will never block. If the operation cannot be executed immediately it will return Nothing.

Var

data Var a Source #

Like an MVar, but must always be full. Used to operate on a mutable variable in a thread-safe way. As an example:

hits <- newVar 0
forkIO $ do ...; modifyVar_ hits (+1); ...
i <- readVar hits
print ("HITS",i)

Here we have a variable which we modify atomically, so modifications are not interleaved. This use of MVar never blocks on a put. No modifyVar operation should ever block, and they should always complete in a reasonable timeframe. A Var should not be used to protect some external resource, only the variable contained within. Information from a readVar should not be subsequently inserted back into the Var.

newVar :: a -> IO (Var a) Source #

Create a new Var with a value.

readVar :: Var a -> IO a Source #

Read the current value of the Var.

writeVar :: Var a -> a -> IO () Source #

Write a value to become the new value of Var.

writeVar' :: Var a -> a -> IO () Source #

Strict variant of writeVar

modifyVar :: Var a -> (a -> IO (a, b)) -> IO b Source #

Modify a Var producing a new value and a return result.

modifyVar' :: Var a -> (a -> IO (a, b)) -> IO b Source #

Strict variant of modifyVar'

modifyVar_ :: Var a -> (a -> IO a) -> IO () Source #

Modify a Var, a restricted version of modifyVar.

modifyVar_' :: Var a -> (a -> IO a) -> IO () Source #

Strict variant of modifyVar_

withVar :: Var a -> (a -> IO b) -> IO b Source #

Perform some operation using the value in the Var, a restricted version of modifyVar.

Barrier

data Barrier a Source #

Starts out empty, then is filled exactly once. As an example:

bar <- newBarrier
forkIO $ do ...; val <- ...; signalBarrier bar val
print =<< waitBarrier bar

Here we create a barrier which will contain some computed value. A thread is forked to fill the barrier, while the main thread waits for it to complete. A barrier has similarities to a future or promise from other languages, has been known as an IVar in other Haskell work, and in some ways is like a manually managed thunk.

newBarrier :: IO (Barrier a) Source #

Create a new Barrier.

signalBarrier :: Partial => Barrier a -> a -> IO () Source #

Write a value into the Barrier, releasing anyone at waitBarrier. Any subsequent attempts to signal the Barrier will throw an exception.

waitBarrier :: Barrier a -> IO a Source #

Wait until a barrier has been signaled with signalBarrier.

waitBarrierMaybe :: Barrier a -> IO (Maybe a) Source #

A version of waitBarrier that never blocks, returning Nothing if the barrier has not yet been signaled.