Moduleconcurrency-1.11.0.3Haskell2010

Control.Monad.Conc.Class

This module captures in a typeclass the interface of concurrency monads.

Deviations: An instance of MonadConc is not required to be an instance of MonadFix, unlike IO. The IORef, MVar, and Ticket types are not required to be instances of Show or Eq, unlike their normal counterparts. The threadCapability, threadWaitRead, threadWaitWrite, threadWaitReadSTM, threadWaitWriteSTM, and mkWeakThreadId functions are not provided. The threadDelay function is not required to delay the thread, merely to yield it. The BlockedIndefinitelyOnMVar (and similar) exceptions are not thrown during testing, so do not rely on them at all.

1 type
1 class
27 values

Packageconcurrency-1.11.0.3
Exports29
LanguageHaskell2010
LicenceMIT
SourceClass.hs

class

class (Monad m, MonadCatch m, MonadThrow m, MonadMask m, MonadSTM (STM m), Ord (ThreadId m), Show (ThreadId m)) => MonadConc (m :: Type -> Type) where

MonadConc is an abstraction over GHC's typical concurrency abstraction. It captures the interface of concurrency monads in terms of how they can operate on shared state and in the presence of exceptions.

Every MonadConc has an associated MonadSTM, transactions of which can be run atomically.

Deriving instances: If you have a newtype wrapper around a type with an existing MonadConc instance, you should be able to derive an instance for your type automatically, in simple cases.

For example:

