-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Typeclasses, functions, and data types for concurrency and STM.
--   
--   A typeclass abstraction over much of Control.Concurrent (and some
--   extras!). If you're looking for a general introduction to Haskell
--   concurrency, you should check out the excellent Parallel and
--   Concurrent Programming in Haskell, by Simon Marlow. If you are already
--   familiar with concurrent Haskell, just change all the imports from
--   Control.Concurrent.* to Control.Concurrent.Classy.* and fix the type
--   errors.
@package concurrency
@version 1.11.0.2


-- | This module provides an abstraction over <tt>STM</tt>, which can be
--   used with <tt>MonadConc</tt>.
--   
--   This module only defines the <tt>STM</tt> class; you probably want to
--   import <a>Control.Concurrent.Classy.STM</a> (which exports
--   <a>Control.Monad.STM.Class</a>).
--   
--   <b>Deriving instances:</b> If you have a newtype wrapper around a type
--   with an existing <tt>MonadSTM</tt> instance, you should be able to
--   derive an instance for your type automatically, in simple cases.
--   
--   For example:
--   
--   <pre>
--   {-# LANGUAGE GeneralizedNewtypeDeriving #-}
--   {-# LANGUAGE StandaloneDeriving #-}
--   {-# LANGUAGE UndecidableInstances #-}
--   
--   data Env = Env
--   
--   newtype MyMonad m a = MyMonad { runMyMonad :: ReaderT Env m a }
--     deriving (Functor, Applicative, Monad, Alternative, MonadPlus)
--   
--   deriving instance MonadThrow m =&gt; MonadThrow (MyMonad m)
--   deriving instance MonadCatch m =&gt; MonadCatch (MyMonad m)
--   
--   deriving instance MonadSTM m =&gt; MonadSTM (MyMonad m)
--   </pre>
--   
--   Do not be put off by the use of <tt>UndecidableInstances</tt>, it is
--   safe here.
--   
--   <b>Deviations:</b> An instance of <tt>MonadSTM</tt> is not required to
--   be a <tt>MonadFix</tt>, unlike <tt>STM</tt>.
module Control.Monad.STM.Class

-- | <tt>MonadSTM</tt> is an abstraction over <tt>STM</tt>.
--   
--   This class does not provide any way to run transactions, rather each
--   <tt>MonadConc</tt> has an associated <tt>MonadSTM</tt> from which it
--   can atomically run a transaction.
class (MonadCatch stm, MonadPlus stm) => MonadSTM stm where {
    
    -- | The mutable reference type. These behave like <a>TVar</a>s, in that
    --   they always contain a value and updates are non-blocking and
    --   synchronised.
    type family TVar stm :: Type -> Type;
}

-- | Create a new <tt>TVar</tt> containing the given value.
--   
--   <pre>
--   newTVar = newTVarN ""
--   </pre>
newTVar :: MonadSTM stm => a -> stm (TVar stm a)

-- | Create a new <tt>TVar</tt> containing the given value, but it is given
--   a name which may be used to present more useful debugging information.
--   
--   If an empty name is given, a counter starting from 0 is used. If names
--   conflict, successive <tt>TVar</tt>s with the same name are given a
--   numeric suffix, counting up from 1.
--   
--   <pre>
--   newTVarN _ = newTVar
--   </pre>
newTVarN :: MonadSTM stm => String -> a -> stm (TVar stm a)

-- | Return the current value stored in a <tt>TVar</tt>.
readTVar :: MonadSTM stm => TVar stm a -> stm a

-- | Write the supplied value into the <tt>TVar</tt>.
writeTVar :: MonadSTM stm => TVar stm a -> a -> stm ()

-- | Retry execution of this transaction because it has seen values in
--   <tt>TVar</tt>s that it shouldn't have. This will result in the thread
--   running the transaction being blocked until any <tt>TVar</tt>s
--   referenced in it have been mutated.
--   
--   This is just <a>mzero</a>.
retry :: MonadSTM stm => stm a

-- | Check whether a condition is true and, if not, call <tt>retry</tt>.
check :: MonadSTM stm => Bool -> stm ()

-- | Run the first transaction and, if it <tt>retry</tt>s, run the second
--   instead.
--   
--   This is just <a>mplus</a>.
orElse :: MonadSTM stm => stm a -> stm a -> stm a

-- | Throw an exception. This aborts the transaction and propagates the
--   exception.
throwSTM :: (MonadSTM stm, Exception e) => e -> stm a

-- | Handling exceptions from <a>throwSTM</a>.
catchSTM :: (MonadSTM stm, Exception e) => stm a -> (e -> stm a) -> stm a

-- | A value of type <tt>IsSTM m a</tt> can only be constructed if
--   <tt>m</tt> has a <tt>MonadSTM</tt> instance.
data IsSTM m a

-- | Wrap an <tt>m a</tt> value inside an <tt>IsSTM</tt> if <tt>m</tt> has
--   a <tt>MonadSTM</tt> instance.
toIsSTM :: MonadSTM m => m a -> IsSTM m a

-- | Unwrap an <tt>IsSTM</tt> value.
fromIsSTM :: MonadSTM m => IsSTM m a -> m a
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.STM.Class.IsSTM m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.STM.Class.IsSTM m)
instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Control.Monad.STM.Class.IsSTM m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.STM.Class.IsSTM m)
instance GHC.Base.Alternative m => GHC.Base.Alternative (Control.Monad.STM.Class.IsSTM m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.STM.Class.IsSTM m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.STM.Class.IsSTM m)
instance Control.Monad.Fail.MonadFail m => Control.Monad.Fail.MonadFail (Control.Monad.STM.Class.IsSTM m)
instance Control.Monad.STM.Class.MonadSTM m => Control.Monad.STM.Class.MonadSTM (Control.Monad.STM.Class.IsSTM m)
instance Control.Monad.STM.Class.MonadSTM GHC.Conc.Sync.STM
instance Control.Monad.STM.Class.MonadSTM stm => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.Reader.ReaderT r stm)
instance Control.Monad.STM.Class.MonadSTM stm => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.Identity.IdentityT stm)
instance (Control.Monad.STM.Class.MonadSTM stm, GHC.Base.Monoid w) => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.Writer.Lazy.WriterT w stm)
instance (Control.Monad.STM.Class.MonadSTM stm, GHC.Base.Monoid w) => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.Writer.Strict.WriterT w stm)
instance Control.Monad.STM.Class.MonadSTM stm => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.State.Lazy.StateT s stm)
instance Control.Monad.STM.Class.MonadSTM stm => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.State.Strict.StateT s stm)
instance (Control.Monad.STM.Class.MonadSTM stm, GHC.Base.Monoid w) => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.RWS.Lazy.RWST r w s stm)
instance (Control.Monad.STM.Class.MonadSTM stm, GHC.Base.Monoid w) => Control.Monad.STM.Class.MonadSTM (Control.Monad.Trans.RWS.Strict.RWST r w s stm)


-- | This module captures in a typeclass the interface of concurrency
--   monads.
--   
--   <b>Deviations:</b> An instance of <tt>MonadConc</tt> is not required
--   to be an instance of <tt>MonadFix</tt>, unlike <tt>IO</tt>. The
--   <tt>IORef</tt>, <tt>MVar</tt>, and <tt>Ticket</tt> types are not
--   required to be instances of <tt>Show</tt> or <tt>Eq</tt>, unlike their
--   normal counterparts. The <tt>threadCapability</tt>,
--   <tt>threadWaitRead</tt>, <tt>threadWaitWrite</tt>,
--   <tt>threadWaitReadSTM</tt>, <tt>threadWaitWriteSTM</tt>, and
--   <tt>mkWeakThreadId</tt> functions are not provided. The
--   <tt>threadDelay</tt> function is not required to delay the thread,
--   merely to yield it. The <tt>BlockedIndefinitelyOnMVar</tt> (and
--   similar) exceptions are <i>not</i> thrown during testing, so do not
--   rely on them at all.
module Control.Monad.Conc.Class

-- | <tt>MonadConc</tt> 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 <tt>MonadConc</tt> has an associated <a>MonadSTM</a>,
--   transactions of which can be run atomically.
--   
--   <b>Deriving instances:</b> If you have a newtype wrapper around a type
--   with an existing <tt>MonadConc</tt> instance, you should be able to
--   derive an instance for your type automatically, in simple cases.
--   
--   For example:
--   
--   <pre>
--   {-# 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 =&gt; MonadThrow (MyMonad m)
--   deriving instance MonadCatch m =&gt; MonadCatch (MyMonad m)
--   deriving instance MonadMask  m =&gt; MonadMask  (MyMonad m)
--   
--   deriving instance MonadConc m =&gt; MonadConc (MyMonad m)
--   </pre>
--   
--   Do not be put off by the use of <tt>UndecidableInstances</tt>, it is
--   safe here.
class (Monad m, MonadCatch m, MonadThrow m, MonadMask m, MonadSTM (STM m), Ord (ThreadId m), Show (ThreadId m)) => MonadConc m where {
    
    -- | The associated <a>MonadSTM</a> for this class.
    type family STM m :: Type -> Type;
    
    -- | The mutable reference type, like <a>MVar</a>s. This may contain one
    --   value at a time, attempting to read or take from an "empty"
    --   <tt>MVar</tt> will block until it is full, and attempting to put to a
    --   "full" <tt>MVar</tt> will block until it is empty.
    type family MVar m :: Type -> Type;
    
    -- | The mutable non-blocking reference type. These may suffer from relaxed
    --   memory effects if functions outside the set <tt>newIORef</tt>,
    --   <tt>readIORef</tt>, <tt>atomicModifyIORef</tt>, and
    --   <tt>atomicWriteIORef</tt> are used.
    type family IORef m :: Type -> Type;
    
    -- | When performing compare-and-swap operations on <tt>IORef</tt>s, a
    --   <tt>Ticket</tt> is a proof that a thread observed a specific previous
    --   value.
    type family Ticket m :: Type -> Type;
    
    -- | An abstract handle to a thread.
    type family ThreadId m :: Type;
}

-- | Like <a>fork</a>, but the child thread is passed a function that can
--   be used to unmask asynchronous exceptions. This function should not be
--   used within a <a>mask</a> or <a>uninterruptibleMask</a>.
--   
--   <pre>
--   forkWithUnmask = forkWithUnmaskN ""
--   </pre>
forkWithUnmask :: MonadConc m => ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)

-- | Like <a>forkWithUnmask</a>, but the thread is given a name which may
--   be used to present more useful debugging information.
--   
--   <pre>
--   forkWithUnmaskN _ = forkWithUnmask
--   </pre>
forkWithUnmaskN :: MonadConc m => String -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)

-- | Like <a>forkWithUnmask</a>, but the child thread is pinned to the
--   given CPU, as with <a>forkOn</a>.
--   
--   <pre>
--   forkOnWithUnmask = forkOnWithUnmaskN ""
--   </pre>
forkOnWithUnmask :: MonadConc m => Int -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)

-- | Like <a>forkWithUnmaskN</a>, but the child thread is pinned to the
--   given CPU, as with <a>forkOn</a>.
--   
--   <pre>
--   forkOnWithUnmaskN _ = forkOnWithUnmask
--   </pre>
forkOnWithUnmaskN :: MonadConc m => String -> Int -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)

-- | Like <a>forkOS</a>, but the child thread is passed a function that can
--   be used to unmask asynchronous exceptions. This function should not be
--   used within a <a>mask</a> or <a>uninterruptibleMask</a>.
--   
--   <pre>
--   forkOSWithUnmask = forkOSWithUnmaskN ""
--   </pre>
forkOSWithUnmask :: MonadConc m => ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)

-- | Like <a>forkOSWithUnmask</a>, but the thread is given a name which may
--   be used to present more useful debugging information.
--   
--   <pre>
--   forkOSWithUnmaskN _ = forkOSWithUnmask
--   </pre>
forkOSWithUnmaskN :: MonadConc m => String -> ((forall a. m a -> m a) -> m ()) -> m (ThreadId m)

-- | Returns <a>True</a> if bound threads can be forked. If <a>False</a>,
--   <a>isCurrentThreadBound</a> will always return <a>False</a> and both
--   <a>forkOS</a> and <a>runInBoundThread</a> will fail.
supportsBoundThreads :: MonadConc m => m Bool

-- | Returns <a>True</a> 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.
isCurrentThreadBound :: MonadConc m => m Bool

-- | Get the number of Haskell threads that can run simultaneously.
getNumCapabilities :: MonadConc m => m Int

-- | Set the number of Haskell threads that can run simultaneously.
setNumCapabilities :: MonadConc m => Int -> m ()

-- | Get the <tt>ThreadId</tt> of the current thread.
myThreadId :: MonadConc m => m (ThreadId m)

-- | Allows a context-switch to any other unblocked thread (if any).
yield :: MonadConc m => 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.
--   
--   <pre>
--   threadDelay _ = yield
--   </pre>
threadDelay :: MonadConc m => Int -> m ()

-- | Create a new empty <tt>MVar</tt>.
--   
--   <pre>
--   newEmptyMVar = newEmptyMVarN ""
--   </pre>
newEmptyMVar :: MonadConc m => m (MVar m a)

-- | Create a new empty <tt>MVar</tt>, but it is given a name which may be
--   used to present more useful debugging information.
--   
--   <pre>
--   newEmptyMVarN _ = newEmptyMVar
--   </pre>
newEmptyMVarN :: MonadConc m => String -> m (MVar m a)

-- | Put a value into a <tt>MVar</tt>. If there is already a value there,
--   this will block until that value has been taken, at which point the
--   value will be stored.
putMVar :: MonadConc m => MVar m a -> a -> m ()

-- | Attempt to put a value in a <tt>MVar</tt> non-blockingly, returning
--   <a>True</a> (and filling the <tt>MVar</tt>) if there was nothing
--   there, otherwise returning <a>False</a>.
tryPutMVar :: MonadConc m => MVar m a -> a -> m Bool

-- | Block until a value is present in the <tt>MVar</tt>, and then return
--   it. This does not "remove" the value, multiple reads are possible.
readMVar :: MonadConc m => MVar m a -> m a

-- | Attempt to read a value from a <tt>MVar</tt> non-blockingly, returning
--   a <a>Just</a> if there is something there, otherwise returning
--   <a>Nothing</a>. As with <a>readMVar</a>, this does not "remove" the
--   value.
tryReadMVar :: MonadConc m => MVar m a -> m (Maybe a)

-- | Take a value from a <tt>MVar</tt>. This "empties" the <tt>MVar</tt>,
--   allowing a new value to be put in. This will block if there is no
--   value in the <tt>MVar</tt> already, until one has been put.
takeMVar :: MonadConc m => MVar m a -> m a

-- | Attempt to take a value from a <tt>MVar</tt> non-blockingly, returning
--   a <a>Just</a> (and emptying the <tt>MVar</tt>) if there was something
--   there, otherwise returning <a>Nothing</a>.
tryTakeMVar :: MonadConc m => MVar m a -> m (Maybe a)

-- | Create a new reference.
--   
--   <pre>
--   newIORef = newIORefN ""
--   </pre>
newIORef :: MonadConc m => 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.
--   
--   <pre>
--   newIORefN _ = newIORef
--   </pre>
newIORefN :: MonadConc m => String -> a -> m (IORef m a)

-- | Read the current value stored in a reference.
--   
--   <pre>
--   readIORef ioref = readForCAS ioref &gt;&gt;= peekTicket
--   </pre>
readIORef :: MonadConc m => IORef m a -> m a

-- | Atomically modify the value stored in a reference. This imposes a full
--   memory barrier.
atomicModifyIORef :: MonadConc m => IORef m a -> (a -> (a, b)) -> m b

-- | Write a new value into an <tt>IORef</tt>, without imposing a memory
--   barrier. This means that relaxed memory effects can be observed.
writeIORef :: MonadConc m => IORef m a -> a -> m ()

-- | Replace the value stored in a reference, with the
--   barrier-to-reordering property that <a>atomicModifyIORef</a> has.
--   
--   <pre>
--   atomicWriteIORef r a = atomicModifyIORef r $ const (a, ())
--   </pre>
atomicWriteIORef :: MonadConc m => IORef m a -> a -> m ()

-- | Read the current value stored in a reference, returning a
--   <tt>Ticket</tt>, for use in future compare-and-swap operations.
readForCAS :: MonadConc m => IORef m a -> m (Ticket m a)

-- | Extract the actual Haskell value from a <tt>Ticket</tt>.
--   
--   The <tt>Proxy m</tt> is to determine the <tt>m</tt> in the
--   <tt>Ticket</tt> type.
peekTicket' :: MonadConc m => Proxy m -> Ticket m a -> a

-- | Perform a machine-level compare-and-swap (CAS) operation on a
--   <tt>IORef</tt>. Returns an indication of success and a <tt>Ticket</tt>
--   for the most current value in the <tt>IORef</tt>.
--   
--   This is strict in the "new" value argument.
casIORef :: MonadConc m => IORef m a -> Ticket m a -> a -> m (Bool, Ticket m a)

-- | A replacement for <a>atomicModifyIORef</a> using a compare-and-swap.
--   
--   This is strict in the "new" value argument.
modifyIORefCAS :: MonadConc m => IORef m a -> (a -> (a, b)) -> m b

-- | A variant of <a>modifyIORefCAS</a> which doesn't return a result.
--   
--   <pre>
--   modifyIORefCAS_ ioref f = modifyIORefCAS ioref (\a -&gt; (f a, ()))
--   </pre>
modifyIORefCAS_ :: MonadConc m => IORef m a -> (a -> a) -> m ()

-- | Perform an STM transaction atomically.
atomically :: MonadConc m => STM m a -> m a

-- | Create a <tt>TVar</tt>. This may be implemented differently for speed.
--   
--   <pre>
--   newTVarConc = atomically . newTVar
--   </pre>
newTVarConc :: MonadConc m => a -> m (TVar (STM m) a)

-- | Read the current value stored in a <tt>TVar</tt>. This may be
--   implemented differently for speed.
--   
--   <pre>
--   readTVarConc = atomically . readTVar
--   </pre>
readTVarConc :: MonadConc m => TVar (STM m) a -> m a

-- | 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 <a>throw</a>. This can interrupt a blocked action.
throwTo :: (MonadConc m, Exception e) => ThreadId m -> e -> m ()

-- | Return the <a>MaskingState</a> for the current thread.
getMaskingState :: MonadConc m => m MaskingState

-- | Set the <a>MaskingState</a> for the current thread to
--   <a>MaskedUninterruptible</a>.
unsafeUnmask :: MonadConc m => m a -> m a

-- | Fork a computation to happen concurrently. Communication may happen
--   over <tt>MVar</tt>s.
fork :: MonadConc m => m () -> m (ThreadId m)

-- | Fork a computation to happen on a specific processor. The specified
--   int is the <i>capability number</i>, 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 <a>getNumCapabilities</a>.
forkOn :: MonadConc m => Int -> m () -> m (ThreadId m)

-- | Fork a computation to happen in a <i>bound thread</i>, which is
--   necessary if you need to call foreign (non-Haskell) libraries that
--   make use of thread-local state, such as OpenGL.
forkOS :: MonadConc m => 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.
forkFinally :: MonadConc m => m a -> (Either SomeException a -> m ()) -> m (ThreadId m)

-- | Create a concurrent computation for the provided action, and return a
--   <tt>MVar</tt> which can be used to query the result.
spawn :: MonadConc m => m a -> m (MVar m a)

-- | Raise the <a>ThreadKilled</a> exception in the target thread. Note
--   that if the thread is prepared to catch this exception, it won't
--   actually kill it.
killThread :: MonadConc m => ThreadId m -> m ()

-- | <a>True</a> if bound threads are supported. If
--   <a>rtsSupportsBoundThreads</a> is <a>False</a>,
--   <a>isCurrentThreadBound</a> will always return <a>False</a> and both
--   <a>forkOS</a> and <a>runInBoundThread</a> will fail.
--   
--   Use <a>supportsBoundThreads</a> in <a>MonadConc</a> instead.

-- | <i>Deprecated: Use <a>supportsBoundThreads</a> instead</i>
rtsSupportsBoundThreads :: Bool

-- | Run the computation passed as the first argument. If the calling
--   thread is not <i>bound</i>, a bound thread is created temporarily.
--   <tt>runInBoundThread</tt> doesn't finish until the inner computation
--   finishes.
--   
--   You can wrap a series of foreign function calls that rely on
--   thread-local state with <tt>runInBoundThread</tt> so that you can use
--   them without knowing whether the current thread is <i>bound</i>.
runInBoundThread :: MonadConc m => m a -> m a

-- | Run the computation passed as the first argument. If the calling
--   thread is <i>bound</i>, an unbound thread is created temporarily using
--   <tt>fork</tt>. <tt>runInBoundThread</tt> doesn't finish until the
--   inner computation finishes.
--   
--   Use this function <i>only</i> 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 <i>heavy</i>
--   use of concurrency (e.g. a web server), might want to wrap its
--   <tt>main</tt> action in <tt>runInUnboundThread</tt>.
--   
--   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.
runInUnboundThread :: MonadConc m => m a -> m a

-- | Like <a>fork</a>, but the thread is given a name which may be used to
--   present more useful debugging information.
forkN :: MonadConc m => String -> m () -> m (ThreadId m)

-- | Like <a>forkOn</a>, but the thread is given a name which may be used
--   to present more useful debugging information.
forkOnN :: MonadConc m => String -> Int -> m () -> m (ThreadId m)

-- | Like <a>forkOS</a>, but the thread is given a name which may be used
--   to present more useful debugging information.
forkOSN :: MonadConc m => String -> m () -> m (ThreadId m)

-- | 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.
throw :: (MonadConc m, Exception e) => e -> m a

-- | Catch an exception. This is only required to be able to catch
--   exceptions raised by <a>throw</a>, unlike the more general
--   Control.Exception.catch function. If you need to be able to catch
--   <i>all</i> errors, you will have to use <a>IO</a>.
catch :: (MonadConc m, Exception e) => m a -> (e -> m a) -> m a

-- | Executes a computation with asynchronous exceptions <i>masked</i>.
--   That is, any thread which attempts to raise an exception in the
--   current thread with <a>throwTo</a> 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 <a>uninterruptibleMask</a>.
mask :: MonadConc m => ((forall a. m a -> m a) -> m b) -> m b