{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE StandaloneDeriving #-}
{-# LANGUAGE UndecidableInstances #-}

data Env = Env

newtype MyMonad m a = MyMonad { runMyMonad :: ReaderT Env m a }
  deriving (Functor, Applicative, Monad)

deriving instance MonadThrow m => MonadThrow (MyMonad m)
deriving instance MonadCatch m => MonadCatch (MyMonad m)
deriving instance MonadMask  m => MonadMask  (MyMonad m)

deriving instance MonadConc m => MonadConc (MyMonad m)

Do not be put off by the use of UndecidableInstances, it is safe here.

Associated types

type family STM (m :: Type -> Type) :: Type -> Type
The associated MonadSTM for this class.
type family MVar (m :: Type -> Type) :: Type -> Type
The mutable reference type, like MVars. This may contain one value at a time, attempting to read or take from an "empty" MVar will block until it is full, and attempting to put to a "full" MVar will block until it is empty.
type family IORef (m :: Type -> Type) :: Type -> Type
The mutable non-blocking reference type. These may suffer from relaxed memory effects if functions outside the set newIORef, readIORef, atomicModifyIORef, and atomicWriteIORef are used.
type family Ticket (m :: Type -> Type) :: Type -> Type
When performing compare-and-swap operations on IORefs, a Ticket is a proof that a thread observed a specific previous value.
type family ThreadId (m :: Type -> Type)
An abstract handle to a thread.

Methods

forkWithUnmask :: ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)
Like fork, but the child thread is passed a function that can be used to unmask asynchronous exceptions. This function should not be used within a mask or uninterruptibleMask.
```
forkWithUnmask = forkWithUnmaskN ""
```
forkWithUnmaskN :: String -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)
Like forkWithUnmask, but the thread is given a name which may be used to present more useful debugging information.
```
forkWithUnmaskN _ = forkWithUnmask
```
forkOnWithUnmask :: Int -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)
Like forkWithUnmask, but the child thread is pinned to the given CPU, as with forkOn.
```
forkOnWithUnmask = forkOnWithUnmaskN ""
```
forkOnWithUnmaskN :: String -> Int -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)
Like forkWithUnmaskN, but the child thread is pinned to the given CPU, as with forkOn.
```
forkOnWithUnmaskN _ = forkOnWithUnmask
```
forkOSWithUnmask :: ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)
Like forkOS, but the child thread is passed a function that can be used to unmask asynchronous exceptions. This function should not be used within a mask or uninterruptibleMask.
```
forkOSWithUnmask = forkOSWithUnmaskN ""
```
forkOSWithUnmaskN :: String -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)
Like forkOSWithUnmask, but the thread is given a name which may be used to present more useful debugging information.
```
forkOSWithUnmaskN _ = forkOSWithUnmask
```
supportsBoundThreads :: m Bool
Returns True if bound threads can be forked. If False, isCurrentThreadBound will always return False and both forkOS and runInBoundThread will fail.
isCurrentThreadBound :: m Bool
Returns True if the calling thread is bound, that is, if it is safe to use foreign libraries that rely on thread-local state from the calling thread.
This will always be false if your program is not compiled with the threaded runtime.
getNumCapabilities :: m Int
Get the number of Haskell threads that can run simultaneously.
setNumCapabilities :: Int -> m ()
Set the number of Haskell threads that can run simultaneously.
myThreadId :: m (ThreadId m)
Get the ThreadId of the current thread.
yield :: m ()
Allows a context-switch to any other unblocked thread (if any).
threadDelay :: Int -> m ()
Yields the current thread, and optionally suspends the current thread for a given number of microseconds.
If suspended, there is no guarantee that the thread will be rescheduled promptly when the delay has expired, but the thread will never continue to run earlier than specified.
```
threadDelay _ = yield
```
newEmptyMVar :: m (MVar m a)
Create a new empty MVar.
```
newEmptyMVar = newEmptyMVarN ""
```
newEmptyMVarN :: String -> m (MVar m a)
Create a new empty MVar, but it is given a name which may be used to present more useful debugging information.
```
newEmptyMVarN _ = newEmptyMVar
```
putMVar :: MVar m a -> a -> m ()
Put a value into a MVar. If there is already a value there, this will block until that value has been taken, at which point the value will be stored.
tryPutMVar :: MVar m a -> a -> m Bool
Attempt to put a value in a MVar non-blockingly, returning True (and filling the MVar) if there was nothing there, otherwise returning False.
readMVar :: MVar m a -> m a
Block until a value is present in the MVar, and then return it. This does not "remove" the value, multiple reads are possible.
tryReadMVar :: MVar m a -> m (Maybe a)
Attempt to read a value from a MVar non-blockingly, returning a Just if there is something there, otherwise returning Nothing. As with readMVar, this does not "remove" the value.
takeMVar :: MVar m a -> m a
Take a value from a MVar. This "empties" the MVar, allowing a new value to be put in. This will block if there is no value in the MVar already, until one has been put.
tryTakeMVar :: MVar m a -> m (Maybe a)
Attempt to take a value from a MVar non-blockingly, returning a Just (and emptying the MVar) if there was something there, otherwise returning Nothing.
newIORef :: a -> m (IORef m a)
Create a new reference.
```
newIORef = newIORefN ""
```
newIORefN :: String -> a -> m (IORef m a)
Create a new reference, but it is given a name which may be used to present more useful debugging information.
```
newIORefN _ = newIORef
```
readIORef :: IORef m a -> m a
Read the current value stored in a reference.
```
readIORef ioref = readForCAS ioref >>= peekTicket
```
atomicModifyIORef :: IORef m a -> (a -> (a, b)) -> m b
Atomically modify the value stored in a reference. This imposes a full memory barrier.
writeIORef :: IORef m a -> a -> m ()
Write a new value into an IORef, without imposing a memory barrier. This means that relaxed memory effects can be observed.
atomicWriteIORef :: IORef m a -> a -> m ()
Replace the value stored in a reference, with the barrier-to-reordering property that atomicModifyIORef has.
```
atomicWriteIORef r a = atomicModifyIORef r $ const (a, ())
```
readForCAS :: IORef m a -> m (Ticket m a)
Read the current value stored in a reference, returning a Ticket, for use in future compare-and-swap operations.
peekTicket' :: Proxy m -> Ticket m a -> a
Extract the actual Haskell value from a Ticket.
The Proxy m is to determine the m in the Ticket type.
casIORef :: IORef m a -> Ticket m a -> a -> m (Bool, Ticket m a)
Perform a machine-level compare-and-swap (CAS) operation on a IORef. Returns an indication of success and a Ticket for the most current value in the IORef.
This is strict in the "new" value argument.
modifyIORefCAS :: IORef m a -> (a -> (a, b)) -> m b
A replacement for atomicModifyIORef using a compare-and-swap.
This is strict in the "new" value argument.
modifyIORefCAS_ :: IORef m a -> (a -> a) -> m ()
A variant of modifyIORefCAS which doesn't return a result.
```
modifyIORefCAS_ ioref f = modifyIORefCAS ioref (\a -> (f a, ()))
```
atomically :: STM m a -> m a
Perform an STM transaction atomically.
newTVarConc :: a -> m (TVar (STM m) a)
Create a TVar. This may be implemented differently for speed.
```
newTVarConc = atomically . newTVar
```
readTVarConc :: TVar (STM m) a -> m a
Read the current value stored in a TVar. This may be implemented differently for speed.
```
readTVarConc = atomically . readTVar
```
throwTo :: Exception e => ThreadId m -> e -> m ()
Throw an exception to the target thread. This blocks until the exception is delivered, and it is just as if the target thread had raised it with throw. This can interrupt a blocked action.
getMaskingState :: m MaskingState
Return the MaskingState for the current thread.
unsafeUnmask :: m a -> m a
Set the MaskingState for the current thread to MaskedUninterruptible.