-- | Like <a>mask</a>, but does not pass a <tt>restore</tt> action to the
--   argument.
mask_ :: MonadMask m => m a -> m a

-- | Like <a>mask</a>, but the masked computation is not interruptible.
--   THIS SHOULD BE USED WITH GREAT CARE, because if a thread executing in
--   <a>uninterruptibleMask</a> 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 <a>mask</a>.
uninterruptibleMask :: MonadConc m => ((forall a. m a -> m a) -> m b) -> m b

-- | Like <a>uninterruptibleMask</a>, but does not pass a <tt>restore</tt>
--   action to the argument.
uninterruptibleMask_ :: MonadMask m => m a -> m a

-- | Allow asynchronous exceptions to be raised even inside <a>mask</a>,
--   making the operation interruptible.
--   
--   When called outside <a>mask</a>, or inside <a>uninterruptibleMask</a>,
--   this function has no effect.
interruptible :: MonadConc m => m a -> m a

-- | Create a new <tt>MVar</tt> containing a value.
newMVar :: MonadConc m => a -> m (MVar m a)

-- | Create a new <tt>MVar</tt> containing a value, but it is given a name
--   which may be used to present more useful debugging information.
newMVarN :: MonadConc m => String -> a -> m (MVar m a)

-- | Compare-and-swap a value in a <tt>IORef</tt>, returning an indication
--   of success and the new value.
cas :: MonadConc m => IORef m a -> a -> m (Bool, a)

-- | Extract the actual Haskell value from a <tt>Ticket</tt>.
--   
--   This doesn't do do any monadic computation, the <tt>m</tt> appears in
--   the result type to determine the <tt>m</tt> in the <tt>Ticket</tt>
--   type.
peekTicket :: forall m a. MonadConc m => Ticket m a -> m a

-- | A value of type <tt>IsConc m a</tt> can only be constructed if
--   <tt>m</tt> has a <tt>MonadConc</tt> instance.
data IsConc m a

-- | Wrap an <tt>m a</tt> value inside an <tt>IsConc</tt> if <tt>m</tt> has
--   a <tt>MonadConc</tt> instance.
toIsConc :: MonadConc m => m a -> IsConc m a

-- | Unwrap an <tt>IsConc</tt> value.
fromIsConc :: MonadConc m => IsConc m a -> m a

-- | Given a function to remove the transformer-specific state, lift a
--   function invocation.
liftedF :: (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
--   <tt>fork(on)WithUnmask</tt> invocation.
liftedFork :: (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
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Conc.Class.IsConc m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Conc.Class.IsConc m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Conc.Class.IsConc m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Conc.Class.IsConc m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.Conc.Class.IsConc m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Conc.Class.IsConc m)
instance Control.Monad.Fail.MonadFail m => Control.Monad.Fail.MonadFail (Control.Monad.Conc.Class.IsConc m)
instance Control.Monad.Conc.Class.MonadConc m => Control.Monad.Conc.Class.MonadConc (Control.Monad.Conc.Class.IsConc m)
instance Control.Monad.Conc.Class.MonadConc GHC.Types.IO
instance Control.Monad.Conc.Class.MonadConc m => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Conc.Class.MonadConc m => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.Identity.IdentityT m)
instance (Control.Monad.Conc.Class.MonadConc m, GHC.Base.Monoid w) => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Control.Monad.Conc.Class.MonadConc m, GHC.Base.Monoid w) => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance Control.Monad.Conc.Class.MonadConc m => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Conc.Class.MonadConc m => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.State.Strict.StateT s m)
instance (Control.Monad.Conc.Class.MonadConc m, GHC.Base.Monoid w) => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (Control.Monad.Conc.Class.MonadConc m, GHC.Base.Monoid w) => Control.Monad.Conc.Class.MonadConc (Control.Monad.Trans.RWS.Strict.RWST r w s m)


-- | An <tt><a>MVar</a> t</tt> is mutable location that is either empty or
--   contains a value of type <tt>t</tt>. It has two fundamental
--   operations: <a>putMVar</a> which fills an <a>MVar</a> if it is empty
--   and blocks otherwise, and <a>takeMVar</a> which empties an <a>MVar</a>
--   if it is full and blocks otherwise. They can be used in multiple
--   different ways:
--   
--   <ol>
--   <li>As synchronized mutable variables,</li>
--   <li>As channels, with <a>takeMVar</a> and <a>putMVar</a> as receive
--   and send, and</li>
--   <li>As a binary semaphore <tt><a>MVar</a> ()</tt>, with
--   <a>takeMVar</a> and <a>putMVar</a> as wait and signal.</li>
--   </ol>
--   
--   <b>Deviations:</b> There is no <tt>Eq</tt> instance for
--   <tt>MonadConc</tt> the <tt>MVar</tt> type. Furthermore, the
--   <tt>mkWeakMVar</tt> and <tt>addMVarFinalizer</tt> functions are not
--   provided. Finally, normal <tt>MVar</tt>s have a fairness guarantee,
--   which dejafu does not currently make use of when generating schedules
--   to test, so your program may be tested with <i>unfair</i> schedules.
module Control.Concurrent.Classy.MVar

-- | The mutable reference type, like <a>MVar</a>s. This may contain one
--   value at a time, attempting to read or take from an "empty"
--   <tt>MVar</tt> will block until it is full, and attempting to put to a
--   "full" <tt>MVar</tt> will block until it is empty.
type family MVar m :: Type -> Type

-- | Create a new empty <tt>MVar</tt>.
--   
--   <pre>
--   newEmptyMVar = newEmptyMVarN ""
--   </pre>
newEmptyMVar :: MonadConc m => m (MVar m a)

-- | Create a new empty <tt>MVar</tt>, but it is given a name which may be
--   used to present more useful debugging information.
--   
--   <pre>
--   newEmptyMVarN _ = newEmptyMVar
--   </pre>
newEmptyMVarN :: MonadConc m => String -> m (MVar m a)

-- | Create a new <tt>MVar</tt> containing a value.
newMVar :: MonadConc m => a -> m (MVar m a)

-- | Create a new <tt>MVar</tt> containing a value, but it is given a name
--   which may be used to present more useful debugging information.
newMVarN :: MonadConc m => String -> a -> m (MVar m a)

-- | Take a value from a <tt>MVar</tt>. This "empties" the <tt>MVar</tt>,
--   allowing a new value to be put in. This will block if there is no
--   value in the <tt>MVar</tt> already, until one has been put.
takeMVar :: MonadConc m => MVar m a -> m a

-- | Put a value into a <tt>MVar</tt>. If there is already a value there,
--   this will block until that value has been taken, at which point the
--   value will be stored.
putMVar :: MonadConc m => MVar m a -> a -> m ()

-- | Block until a value is present in the <tt>MVar</tt>, and then return
--   it. This does not "remove" the value, multiple reads are possible.
readMVar :: MonadConc m => MVar m a -> m a

-- | Swap the contents of a <tt>MVar</tt>, and return the value taken. This
--   function is atomic only if there are no other producers fro this
--   <tt>MVar</tt>.
swapMVar :: MonadConc m => MVar m a -> a -> m a

-- | Attempt to take a value from a <tt>MVar</tt> non-blockingly, returning
--   a <a>Just</a> (and emptying the <tt>MVar</tt>) if there was something
--   there, otherwise returning <a>Nothing</a>.
tryTakeMVar :: MonadConc m => MVar m a -> m (Maybe a)

-- | Attempt to put a value in a <tt>MVar</tt> non-blockingly, returning
--   <a>True</a> (and filling the <tt>MVar</tt>) if there was nothing
--   there, otherwise returning <a>False</a>.
tryPutMVar :: MonadConc m => MVar m a -> a -> m Bool

-- | Check if a <tt>MVar</tt> is empty.
--   
--   The boolean value returned is just a snapshot of the state of the
--   <tt>MVar</tt>, it may have been emptied (or filled) by the time you
--   actually access it. Generally prefer <a>tryPutMVar</a>,
--   <a>tryTakeMVar</a>, and <a>tryReadMVar</a>.
isEmptyMVar :: MonadConc m => MVar m a -> m Bool

-- | Operate on the contents of a <tt>MVar</tt>, replacing the contents
--   after finishing. This operation is exception-safe: it will replace the
--   original contents of the <tt>MVar</tt> if an exception is raised.
--   However, it is only atomic if there are no other producers for this
--   <tt>MVar</tt>.
withMVar :: MonadConc m => MVar m a -> (a -> m b) -> m b

-- | Like <a>withMVar</a>, but the <tt>IO</tt> action in the second
--   argument is executed with asynchronous exceptions masked.
withMVarMasked :: MonadConc m => MVar m a -> (a -> m b) -> m b

-- | An exception-safe wrapper for modifying the contents of a
--   <tt>MVar</tt>. Like <a>withMVar</a>, <a>modifyMVar</a> will replace
--   the original contents of the <tt>MVar</tt> if an exception is raised
--   during the operation. This function is only atomic if there are no
--   other producers for this <tt>MVar</tt>.
modifyMVar_ :: MonadConc m => MVar m a -> (a -> m a) -> m ()

-- | A slight variation on <a>modifyMVar_</a> that allows a value to be
--   returned (<tt>b</tt>) in addition to the modified value of the
--   <tt>MVar</tt>.
modifyMVar :: MonadConc m => MVar m a -> (a -> m (a, b)) -> m b

-- | Like <a>modifyMVar_</a>, but the <tt>IO</tt> action in the second
--   argument is executed with asynchronous exceptions masked.
modifyMVarMasked_ :: MonadConc m => MVar m a -> (a -> m a) -> m ()

-- | Like <a>modifyMVar</a>, but the <tt>IO</tt> action in the second
--   argument is executed with asynchronous exceptions masked.
modifyMVarMasked :: MonadConc m => MVar m a -> (a -> m (a, b)) -> m b


-- | Quantity semaphores in which each thread may wait for an arbitrary
--   "amount".
module Control.Concurrent.Classy.QSemN

-- | <a>QSemN</a> is a quantity semaphore in which the resource is aqcuired
--   and released in units of one. It provides guaranteed FIFO ordering for
--   satisfying blocked <a>waitQSemN</a> calls.
--   
--   The pattern
--   
--   <pre>
--   bracket_ (waitQSemN n) (signalQSemN n) (...)
--   </pre>
--   
--   is safe; it never loses any of the resource.
data QSemN m

-- | Build a new <a>QSemN</a> with a supplied initial quantity. The initial
--   quantity must be at least 0.
newQSemN :: (MonadConc m, MonadFail m) => Int -> m (QSemN m)

-- | Wait for the specified quantity to become available
waitQSemN :: MonadConc m => QSemN m -> Int -> m ()

-- | Signal that a given quantity is now available from the <a>QSemN</a>.
signalQSemN :: MonadConc m => QSemN m -> Int -> m ()


-- | Simple quantity semaphores.
module Control.Concurrent.Classy.QSem

-- | <tt>QSem</tt> is a quantity semaphore in which the resource is
--   acquired and released in units of one. It provides guaranteed FIFO
--   ordering for satisfying blocked <a>waitQSem</a> calls.
--   
--   The pattern
--   
--   <pre>
--   bracket_ qaitQSem signalSSem (...)
--   </pre>
--   
--   is safe; it never loses a unit of the resource.
data QSem m

-- | Build a new <a>QSem</a> with a supplied initial quantity. The initial
--   quantity must be at least 0.
newQSem :: (MonadConc m, MonadFail m) => Int -> m (QSem m)

-- | Wait for a unit to become available.
waitQSem :: MonadConc m => QSem m -> m ()

-- | Signal that a unit of the <a>QSem</a> is available.
signalQSem :: MonadConc m => QSem m -> m ()


-- | This module provides the <a>Lock</a> synchronisation mechanism. It was
--   inspired by the Python and Java <tt>Lock</tt> objects and should
--   behave in a similar way. See:
--   
--   <a>http://docs.python.org/3.1/library/threading.html#lock-objects</a>
--   
--   and:
--   
--   
--   <a>http://java.sun.com/javase/7/docs/api/java/util/concurrent/locks/Lock.html</a>
--   
--   All functions are <i>exception safe</i>. Throwing asynchronous
--   exceptions will not compromise the internal state of a <a>Lock</a>.
module Control.Concurrent.Classy.Lock

-- | A lock is in one of two states: "locked" or "unlocked".
data Lock m

-- | Create a lock in the "unlocked" state.
newLock :: MonadConc m => m (Lock m)

-- | Create a lock in the "locked" state.
newAcquired :: MonadConc m => m (Lock m)

-- | Acquires the <a>Lock</a>. Blocks if another thread has acquired the
--   <a>Lock</a>.
--   
--   <tt>acquire</tt> behaves as follows:
--   
--   <ul>
--   <li>When the state is "unlocked" <tt>acquire</tt> changes the state to
--   "locked".</li>
--   <li>When the state is "locked" <tt>acquire</tt> <i>blocks</i> until a
--   call to <a>release</a> in another thread wakes the calling thread.
--   Upon awakening it will change the state to "locked".</li>
--   </ul>
--   
--   There are two further important properties of <tt>acquire</tt>:
--   
--   <ul>
--   <li><tt>acquire</tt> is single-wakeup. That is, if there are multiple
--   threads blocked on <tt>acquire</tt> and the lock is released, only one
--   thread will be woken up. The runtime guarantees that the woken thread
--   completes its <tt>acquire</tt> operation.</li>
--   <li>When multiple threads are blocked on <tt>acquire</tt>, they are
--   woken up in FIFO order. This is useful for providing fairness
--   properties of abstractions built using locks. Note that this differs
--   from the Python implementation where the wake-up order is
--   undefined.</li>
--   </ul>
acquire :: MonadConc m => Lock m -> m ()

-- | A non-blocking <a>acquire</a>.
--   
--   <ul>
--   <li>When the state is "unlocked" <tt>tryAcquire</tt> changes the state
--   to "locked" and returns <tt>True</tt>.</li>
--   <li>When the state is "locked" <tt>tryAcquire</tt> leaves the state
--   unchanged and returns <tt>False</tt>.</li>
--   </ul>
tryAcquire :: MonadConc m => Lock m -> m Bool

-- | <tt>release</tt> changes the state to "unlocked" and returns
--   immediately.
--   
--   Note that it is an error to release a lock in the "unlocked" state!
--   
--   If there are any threads blocked on <a>acquire</a> the thread that
--   first called <tt>acquire</tt> will be woken up.
release :: MonadConc m => Lock m -> m ()

-- | A convenience function which first acquires the lock and then performs
--   the computation. When the computation terminates, whether normally or
--   by raising an exception, the lock is released.
--   
--   Note that: <tt>with = <a>bracket_</a> <a>&lt;$&gt;</a> <a>acquire</a>
--   <a>&lt;*&gt;</a> <a>release</a></tt>.
with :: MonadConc m => Lock m -> m a -> m a

-- | A non-blocking <a>with</a>. <tt>tryWith</tt> is a convenience function
--   which first tries to acquire the lock. If that fails, <a>Nothing</a>
--   is returned. If it succeeds, the computation is performed. When the
--   computation terminates, whether normally or by raising an exception,
--   the lock is released and <a>Just</a> the result of the computation is
--   returned.
tryWith :: MonadConc m => Lock m -> m a -> m (Maybe a)

-- | <ul>
--   <li>When the state is "locked", <tt>wait</tt> <i>blocks</i> until a
--   call to <a>release</a> in another thread changes it to
--   "unlocked".</li>
--   <li><tt>wait</tt> is multiple-wakeup, so when multiple waiters are
--   blocked on a <tt>Lock</tt>, all of them are woken up at the same
--   time.</li>
--   <li>When the state is "unlocked" <tt>wait</tt> returns
--   immediately.</li>
--   </ul>
--   
--   <tt>wait</tt> does not alter the state of the lock.
wait :: MonadConc m => Lock m -> m ()

-- | Determines if the lock is in the "locked" state.
--   
--   Note that this is only a snapshot of the state. By the time a program
--   reacts on its result it may already be out of date.
locked :: MonadConc m => Lock m -> m Bool
instance GHC.Classes.Eq (Control.Monad.Conc.Class.MVar m ()) => GHC.Classes.Eq (Control.Concurrent.Classy.Lock.Lock m)


-- | Multiple-reader, single-writer locks. Used to protect shared resources
--   which may be concurrently read, but only sequentially written.
--   
--   All functions are <i>exception safe</i>. Throwing asynchronous
--   exceptions will not compromise the internal state of an <a>RWLock</a>.
--   This means it is perfectly safe to kill a thread that is blocking on,
--   for example, <a>acquireRead</a>.
module Control.Concurrent.Classy.RWLock

-- | Multiple-reader, single-writer lock. Is in one of three states:
--   
--   <ul>
--   <li>"Free": Read or write access can be acquired without
--   blocking.</li>
--   <li>"Read": One or more threads have acquired read access. Blocks
--   write access.</li>
--   <li>"Write": A single thread has acquired write access. Blocks other
--   threads from acquiring both read and write access.</li>
--   </ul>
data RWLock m

-- | Create a new <a>RWLock</a> in the "free" state; either read or write
--   access can be acquired without blocking.
newRWLock :: MonadConc m => m (RWLock m)

-- | Create a new <a>RWLock</a> in the "read" state; only read can be
--   acquired without blocking.
newAcquiredRead :: MonadConc m => m (RWLock m)

-- | Create a new <a>RWLock</a> in the "write" state; either acquiring read
--   or write will block.
newAcquiredWrite :: MonadConc m => m (RWLock m)

-- | Acquire the read lock.
--   
--   Blocks if another thread has acquired write access. If
--   <tt>acquireRead</tt> terminates without throwing an exception the
--   state of the <a>RWLock</a> will be "read".
--   
--   Implementation note: throws an exception when more than
--   <tt><tt>maxBound</tt> :: <a>Int</a></tt> simultaneous threads acquire
--   the read lock. But that is unlikely.
acquireRead :: MonadConc m => RWLock m -> m ()

-- | Release the read lock.
--   
--   If the calling thread was the last one to relinquish read access the
--   state will revert to "free".
--   
--   It is an error to release read access to an <a>RWLock</a> which is not
--   in the "read" state.
releaseRead :: MonadConc m => RWLock m -> m ()

-- | A convenience function wich first acquires read access and then
--   performs the computation. When the computation terminates, whether
--   normally or by raising an exception, the read lock is released.
withRead :: MonadConc m => RWLock m -> m a -> m a

-- | <ul>
--   <li>When the state is "write", <tt>waitRead</tt> <i>blocks</i> until a
--   call to <a>releaseWrite</a> in another thread changes the state to
--   "free".</li>
--   <li>When the state is "free" or "read" <tt>waitRead</tt> returns
--   immediately.</li>
--   </ul>
--   
--   <tt>waitRead</tt> does not alter the state of the lock.
--   
--   Note that <tt>waitRead</tt> is just a convenience function defined as:
--   
--   <pre>
--   waitRead l = <a>mask_</a> <a>$</a> <a>acquireRead</a> l <a>&gt;&gt;</a> <a>releaseRead</a> l
--   </pre>
waitRead :: MonadConc m => RWLock m -> m ()

-- | Try to acquire the read lock; non blocking.
--   
--   Like <a>acquireRead</a>, but doesn't block. Returns <a>True</a> if the
--   resulting state is "read", <a>False</a> otherwise.
tryAcquireRead :: MonadConc m => RWLock m -> m Bool

-- | A non-blocking <a>withRead</a>. First tries to acquire the lock. If
--   that fails, <a>Nothing</a> is returned. If it succeeds, the
--   computation is performed. When the computation terminates, whether
--   normally or by raising an exception, the lock is released and
--   <a>Just</a> the result of the computation is returned.
tryWithRead :: MonadConc m => RWLock m -> m a -> m (Maybe a)

-- | Acquire the write lock.
--   
--   Blocks if another thread has acquired either read or write access. If
--   <tt>acquireWrite</tt> terminates without throwing an exception the
--   state of the <a>RWLock</a> will be "write".
acquireWrite :: MonadConc m => RWLock m -> m ()

-- | Release the write lock.
--   
--   If <tt>releaseWrite</tt> terminates without throwing an exception the
--   state will be "free".
--   
--   It is an error to release write access to an <a>RWLock</a> which is
--   not in the "write" state.
releaseWrite :: MonadConc m => RWLock m -> m ()

-- | A convenience function wich first acquires write access and then
--   performs the computation. When the computation terminates, whether
--   normally or by raising an exception, the write lock is released.
withWrite :: MonadConc m => RWLock m -> m a -> m a

-- | <ul>
--   <li>When the state is "write" or "read" <tt>waitWrite</tt>
--   <i>blocks</i> until a call to <a>releaseWrite</a> or
--   <a>releaseRead</a> in another thread changes the state to "free".</li>
--   <li>When the state is "free" <tt>waitWrite</tt> returns
--   immediately.</li>
--   </ul>
--   
--   <tt>waitWrite</tt> does not alter the state of the lock.
--   
--   Note that <tt>waitWrite</tt> is just a convenience function defined
--   as:
--   
--   <pre>
--   waitWrite l = <a>mask_</a> <a>$</a> <a>acquireWrite</a> l <a>&gt;&gt;</a> <a>releaseWrite</a> l
--   </pre>
waitWrite :: MonadConc m => RWLock m -> m ()

-- | Try to acquire the write lock; non blocking.
--   
--   Like <a>acquireWrite</a>, but doesn't block. Returns <a>True</a> if
--   the resulting state is "write", <a>False</a> otherwise.
tryAcquireWrite :: MonadConc m => RWLock m -> m Bool

-- | A non-blocking <a>withWrite</a>. First tries to acquire the lock. If
--   that fails, <a>Nothing</a> is returned. If it succeeds, the
--   computation is performed. When the computation terminates, whether
--   normally or by raising an exception, the lock is released and
--   <a>Just</a> the result of the computation is returned.
tryWithWrite :: MonadConc m => RWLock m -> m a -> m (Maybe a)
instance GHC.Read.Read Control.Concurrent.Classy.RWLock.State
instance GHC.Show.Show Control.Concurrent.Classy.RWLock.State
instance GHC.Classes.Ord Control.Concurrent.Classy.RWLock.State
instance GHC.Classes.Eq Control.Concurrent.Classy.RWLock.State
instance GHC.Classes.Eq (Control.Monad.Conc.Class.MVar m Control.Concurrent.Classy.RWLock.State) => GHC.Classes.Eq (Control.Concurrent.Classy.RWLock.RWLock m)