Instances10MonadConc, …

MonadConc IODefined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadConc m => MonadConc (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadConc m => MonadConc (IdentityT m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadConc m => MonadConc (ReaderT r m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
New threads inherit the reader state of their parent, but do not communicate results back.
MonadConc m => MonadConc (StateT s m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
New threads inherit the state of their parent, but do not communicate results back.
MonadConc m => MonadConc (StateT s m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
New threads inherit the state of their parent, but do not communicate results back.
(MonadConc m, Monoid w) => MonadConc (WriterT w m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
New threads inherit the writer state of their parent, but do not communicate results back.
(MonadConc m, Monoid w) => MonadConc (WriterT w m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
New threads inherit the writer state of their parent, but do not communicate results back.
(MonadConc m, Monoid w) => MonadConc (RWST r w s m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
New threads inherit the states of their parent, but do not communicate results back.
(MonadConc m, Monoid w) => MonadConc (RWST r w s m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
New threads inherit the states of their parent, but do not communicate results back.

Threads

6 declarations

valuefork :: MonadConc m => m () -> m (ThreadId m)

Fork a computation to happen concurrently. Communication may happen over MVars.

valueforkOn :: MonadConc m => Int -> m () -> m (ThreadId m)

Fork a computation to happen on a specific processor. The specified int is the capability number, typically capabilities correspond to physical processors or cores but this is implementation dependent. The int is interpreted modulo to the total number of capabilities as returned by getNumCapabilities.

valueforkOS :: MonadConc m => m () -> m (ThreadId m)

Fork a computation to happen in a bound thread, which is necessary if you need to call foreign (non-Haskell) libraries that make use of thread-local state, such as OpenGL.

valueforkFinally

:: MonadConc m
=> m a
-> Either SomeException a -> m ()
-> m (ThreadId m)

Fork a thread and call the supplied function when the thread is about to terminate, with an exception or a returned value. The function is called with asynchronous exceptions masked.

This function is useful for informing the parent when a child terminates, for example.

valuespawn :: MonadConc m => m a -> m (MVar m a)

Create a concurrent computation for the provided action, and return a MVar which can be used to query the result.

valuekillThread :: MonadConc m => ThreadId m -> m ()

Raise the ThreadKilled exception in the target thread. Note that if the thread is prepared to catch this exception, it won't actually kill it.

Bound threads

Support for multiple operating system threads and bound threads as described below is currently only available in the GHC runtime system if you use the -threaded option when linking.

Other Haskell systems do not currently support multiple operating system threads.

A bound thread is a haskell thread that is bound to an operating system thread. While the bound thread is still scheduled by the Haskell run-time system, the operating system thread takes care of all the foreign calls made by the bound thread.

To a foreign library, the bound thread will look exactly like an ordinary operating system thread created using OS functions like pthread_create or CreateThread.

valuertsSupportsBoundThreads :: Bool

Deprecated. Use supportsBoundThreads instead

True if bound threads are supported. If rtsSupportsBoundThreads is False, isCurrentThreadBound will always return False and both forkOS and runInBoundThread will fail.

Use supportsBoundThreads in MonadConc instead.

valuerunInBoundThread :: MonadConc m => m a -> m a

Run the computation passed as the first argument. If the calling thread is not bound, a bound thread is created temporarily. runInBoundThread doesn't finish until the inner computation finishes.

You can wrap a series of foreign function calls that rely on thread-local state with runInBoundThread so that you can use them without knowing whether the current thread is bound.

valuerunInUnboundThread :: MonadConc m => m a -> m a

Run the computation passed as the first argument. If the calling thread is bound, an unbound thread is created temporarily using fork. runInBoundThread doesn't finish until the inner computation finishes.

Use this function only in the rare case that you have actually observed a performance loss due to the use of bound threads. A program that doesn't need its main thread to be bound and makes heavy use of concurrency (e.g. a web server), might want to wrap its main action in runInUnboundThread.

Note that exceptions which are thrown to the current thread are thrown in turn to the thread that is executing the given computation. This ensures there's always a way of killing the forked thread.

Named Threads

valueforkN :: MonadConc m => String -> m () -> m (ThreadId m)

Like fork, but the thread is given a name which may be used to present more useful debugging information.

valueforkOnN :: MonadConc m => String -> Int -> m () -> m (ThreadId m)

Like forkOn, but the thread is given a name which may be used to present more useful debugging information.

valueforkOSN :: MonadConc m => String -> m () -> m (ThreadId m)

Like forkOS, but the thread is given a name which may be used to present more useful debugging information.

Exceptions

7 declarations

valuethrow :: (MonadConc m, Exception e) => e -> m a

Throw an exception. This will "bubble up" looking for an exception handler capable of dealing with it and, if one is not found, the thread is killed.

valuecatch :: (MonadConc m, Exception e) => m a -> (e -> m a) -> m a

Catch an exception. This is only required to be able to catch exceptions raised by throw, unlike the more general Control.Exception.catch function. If you need to be able to catch all errors, you will have to use IO.

valuemask :: MonadConc m => ((forall a. m a -> m a) -> m b) -> m b

Executes a computation with asynchronous exceptions masked. That is, any thread which attempts to raise an exception in the current thread with throwTo will be blocked until asynchronous exceptions are unmasked again.

The argument passed to mask is a function that takes as its argument another function, which can be used to restore the prevailing masking state within the context of the masked computation. This function should not be used within an uninterruptibleMask.

valuemask_ :: (HasCallStack, MonadMask m) => m a -> m a

Like mask, but does not pass a restore action to the argument.

valueuninterruptibleMask :: MonadConc m => ((forall a. m a -> m a) -> m b) -> m b

Like mask, but the masked computation is not interruptible. THIS SHOULD BE USED WITH GREAT CARE, because if a thread executing in uninterruptibleMask blocks for any reason, then the thread (and possibly the program, if this is the main thread) will be unresponsive and unkillable. This function should only be necessary if you need to mask exceptions around an interruptible operation, and you can guarantee that the interruptible operation will only block for a short period of time. The supplied unmasking function should not be used within a mask.

valueuninterruptibleMask_ :: (HasCallStack, MonadMask m) => m a -> m a

Like uninterruptibleMask, but does not pass a restore action to the argument.

valueinterruptible :: MonadConc m => m a -> m a

Allow asynchronous exceptions to be raised even inside mask, making the operation interruptible.

When called outside mask, or inside uninterruptibleMask, this function has no effect.

Mutable State

4 declarations

valuenewMVar :: MonadConc m => a -> m (MVar m a)

Create a new MVar containing a value.

valuenewMVarN :: MonadConc m => String -> a -> m (MVar m a)

Create a new MVar containing a value, but it is given a name which may be used to present more useful debugging information.

valuecas :: MonadConc m => IORef m a -> a -> m (Bool, a)

Compare-and-swap a value in a IORef, returning an indication of success and the new value.

valuepeekTicket :: MonadConc m => Ticket m a -> m a

Extract the actual Haskell value from a Ticket.

This doesn't do do any monadic computation, the m appears in the result type to determine the m in the Ticket type.

Utilities for type shenanigans

3 declarations

newtypenewtype IsConc (m :: k -> Type) (a :: k)

A value of type IsConc m a can only be constructed if m has a MonadConc instance.

Instances13Monad, Functor, MonadFail, Applicative, MonadCatch, MonadMask, …

Monad m => Monad (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
Functor m => Functor (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadFail m => MonadFail (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
Applicative m => Applicative (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadCatch m => MonadCatch (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadMask m => MonadMask (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadThrow m => MonadThrow (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
MonadConc m => MonadConc (IsConc m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
type IORef (IsConc m) = IORef mDefined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
type MVar (IsConc m) = MVar mDefined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
type STM (IsConc m) = IsSTM (STM m)Defined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
type ThreadId (IsConc m) = ThreadId mDefined in concurrency-1.11.0.3 · Control.Monad.Conc.Class
type Ticket (IsConc m) = Ticket mDefined in concurrency-1.11.0.3 · Control.Monad.Conc.Class

valuetoIsConc :: MonadConc m => m a -> IsConc m a

Wrap an m a value inside an IsConc if m has a MonadConc instance.

valuefromIsConc :: MonadConc m => IsConc m a -> m a

Unwrap an IsConc value.

Utilities for instance writers

2 declarations

valueliftedF

:: (MonadTransControl t, MonadConc m)
=> forall x. StT t x -> x
-> m a -> m b
-> t m a
-> t m b

Given a function to remove the transformer-specific state, lift a function invocation.

valueliftedFork

:: (MonadTransControl t, MonadConc m)
=> forall x. StT t x -> x
-> ((forall x. m x -> m x) -> m a) -> m b
-> (forall x. t m x -> t m x) -> t m a
-> t m b

Given a function to remove the transformer-specific state, lift a fork(on)WithUnmask invocation.