-- | Mutable references in a concurrency monad.
--   
--   <b>Deviations:</b> There is no <tt>Eq</tt> instance for
--   <tt>MonadConc</tt> the <tt>IORef</tt> type. Furthermore, the
--   <tt>mkWeakIORef</tt> function is not provided.
module Control.Concurrent.Classy.IORef

-- | Create a new reference.
--   
--   <pre>
--   newIORef = newIORefN ""
--   </pre>
newIORef :: MonadConc m => a -> m (IORef m a)

-- | Read the current value stored in a reference.
--   
--   <pre>
--   readIORef ioref = readForCAS ioref &gt;&gt;= peekTicket
--   </pre>
readIORef :: MonadConc m => IORef m a -> m a

-- | Write a new value into an <tt>IORef</tt>, without imposing a memory
--   barrier. This means that relaxed memory effects can be observed.
writeIORef :: MonadConc m => IORef m a -> a -> m ()

-- | Mutate the contents of a <tt>IORef</tt>.
--   
--   Be warned that <a>modifyIORef</a> does not apply the function
--   strictly. This means if the program calls <a>modifyIORef</a> many
--   times, but seldomly uses the value, thunks will pile up in memory
--   resulting in a space leak. This is a common mistake made when using a
--   <tt>IORef</tt> as a counter. For example, the following will likely
--   produce a stack overflow:
--   
--   <pre>
--   ref &lt;- newIORef 0
--   replicateM_ 1000000 $ modifyIORef ref (+1)
--   readIORef ref &gt;&gt;= print
--   </pre>
--   
--   To avoid this problem, use <a>modifyIORef'</a> instead.
modifyIORef :: MonadConc m => IORef m a -> (a -> a) -> m ()

-- | Strict version of <a>modifyIORef</a>
modifyIORef' :: MonadConc m => IORef m a -> (a -> a) -> m ()

-- | Atomically modify the value stored in a reference. This imposes a full
--   memory barrier.
atomicModifyIORef :: MonadConc m => IORef m a -> (a -> (a, b)) -> m b

-- | Strict version of <a>atomicModifyIORef</a>. This forces both the value
--   stored in the <tt>IORef</tt> as well as the value returned.
atomicModifyIORef' :: MonadConc m => IORef m a -> (a -> (a, b)) -> m b

-- | Replace the value stored in a reference, with the
--   barrier-to-reordering property that <a>atomicModifyIORef</a> has.
--   
--   <pre>
--   atomicWriteIORef r a = atomicModifyIORef r $ const (a, ())
--   </pre>
atomicWriteIORef :: MonadConc m => IORef m a -> a -> m ()


-- | Unbounded channels.
--   
--   <b>Deviations:</b> <tt>Chan</tt> as defined here does not have an
--   <tt>Eq</tt> instance, this is because the <tt>MonadConc</tt>
--   <tt>MVar</tt> type does not have an <tt>Eq</tt> constraint. The
--   deprecated <tt>unGetChan</tt> and <tt>isEmptyCHan</tt> functions are
--   not provided. Furthermore, the <tt>getChanContents</tt> function is
--   not provided as it needs unsafe I/O.
module Control.Concurrent.Classy.Chan

-- | <a>Chan</a> is an abstract type representing an unbounded FIFO
--   channel.
data Chan m a

-- | Build and returns a new instance of <a>Chan</a>.
newChan :: MonadConc m => m (Chan m a)

-- | Write a value to a <a>Chan</a>.
writeChan :: MonadConc m => Chan m a -> a -> m ()

-- | Read the next value from the <a>Chan</a>.
readChan :: MonadConc m => Chan m a -> m a

-- | Duplicate a <a>Chan</a>: the duplicate channel begins empty, but data
--   written to either channel from then on will be available from both.
--   Hence this creates a kind of broadcast channel, where data written by
--   anyone is seen by everyone else.
dupChan :: MonadConc m => Chan m a -> m (Chan m a)

-- | Write an entire list of items to a <a>Chan</a>.
writeList2Chan :: MonadConc m => Chan m a -> [a] -> m ()


-- | Deprecated re-exports of <tt>IORef</tt> functions under the old
--   <tt>CRef</tt> names.

-- | <i>Deprecated: Import Control.Concurrent.Classy.IORef instead</i>
module Control.Concurrent.Classy.CRef

-- | Type alias for <a>IORef</a>.
type CRef m a = IORef m a

-- | Create a new reference.
newCRef :: MonadConc m => a -> m (CRef m a)

-- | Create a new reference, but it is given a name which may be used to
--   present more useful debugging information.
newCRefN :: MonadConc m => String -> a -> m (CRef m a)

-- | Read the current value stored in a reference.
readCRef :: MonadConc m => CRef m a -> m a

-- | Write a new value into an <tt>CRef</tt>, without imposing a memory
--   barrier. This means that relaxed memory effects can be observed.
writeCRef :: MonadConc m => CRef m a -> a -> m ()

-- | Mutate the contents of a <tt>CRef</tt>.
--   
--   Be warned that <a>modifyCRef</a> does not apply the function strictly.
--   This means if the program calls <a>modifyCRef</a> many times, but
--   seldomly uses the value, thunks will pile up in memory resulting in a
--   space leak.
modifyCRef :: MonadConc m => CRef m a -> (a -> a) -> m ()

-- | Strict version of <a>modifyCRef</a>
modifyCRef' :: MonadConc m => CRef m a -> (a -> a) -> m ()

-- | Atomically modify the value stored in a reference. This imposes a full
--   memory barrier.
atomicModifyCRef :: MonadConc m => CRef m a -> (a -> (a, b)) -> m b

-- | Strict version of <a>atomicModifyCRef</a>. This forces both the value
--   stored in the <tt>CRef</tt> as well as the value returned.
atomicModifyCRef' :: MonadConc m => CRef m a -> (a -> (a, b)) -> m b

-- | Replace the value stored in a reference, with the
--   barrier-to-reordering property that <tt>atomicModifyIORef</tt> has.
atomicWriteCRef :: MonadConc m => CRef m a -> a -> m ()

-- | Perform a machine-level compare-and-swap (CAS) operation on a
--   <tt>CRef</tt>. Returns an indication of success and a <tt>Ticket</tt>
--   for the most current value in the <tt>CRef</tt>. This is strict in the
--   "new" value argument.
casCRef :: MonadConc m => CRef m a -> Ticket m a -> a -> m (Bool, Ticket m a)

-- | A replacement for <a>atomicModifyCRef</a> using a compare-and-swap.
--   
--   This is strict in the "new" value argument.
modifyCRefCAS :: MonadConc m => CRef m a -> (a -> (a, b)) -> m b

-- | A variant of <a>modifyCRefCAS</a> which doesn't return a result.
modifyCRefCAS_ :: MonadConc m => CRef m a -> (a -> a) -> m ()


-- | Implements bounded channels. These channels differ from normal
--   <tt>Chan</tt>s in that they are guaranteed to contain no more than a
--   certain number of elements. This is ideal when you may be writing to a
--   channel faster than you are able to read from it.
--   
--   This module supports all the functions of
--   <a>Control.Concurrent.Chan</a> except <tt>unGetChan</tt> and
--   <tt>dupChan</tt>, which are not supported for bounded channels.
--   
--   Extra consistency: This version enforces that if thread Alice writes
--   e1 followed by e2 then e1 will be returned by readBoundedChan before
--   e2. Conversely, if thead Bob reads e1 followed by e2 then it was true
--   that writeBoundedChan e1 preceded writeBoundedChan e2.
--   
--   Previous versions did not enforce this consistency: if
--   writeBoundedChan were preempted between putMVars or killThread arrived
--   between putMVars then it can fail. Similarly it might fail if
--   readBoundedChan were stopped after putMVar and before the second
--   takeMVar. An unlucky pattern of several such deaths might actually
--   break the invariants of the array in an unrecoverable way causing all
--   future reads and writes to block.
module Control.Concurrent.Classy.BoundedChan

-- | A <a>BoundedChan</a> is an abstract data type representing a bounded
--   channel.
data BoundedChan m a

-- | <tt>newBoundedChan n</tt> returns a channel than can contain no more
--   than <tt>n</tt> elements.
newBoundedChan :: MonadConc m => Int -> m (BoundedChan m a)

-- | Write an element to the channel. If the channel is full, this routine
--   will block until it is able to write. Blockers wait in a fair FIFO
--   queue.
writeBoundedChan :: MonadConc m => BoundedChan m a -> a -> m ()

-- | A variant of <a>writeBoundedChan</a> which, instead of blocking when
--   the channel is full, simply aborts and does not write the element.
--   Note that this routine can still block while waiting for write access
--   to the channel.
trywriteBoundedChan :: MonadConc m => BoundedChan m a -> a -> m Bool

-- | Read an element from the channel. If the channel is empty, this
--   routine will block until it is able to read. Blockers wait in a fair
--   FIFO queue.
readBoundedChan :: MonadConc m => BoundedChan m a -> m a

-- | A variant of <a>readBoundedChan</a> which, instead of blocking when
--   the channel is empty, immediately returns <a>Nothing</a>. Otherwise,
--   <a>tryreadBoundedChan</a> returns <tt><a>Just</a> a</tt> where
--   <tt>a</tt> is the element read from the channel. Note that this
--   routine can still block while waiting for read access to the channel.
tryreadBoundedChan :: MonadConc m => BoundedChan m a -> m (Maybe a)

-- | Returns <a>True</a> if the supplied channel is empty.
--   
--   NOTE: This may block on an empty channel if there is a blocked reader.
--   NOTE: This function is deprecated.

-- | <i>Deprecated: This isEmptyBoundedChan can block, no non-blocking
--   substitute yet</i>
isEmptyBoundedChan :: MonadConc m => BoundedChan m a -> m Bool

-- | Write a list of elements to the channel. If the channel becomes full,
--   this routine will block until it can write. Competing writers may
--   interleave with this one.
writeList2BoundedChan :: MonadConc m => BoundedChan m a -> [a] -> m ()


-- | Transactional variables, for use with <a>MonadSTM</a>.
--   
--   <b>Deviations:</b> There is no <tt>Eq</tt> instance for
--   <tt>MonadSTM</tt> the <tt>TVar</tt> type. Furthermore, the
--   <tt>newTVarIO</tt> and <tt>mkWeakTVar</tt> functions are not provided.
module Control.Concurrent.Classy.STM.TVar

-- | The mutable reference type. These behave like <a>TVar</a>s, in that
--   they always contain a value and updates are non-blocking and
--   synchronised.
type family TVar stm :: Type -> Type

-- | Create a new <tt>TVar</tt> containing the given value.
--   
--   <pre>
--   newTVar = newTVarN ""
--   </pre>
newTVar :: MonadSTM stm => a -> stm (TVar stm a)

-- | Create a new <tt>TVar</tt> containing the given value, but it is given
--   a name which may be used to present more useful debugging information.
--   
--   If an empty name is given, a counter starting from 0 is used. If names
--   conflict, successive <tt>TVar</tt>s with the same name are given a
--   numeric suffix, counting up from 1.
--   
--   <pre>
--   newTVarN _ = newTVar
--   </pre>
newTVarN :: MonadSTM stm => String -> a -> stm (TVar stm a)

-- | Return the current value stored in a <tt>TVar</tt>.
readTVar :: MonadSTM stm => TVar stm a -> stm a

-- | Read the current value stored in a <tt>TVar</tt>. This may be
--   implemented differently for speed.
--   
--   <pre>
--   readTVarConc = atomically . readTVar
--   </pre>
readTVarConc :: MonadConc m => TVar (STM m) a -> m a

-- | Write the supplied value into the <tt>TVar</tt>.
writeTVar :: MonadSTM stm => TVar stm a -> a -> stm ()

-- | Mutate the contents of a <a>TVar</a>. This is non-strict.
modifyTVar :: MonadSTM stm => TVar stm a -> (a -> a) -> stm ()

-- | Mutate the contents of a <a>TVar</a> strictly.
modifyTVar' :: MonadSTM stm => TVar stm a -> (a -> a) -> stm ()

-- | Like <a>modifyTVar'</a> but the function is a simple state transition
--   that can return a side value which is passed on as the result of the
--   STM.
stateTVar :: MonadSTM stm => TVar stm s -> (s -> (a, s)) -> stm a

-- | Swap the contents of a <a>TVar</a>, returning the old value.
swapTVar :: MonadSTM stm => TVar stm a -> a -> stm a

-- | Set the value of returned <a>TVar</a> to <tt>True</tt> after a given
--   number of microseconds. The caveats associated with <a>threadDelay</a>
--   also apply.
registerDelay :: MonadConc m => Int -> m (TVar (STM m) Bool)


-- | <a>TSem</a>: transactional semaphores.
--   
--   <b>Deviations:</b> There is no <tt>Eq</tt> instance for <tt>TSem</tt>
--   type.
module Control.Concurrent.Classy.STM.TSem

-- | <a>TSem</a> is a transactional semaphore. It holds a certain number of
--   units, and units may be acquired or released by <a>waitTSem</a> and
--   <a>signalTSem</a> respectively. When the <a>TSem</a> is empty,
--   <a>waitTSem</a> blocks.
--   
--   Note that <a>TSem</a> has no concept of fairness, and there is no
--   guarantee that threads blocked in <a>waitTSem</a> will be unblocked in
--   the same order; in fact they will all be unblocked at the same time
--   and will fight over the <a>TSem</a>. Hence <a>TSem</a> is not suitable
--   if you expect there to be a high number of threads contending for the
--   resource. However, like other STM abstractions, <a>TSem</a> is
--   composable.
data TSem stm

-- | Construct new <a>TSem</a> with an initial counter value.
--   
--   A positive initial counter value denotes availability of units
--   <a>waitTSem</a> can acquire.
--   
--   The initial counter value can be negative which denotes a resource
--   "debt" that requires a respective amount of <a>signalTSem</a>
--   operations to counter-balance.
newTSem :: MonadSTM stm => Integer -> stm (TSem stm)

-- | Wait on <a>TSem</a> (aka <b>P</b> operation).
--   
--   This operation acquires a unit from the semaphore (i.e. decreases the
--   internal counter) and blocks (via <a>retry</a>) if no units are
--   available (i.e. if the counter is <i>not</i> positive).
waitTSem :: MonadSTM stm => TSem stm -> stm ()

-- | Signal a <a>TSem</a> (aka <b>V</b> operation).
--   
--   This operation adds/releases a unit back to the semaphore (i.e.
--   increments the internal counter).
signalTSem :: MonadSTM stm => TSem stm -> stm ()

-- | Multi-signal a <a>TSem</a>
--   
--   This operation adds/releases multiple units back to the semaphore
--   (i.e. increments the internal counter).
--   
--   <pre>
--   signalTSem == signalTSemN 1
--   </pre>
signalTSemN :: MonadSTM stm => Natural -> TSem stm -> stm ()


-- | A <a>TQueue</a> is like a <tt>TChan</tt>, with two important
--   differences:
--   
--   <ul>
--   <li>it has faster throughput than both <tt>TChan</tt> and
--   <tt>Chan</tt> (although the costs are amortised, so the cost of
--   individual operations can vary a lot).</li>
--   <li>it does <i>not</i> provide equivalents of the <tt>dupTChan</tt>
--   and <tt>cloneTChan</tt> operations.</li>
--   </ul>
--   
--   The implementation is based on the traditional purely-functional queue
--   representation that uses two lists to obtain amortised <i>O(1)</i>
--   enqueue and dequeue operations.
--   
--   <b>Deviations:</b> <tt>TQueue</tt> as defined here does not have an
--   <tt>Eq</tt> instance, this is because the <tt>MonadSTM</tt>
--   <tt>TVar</tt> type does not have an <tt>Eq</tt> constraint.
--   Furthermore, the <tt>newTQueueIO</tt> function is not provided.
module Control.Concurrent.Classy.STM.TQueue

-- | <a>TQueue</a> is an abstract type representing an unbounded FIFO
--   channel.
data TQueue stm a

-- | Build and returns a new instance of <a>TQueue</a>
newTQueue :: MonadSTM stm => stm (TQueue stm a)

-- | Read the next value from the <a>TQueue</a>.
readTQueue :: MonadSTM stm => TQueue stm a -> stm a

-- | A version of <a>readTQueue</a> which does not retry. Instead it
--   returns <tt>Nothing</tt> if no value is available.
tryReadTQueue :: MonadSTM stm => TQueue stm a -> stm (Maybe a)

-- | Efficiently read the entire contents of a <a>TQueue</a> into a list.
--   This function never retries.
flushTQueue :: MonadSTM stm => TQueue stm a -> stm [a]

-- | Get the next value from the <tt>TQueue</tt> without removing it,
--   retrying if the channel is empty.
peekTQueue :: MonadSTM stm => TQueue stm a -> stm a

-- | A version of <a>peekTQueue</a> which does not retry. Instead it
--   returns <tt>Nothing</tt> if no value is available.
tryPeekTQueue :: MonadSTM stm => TQueue stm a -> stm (Maybe a)

-- | Write a value to a <a>TQueue</a>.
writeTQueue :: MonadSTM stm => TQueue stm a -> a -> stm ()

-- | Put a data item back onto a channel, where it will be the next item
--   read.
unGetTQueue :: MonadSTM stm => TQueue stm a -> a -> stm ()

-- | Returns <a>True</a> if the supplied <a>TQueue</a> is empty.
isEmptyTQueue :: MonadSTM stm => TQueue stm a -> stm Bool


-- | Transactional <tt>MVar</tt>s, for use with <a>MonadSTM</a>.
--   
--   <b>Deviations:</b> <tt>TMVar</tt> as defined here does not have an
--   <tt>Eq</tt> instance, this is because the <tt>MonadSTM</tt>
--   <tt>TVar</tt> type does not have an <tt>Eq</tt> constraint.
--   Furthermore, the <tt>newTMVarIO</tt>, <tt>newEmptyTMVarIO</tt>, and
--   <tt>mkWeakTMVar</tt> functions are not provided.
module Control.Concurrent.Classy.STM.TMVar

-- | A <tt>TMVar</tt> is like an <tt>MVar</tt> or a <tt>mVar</tt>, but
--   using transactional memory. As transactions are atomic, this makes
--   dealing with multiple <tt>TMVar</tt>s easier than wrangling multiple
--   <tt>mVar</tt>s.
data TMVar stm a

-- | Create a <a>TMVar</a> containing the given value.
newTMVar :: MonadSTM stm => a -> stm (TMVar stm a)

-- | Create a <a>TMVar</a> containing the given value, with the given name.
--   
--   Name conflicts are handled as usual for <a>TVar</a>s. The name is
--   prefixed with "ctmvar-".
newTMVarN :: MonadSTM stm => String -> a -> stm (TMVar stm a)

-- | Create a new empty <a>TMVar</a>.
newEmptyTMVar :: MonadSTM stm => stm (TMVar stm a)

-- | Create a new empty <a>TMVar</a> with the given name.
--   
--   Name conflicts are handled as usual for <a>TVar</a>s. The name is
--   prefixed with "ctmvar-".
newEmptyTMVarN :: MonadSTM stm => String -> stm (TMVar stm a)

-- | Take the contents of a <a>TMVar</a>, or <a>retry</a> if it is empty.
takeTMVar :: MonadSTM stm => TMVar stm a -> stm a

-- | Write to a <a>TMVar</a>, or <a>retry</a> if it is full.
putTMVar :: MonadSTM stm => TMVar stm a -> a -> stm ()

-- | Read from a <a>TMVar</a> without emptying, or <a>retry</a> if it is
--   empty.
readTMVar :: MonadSTM stm => TMVar stm a -> stm a

-- | Try to take the contents of a <a>TMVar</a>, returning <a>Nothing</a>
--   if it is empty.
tryTakeTMVar :: MonadSTM stm => TMVar stm a -> stm (Maybe a)

-- | Try to write to a <a>TMVar</a>, returning <a>False</a> if it is full.
tryPutTMVar :: MonadSTM stm => TMVar stm a -> a -> stm Bool

-- | Try to read from a <a>TMVar</a> without emptying, returning
--   <a>Nothing</a> if it is empty.
tryReadTMVar :: MonadSTM stm => TMVar stm a -> stm (Maybe a)

-- | Check if a <a>TMVar</a> is empty or not.
isEmptyTMVar :: MonadSTM stm => TMVar stm a -> stm Bool

-- | Swap the contents of a <a>TMVar</a> returning the old contents, or
--   <a>retry</a> if it is empty.
swapTMVar :: MonadSTM stm => TMVar stm a -> a -> stm a


-- | Transactional channels
--   
--   <b>Deviations:</b> <tt>TChan</tt> as defined here does not have an
--   <tt>Eq</tt> instance, this is because the <tt>MonadSTM</tt>
--   <tt>TVar</tt> type does not have an <tt>Eq</tt> constraint.
--   Furthermore, the <tt>newTChanIO</tt> and <tt>newBroadcastTChanIO</tt>
--   functions are not provided.
module Control.Concurrent.Classy.STM.TChan

-- | <a>TChan</a> is an abstract type representing an unbounded FIFO
--   channel.
data TChan stm a

-- | Build and return a new instance of <a>TChan</a>
newTChan :: MonadSTM stm => stm (TChan stm a)

-- | Create a write-only <a>TChan</a>. More precisely, <a>readTChan</a>
--   will <a>retry</a> even after items have been written to the channel.
--   The only way to read a broadcast channel is to duplicate it with
--   <a>dupTChan</a>.
newBroadcastTChan :: MonadSTM stm => stm (TChan stm a)

-- | Duplicate a <a>TChan</a>: the duplicate channel begins empty, but data
--   written to either channel from then on will be available from both.
--   Hence this creates a kind of broadcast channel, where data written by
--   anyone is seen by everyone else.
dupTChan :: MonadSTM stm => TChan stm a -> stm (TChan stm a)

-- | Clone a <a>TChan</a>: similar to <a>dupTChan</a>, but the cloned
--   channel starts with the same content available as the original
--   channel.
cloneTChan :: MonadSTM stm => TChan stm a -> stm (TChan stm a)

-- | Read the next value from the <a>TChan</a>.
readTChan :: MonadSTM stm => TChan stm a -> stm a

-- | A version of <a>readTChan</a> which does not retry. Instead it returns
--   <tt>Nothing</tt> if no value is available.
tryReadTChan :: MonadSTM stm => TChan stm a -> stm (Maybe a)

-- | Get the next value from the <a>TChan</a> without removing it, retrying
--   if the channel is empty.
peekTChan :: MonadSTM stm => TChan stm a -> stm a

-- | A version of <a>peekTChan</a> which does not retry. Instead it returns
--   <tt>Nothing</tt> if no value is available.
tryPeekTChan :: MonadSTM stm => TChan stm a -> stm (Maybe a)

-- | Write a value to a <a>TChan</a>.
writeTChan :: MonadSTM stm => TChan stm a -> a -> stm ()

-- | Put a data item back onto a channel, where it will be the next item
--   read.
unGetTChan :: MonadSTM stm => TChan stm a -> a -> stm ()

-- | Returns <a>True</a> if the supplied <a>TChan</a> is empty.
isEmptyTChan :: MonadSTM stm => TChan stm a -> stm Bool


-- | <a>TBQueue</a> is a bounded version of <tt>TQueue</tt>. The queue has
--   a maximum capacity set when it is created. If the queue already
--   contains the maximum number of elements, then <a>writeTBQueue</a>
--   blocks until an element is removed from the queue.
--   
--   The implementation is based on the traditional purely-functional queue
--   representation that uses two lists to obtain amortised <i>O(1)</i>
--   enqueue and dequeue operations.
--   
--   <b>Deviations:</b> <tt>TBQueue</tt> as defined here does not have an
--   <tt>Eq</tt> instance, this is because the <tt>MonadSTM</tt>
--   <tt>TVar</tt> type does not have an <tt>Eq</tt> constraint.
--   Furthermore, the <tt>newTBQueueIO</tt> function is not provided.
module Control.Concurrent.Classy.STM.TBQueue

-- | <a>TBQueue</a> is an abstract type representing a bounded FIFO
--   channel.
data TBQueue stm a

-- | Builds and returns a new instance of <a>TBQueue</a>
newTBQueue :: MonadSTM stm => Natural -> stm (TBQueue stm a)

-- | Read the next value from the <a>TBQueue</a>.
readTBQueue :: MonadSTM stm => TBQueue stm a -> stm a

-- | A version of <a>readTBQueue</a> which does not retry. Instead it
--   returns <tt>Nothing</tt> if no value is available.
tryReadTBQueue :: MonadSTM stm => TBQueue stm a -> stm (Maybe a)

-- | Efficiently read the entire contents of a <a>TBQueue</a> into a list.
--   This function never retries.
flushTBQueue :: MonadSTM stm => TBQueue stm a -> stm [a]

-- | Get the next value from the <tt>TBQueue</tt> without removing it,
--   retrying if the channel is empty.
peekTBQueue :: MonadSTM stm => TBQueue stm a -> stm a

-- | A version of <a>peekTBQueue</a> which does not retry. Instead it
--   returns <tt>Nothing</tt> if no value is available.
tryPeekTBQueue :: MonadSTM stm => TBQueue stm a -> stm (Maybe a)

-- | Write a value to a <a>TBQueue</a>; retries if the queue is full.
writeTBQueue :: MonadSTM stm => TBQueue stm a -> a -> stm ()

-- | Put a data item back onto a channel, where it will be the next item
--   read. Retries if the queue is full.
unGetTBQueue :: MonadSTM stm => TBQueue stm a -> a -> stm ()

-- | Return the length of a <a>TBQueue</a>.
lengthTBQueue :: MonadSTM stm => TBQueue stm a -> stm Natural

-- | Returns <a>True</a> if the supplied <a>TBQueue</a> is empty.
isEmptyTBQueue :: MonadSTM stm => TBQueue stm a -> stm Bool

-- | Returns <a>True</a> if the supplied <a>TBQueue</a> is full.
isFullTBQueue :: MonadSTM stm => TBQueue stm a -> stm Bool


-- | <b>Deviations:</b> <tt>TArray</tt> as defined here does not have an
--   <tt>Eq</tt> instance, this is because the <tt>MonadSTM</tt>
--   <tt>TVar</tt> type does not have an <tt>Eq</tt> constraint.
module Control.Concurrent.Classy.STM.TArray

-- | <tt>TArray</tt> is a transactional array, supporting the usual
--   <a>MArray</a> interface for mutable arrays.
--   
--   It is currently implemented as <tt>Array ix (TVar stm e)</tt>, but it
--   may be replaced by a more efficient implementation in the future (the
--   interface will remain the same, however).
data TArray stm i e
instance Control.Monad.STM.Class.MonadSTM stm => Data.Array.Base.MArray (Control.Concurrent.Classy.STM.TArray.TArray stm) e stm


-- | Classy software transactional memory.
module Control.Concurrent.Classy.STM


-- | Classy concurrency.
--   
--   Concurrency is "lightweight", which means that both thread creation
--   and context switching overheads are extremely low. Scheduling of
--   Haskell threads is done internally in the Haskell runtime system, and
--   doesn't make use of any operating system-supplied thread packages.
--   
--   Haskell threads can communicate via <tt>MVar</tt>s, a kind of
--   synchronised mutable variable (see
--   <a>Control.Concurrent.Classy.MVar</a>). Several common concurrency
--   abstractions can be built from <tt>MVar</tt>s, and these are provided
--   by the <a>Control.Concurrent.Classy</a> library. Threads may also
--   communicate via exceptions.
module Control.Concurrent.Classy


-- | This module is a version of the <a>async</a> package. It provides a
--   set of operations for running <tt>MonadConc</tt> operations
--   asynchronously and waiting for their results.
--   
--   For example, assuming a suitable <tt>getURL</tt> function, we can
--   fetch the contents of two web pages at the same time:
--   
--   <pre>
--   withAsync (getURL url1) $ \a1 -&gt; do
--   withAsync (getURL url2) $ \a2 -&gt; do
--   page1 &lt;- wait a1
--   page2 &lt;- wait a2
--   ...
--   </pre>
--   
--   The <a>withAsync</a> function starts an operation in a separate
--   thread, and kills it if the inner action finishes before it completes.
--   
--   Unlike the regular async package, the <tt>Alternative</tt> instance
--   for <a>Concurrently</a> uses <tt>forever yield</tt> in the definition
--   of <tt>empty</tt>, rather than <tt>forever (threadDelay
--   maxBound)</tt>.
module Control.Concurrent.Classy.Async

-- | An asynchronous action spawned by <a>async</a> or <a>withAsync</a>.
--   Asynchronous actions are executed in a separate thread, and operations
--   are provided for waiting for asynchronous actions to complete and
--   obtaining their results (see e.g. <a>wait</a>).
--   
--   Note that, unlike the "async" package, <a>Async</a> here does not have
--   an <a>Ord</a> instance. This is because <a>MonadConc</a>
--   <a>ThreadId</a>s do not necessarily have one.
data Async m a

-- | Spawn an asynchronous action in a separate thread.
async :: MonadConc m => m a -> m (Async m a)

-- | Like <a>async</a>, but using a named thread for better debugging
--   information.
asyncN :: MonadConc m => String -> m a -> m (Async m a)

-- | Like <a>async</a> but uses <a>forkOS</a> internally.
asyncBound :: MonadConc m => m a -> m (Async m a)

-- | Like <a>asyncBound</a>, but using a named thread for better debugging
--   information.
asyncBoundN :: MonadConc m => String -> m a -> m (Async m a)

-- | Like <a>async</a> but using <a>forkOn</a> internally.
asyncOn :: MonadConc m => Int -> m a -> m (Async m a)

-- | Like <a>asyncOn</a> but using a named thread for better debugging
--   information.
asyncOnN :: MonadConc m => String -> Int -> m a -> m (Async m a)

-- | Like <a>async</a> but using <a>forkWithUnmask</a> internally.
asyncWithUnmask :: MonadConc m => ((forall b. m b -> m b) -> m a) -> m (Async m a)

-- | Like <a>asyncWithUnmask</a> but using a named thread for better
--   debugging information.
asyncWithUnmaskN :: MonadConc m => String -> ((forall b. m b -> m b) -> m a) -> m (Async m a)

-- | Like <a>asyncOn</a> but using <a>forkOnWithUnmask</a> internally.
asyncOnWithUnmask :: MonadConc m => Int -> ((forall b. m b -> m b) -> m a) -> m (Async m a)

-- | Like <a>asyncOnWithUnmask</a> but using a named thread for better
--   debugging information.
asyncOnWithUnmaskN :: MonadConc m => String -> Int -> ((forall b. m b -> m b) -> m a) -> m (Async m a)

-- | Spawn an asynchronous action in a separate thread, and pass its
--   <tt>Async</tt> handle to the supplied function. When the function
--   returns or throws an exception, <a>uninterruptibleCancel</a> is called
--   on the <tt>Async</tt>.
--   
--   <pre>
--   withAsync action inner = bracket (async action) uninterruptiblCancel inner
--   </pre>
--   
--   This is a useful variant of <a>async</a> that ensures an
--   <tt>Async</tt> is never left running unintentionally.
--   
--   Since <a>uninterruptibleCancel</a> may block, <a>withAsync</a> may
--   also block; see <a>uninterruptibleCancel</a> for details.
withAsync :: MonadConc m => m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsync</a> but using a named thread for better debugging
--   information.
withAsyncN :: MonadConc m => String -> m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsync</a> but uses <a>forkOS</a> internally.
withAsyncBound :: MonadConc m => m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsyncBound</a> but using a named thread for better
--   debugging information.
withAsyncBoundN :: MonadConc m => String -> m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsync</a> but uses <a>forkOn</a> internally.
withAsyncOn :: MonadConc m => Int -> m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsyncOn</a> but using a named thread for better debugging
--   information.
withAsyncOnN :: MonadConc m => String -> Int -> m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsync</a> bit uses <a>forkWithUnmask</a> internally.
withAsyncWithUnmask :: MonadConc m => ((forall x. m x -> m x) -> m a) -> (Async m a -> m b) -> m b

-- | Like <a>withAsyncWithUnmask</a> but using a named thread for better
--   debugging information.
withAsyncWithUnmaskN :: MonadConc m => String -> ((forall x. m x -> m x) -> m a) -> (Async m a -> m b) -> m b

-- | Like <a>withAsyncOn</a> bit uses <a>forkOnWithUnmask</a> internally.
withAsyncOnWithUnmask :: MonadConc m => Int -> ((forall x. m x -> m x) -> m a) -> (Async m a -> m b) -> m b

-- | Like <a>withAsyncOnWithUnmask</a> but using a named thread for better
--   debugging information.
withAsyncOnWithUnmaskN :: MonadConc m => String -> Int -> ((forall x. m x -> m x) -> m a) -> (Async m a -> m b) -> m b

-- | Wait for an asynchronous action to complete, and return its value. If
--   the asynchronous value threw an exception, then the exception is
--   re-thrown by <a>wait</a>.
--   
--   <pre>
--   wait = atomically . waitSTM
--   </pre>
wait :: MonadConc m => Async m a -> m a

-- | A version of <a>wait</a> that can be used inside a <tt>MonadSTM</tt>
--   transaction.
waitSTM :: MonadConc m => Async m a -> STM m a

-- | Check whether an <a>Async</a> has completed yet. If it has not
--   completed yet, then the result is <tt>Nothing</tt>, otherwise the
--   result is <tt>Just e</tt> where <tt>e</tt> is <tt>Left x</tt> if the
--   <tt>Async</tt> raised an exception <tt>x</tt>, or <tt>Right a</tt> if
--   it returned a value <tt>a</tt>.
--   
--   <pre>
--   poll = atomically . pollSTM
--   </pre>
poll :: MonadConc m => Async m a -> m (Maybe (Either SomeException a))

-- | A version of <a>poll</a> that can be used inside a <tt>MonadSTM</tt>
--   transaction.
pollSTM :: MonadConc m => Async m a -> STM m (Maybe (Either SomeException a))

-- | Wait for an asynchronous action to complete, and return either
--   <tt>Left e</tt> if the action raised an exception <tt>e</tt>, or
--   <tt>Right a</tt> if it returned a value <tt>a</tt>.
waitCatch :: MonadConc m => Async m a -> m (Either SomeException a)

-- | A version of <a>waitCatch</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitCatchSTM :: MonadConc m => Async m a -> STM m (Either SomeException a)

-- | Cancel an asynchronous action by throwing the <tt>ThreadKilled</tt>
--   exception to it, and waiting for the <a>Async</a> thread to quit. Has
--   no effect if the <a>Async</a> has already completed.
--   
--   <pre>
--   cancel a = throwTo (asyncThreadId a) ThreadKilled &lt;* waitCatch a
--   </pre>
--   
--   Note that <a>cancel</a> will not terminate until the thread the
--   <a>Async</a> refers to has terminated. This means that <a>cancel</a>
--   will block for as long as said thread blocks when receiving an
--   asynchronous exception.
--   
--   An asynchronous <a>cancel</a> can of course be obtained by wrapping
--   <a>cancel</a> itself in <a>async</a>.
cancel :: MonadConc m => Async m a -> m ()

-- | Cancel an asynchronous action.
--   
--   This is a variant of <a>cancel</a> but it is not interruptible.
uninterruptibleCancel :: MonadConc m => Async m a -> m ()

-- | Cancel an asynchronous action by throwing the supplied exception to
--   it.
--   
--   <pre>
--   cancelWith a e = throwTo (asyncThreadId a) e
--   </pre>
--   
--   The notes about the synchronous nature of <a>cancel</a> also apply to
--   <a>cancelWith</a>.
cancelWith :: (MonadConc m, Exception e) => Async m a -> e -> m ()
asyncThreadId :: Async m a -> ThreadId m

-- | Wait for any of the supplied <a>Async</a>s to complete. If the first
--   to complete throws an exception, then that exception is re-thrown by
--   <a>waitAny</a>.
--   
--   If multiple <a>Async</a>s complete or have completed, then the value
--   returned corresponds to the first completed <a>Async</a> in the list.
waitAny :: MonadConc m => [Async m a] -> m (Async m a, a)

-- | A version of <a>waitAny</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitAnySTM :: MonadConc m => [Async m a] -> STM m (Async m a, a)

-- | Wait for any of the supplied asynchronous operations to complete. The
--   value returned is a pair of the <a>Async</a> that completed, and the
--   result that would be returned by <a>wait</a> on that <a>Async</a>.
--   
--   If multiple <a>Async</a>s complete or have completed, then the value
--   returned corresponds to the first completed <a>Async</a> in the list.
waitAnyCatch :: MonadConc m => [Async m a] -> m (Async m a, Either SomeException a)

-- | A version of <a>waitAnyCatch</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitAnyCatchSTM :: MonadConc m => [Async m a] -> STM m (Async m a, Either SomeException a)

-- | Like <a>waitAny</a>, but also cancels the other asynchronous
--   operations as soon as one has completed.
waitAnyCancel :: MonadConc m => [Async m a] -> m (Async m a, a)

-- | Like <a>waitAnyCatch</a>, but also cancels the other asynchronous
--   operations as soon as one has completed.
waitAnyCatchCancel :: MonadConc m => [Async m a] -> m (Async m a, Either SomeException a)

-- | Wait for the first of two <tt>Async</tt>s to finish. If the
--   <tt>Async</tt> that finished first raised an exception, then the
--   exception is re-thrown by <a>waitEither</a>.
waitEither :: MonadConc m => Async m a -> Async m b -> m (Either a b)

-- | A version of <a>waitEither</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitEitherSTM :: MonadConc m => Async m a -> Async m b -> STM m (Either a b)

-- | Wait for the first of two <tt>Async</tt>s to finish.
waitEitherCatch :: MonadConc m => Async m a -> Async m b -> m (Either (Either SomeException a) (Either SomeException b))

-- | A version of <a>waitEitherCatch</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitEitherCatchSTM :: MonadConc m => Async m a -> Async m b -> STM m (Either (Either SomeException a) (Either SomeException b))

-- | Like <a>waitEither</a>, but also <a>cancel</a>s both <tt>Async</tt>s
--   before returning.
waitEitherCancel :: MonadConc m => Async m a -> Async m b -> m (Either a b)

-- | Like <a>waitEitherCatch</a>, but also <a>cancel</a>s both
--   <tt>Async</tt>s before returning.
waitEitherCatchCancel :: MonadConc m => Async m a -> Async m b -> m (Either (Either SomeException a) (Either SomeException b))

-- | Like <a>waitEither</a>, but the result is ignored.
waitEither_ :: MonadConc m => Async m a -> Async m b -> m ()

-- | A version of <a>waitEither_</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitEitherSTM_ :: MonadConc m => Async m a -> Async m b -> STM m ()

-- | Waits for both <tt>Async</tt>s to finish, but if either of them throws
--   an exception before they have both finished, then the exception is
--   re-thrown by <a>waitBoth</a>.
waitBoth :: MonadConc m => Async m a -> Async m b -> m (a, b)

-- | A version of <a>waitBoth</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitBothSTM :: MonadConc m => Async m a -> Async m b -> STM m (a, b)

-- | Link the given <tt>Async</tt> to the current thread, such that if the
--   <tt>Async</tt> raises an exception, that exception will be re-thrown
--   in the current thread.
link :: MonadConc m => Async m a -> m ()

-- | Link two <tt>Async</tt>s together, such that if either raises an
--   exception, the same exception is re-thrown in the other
--   <tt>Async</tt>.
link2 :: MonadConc m => Async m a -> Async m b -> m ()

-- | Run two <tt>MonadConc</tt> actions concurrently, and return the first
--   to finish. The loser of the race is <a>cancel</a>led.
--   
--   <pre>
--   race left right =
--     withAsync left $ \a -&gt;
--     withAsync right $ \b -&gt;
--     waitEither a b
--   </pre>
race :: MonadConc m => m a -> m b -> m (Either a b)

-- | Like <a>race</a>, but the result is ignored.
--   
--   <pre>
--   race_ left right =
--     withAsync left $ \a -&gt;
--     withAsync right $ \b -&gt;
--     waitEither_ a b
--   </pre>
race_ :: MonadConc m => m a -> m b -> m ()

-- | Run two <tt>MonadConc</tt> actions concurrently, and return both
--   results. If either action throws an exception at any time, then the
--   other action is <a>cancel</a>led, and the exception is re-thrown by
--   <a>concurrently</a>.
--   
--   <pre>
--   concurrently left right =
--     withAsync left $ \a -&gt;
--     withAsync right $ \b -&gt;
--     waitBoth a b
--   </pre>
concurrently :: MonadConc m => m a -> m b -> m (a, b)

-- | <a>concurrently_</a> is <a>concurrently</a> but ignores the return
--   values.
concurrently_ :: MonadConc m => m a -> m b -> m ()

-- | Maps a <tt>MonadConc</tt>-performing function over any
--   <tt>Traversable</tt> data type, performing all the <tt>MonadConc</tt>
--   actions concurrently, and returning the original data structure with
--   the arguments replaced by the results.
--   
--   For example, <tt>mapConcurrently</tt> works with lists:
--   
--   <pre>
--   pages &lt;- mapConcurrently getURL ["url1", "url2", "url3"]
--   </pre>
mapConcurrently :: (Traversable t, MonadConc m) => (a -> m b) -> t a -> m (t b)

-- | <a>mapConcurrently_</a> is <a>mapConcurrently</a> with the return
--   value discarded, just like <a>mapM_</a>.
mapConcurrently_ :: (Foldable f, MonadConc m) => (a -> m b) -> f a -> m ()

-- | <a>forConcurrently</a> is <a>mapConcurrently</a> with its arguments
--   flipped
--   
--   <pre>
--   pages &lt;- forConcurrently ["url1", "url2", "url3"] $ \url -&gt; getURL url
--   </pre>
forConcurrently :: (Traversable t, MonadConc m) => t a -> (a -> m b) -> m (t b)

-- | <a>forConcurrently_</a> is <a>forConcurrently</a> with the return
--   value discarded, just like <a>forM_</a>.
forConcurrently_ :: (Foldable f, MonadConc m) => f a -> (a -> m b) -> m ()

-- | Perform the action in the given number of threads.
replicateConcurrently :: MonadConc m => Int -> m a -> m [a]

-- | <a>replicateConcurrently_</a> is <a>replicateConcurrently</a> with the
--   return values discarded.
replicateConcurrently_ :: MonadConc m => Int -> m a -> m ()

-- | A value of type <tt>Concurrently m a</tt> is a <tt>MonadConc</tt>
--   operation that can be composed with other <tt>Concurrently</tt>
--   values, using the <tt>Applicative</tt> and <tt>Alternative</tt>
--   instances.
--   
--   Calling <tt>runConcurrently</tt> on a value of type <tt>Concurrently m
--   a</tt> will execute the <tt>MonadConc</tt> operations it contains
--   concurrently, before delivering the result of type <tt>a</tt>.
--   
--   For example
--   
--   <pre>
--   (page1, page2, page3)
--     &lt;- runConcurrently $ (,,)
--     &lt;$&gt; Concurrently (getURL "url1")
--     &lt;*&gt; Concurrently (getURL "url2")
--     &lt;*&gt; Concurrently (getURL "url3")
--   </pre>
newtype Concurrently m a
Concurrently :: m a -> Concurrently m a
[runConcurrently] :: Concurrently m a -> m a
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Functor (Control.Concurrent.Classy.Async.Concurrently m)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Applicative (Control.Concurrent.Classy.Async.Concurrently m)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Alternative (Control.Concurrent.Classy.Async.Concurrently m)
instance (Control.Monad.Conc.Class.MonadConc m, GHC.Base.Semigroup a) => GHC.Base.Semigroup (Control.Concurrent.Classy.Async.Concurrently m a)
instance (Control.Monad.Conc.Class.MonadConc m, GHC.Base.Monoid a) => GHC.Base.Monoid (Control.Concurrent.Classy.Async.Concurrently m a)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Classes.Eq (Control.Concurrent.Classy.Async.Async m a)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Functor (Control.Concurrent.Classy.Async.Async m)
