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


-- | Software Transactional Memory
--   
--   A modular composable concurrency abstraction.
@package stm
@version 2.4.4.1


-- | Software Transactional Memory: a modular composable concurrency
--   abstraction. See
--   
--   <ul>
--   <li><i>Composable memory transactions</i>, by Tim Harris, Simon
--   Marlow, Simon Peyton Jones, and Maurice Herlihy, in /ACM Conference on
--   Principles and Practice of Parallel Programming/ 2005.
--   <a>http://research.microsoft.com/Users/simonpj/papers/stm/index.htm</a></li>
--   </ul>
--   
--   This module only defines the <a>STM</a> monad; you probably want to
--   import <a>Control.Concurrent.STM</a> (which exports
--   <a>Control.Monad.STM</a>).
module Control.Monad.STM

-- | A monad supporting atomic memory transactions.
data STM a :: * -> *

-- | Perform a series of STM actions atomically.
--   
--   You cannot use <a>atomically</a> inside an <a>unsafePerformIO</a> or
--   <a>unsafeInterleaveIO</a>. Any attempt to do so will result in a
--   runtime error. (Reason: allowing this would effectively allow a
--   transaction inside a transaction, depending on exactly when the thunk
--   is evaluated.)
--   
--   However, see <a>newTVarIO</a>, which can be called inside
--   <a>unsafePerformIO</a>, and which allows top-level TVars to be
--   allocated.
atomically :: STM a -> IO a

-- | always is a variant of alwaysSucceeds in which the invariant is
--   expressed as an STM Bool action that must return True. Returning False
--   or raising an exception are both treated as invariant failures.
always :: STM Bool -> STM ()

-- | alwaysSucceeds adds a new invariant that must be true when passed to
--   alwaysSucceeds, at the end of the current transaction, and at the end
--   of every subsequent transaction. If it fails at any of those points
--   then the transaction violating it is aborted and the exception raised
--   by the invariant is propagated.
alwaysSucceeds :: STM a -> STM ()

-- | Retry execution of the current memory transaction because it has seen
--   values in TVars which mean that it should not continue (e.g. the TVars
--   represent a shared buffer that is now empty). The implementation may
--   block the thread until one of the TVars that it has read from has been
--   udpated. (GHC only)
retry :: STM a

-- | Compose two alternative STM actions (GHC only). If the first action
--   completes without retrying then it forms the result of the orElse.
--   Otherwise, if the first action retries, then the second action is
--   tried in its place. If both actions retry then the orElse as a whole
--   retries.
orElse :: STM a -> STM a -> STM a
check :: Bool -> STM ()

-- | A variant of <a>throw</a> that can only be used within the <a>STM</a>
--   monad.
--   
--   Throwing an exception in <tt>STM</tt> aborts the transaction and
--   propagates the exception.
--   
--   Although <a>throwSTM</a> has a type that is an instance of the type of
--   <a>throw</a>, the two functions are subtly different:
--   
--   <pre>
--   throw e    `seq` x  ===&gt; throw e
--   throwSTM e `seq` x  ===&gt; x
--   </pre>
--   
--   The first example will cause the exception <tt>e</tt> to be raised,
--   whereas the second one won't. In fact, <a>throwSTM</a> will only cause
--   an exception to be raised when it is used within the <a>STM</a> monad.
--   The <a>throwSTM</a> variant should be used in preference to
--   <a>throw</a> to raise an exception within the <a>STM</a> monad because
--   it guarantees ordering with respect to other <a>STM</a> operations,
--   whereas <a>throw</a> does not.
throwSTM :: Exception e => e -> STM a

-- | Exception handling within STM actions.
catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a
instance Control.Monad.Fix.MonadFix GHC.Conc.Sync.STM


-- | TVar: Transactional variables
module Control.Concurrent.STM.TVar

-- | Shared memory locations that support atomic memory transactions.
data TVar a :: * -> *

-- | Create a new TVar holding a value supplied
newTVar :: a -> STM (TVar a)

-- | <tt>IO</tt> version of <a>newTVar</a>. This is useful for creating
--   top-level <a>TVar</a>s using <a>unsafePerformIO</a>, because using
--   <a>atomically</a> inside <a>unsafePerformIO</a> isn't possible.
newTVarIO :: a -> IO (TVar a)

-- | Return the current value stored in a TVar
readTVar :: TVar a -> STM a

-- | Return the current value stored in a TVar. This is equivalent to
--   
--   <pre>
--   readTVarIO = atomically . readTVar
--   </pre>
--   
--   but works much faster, because it doesn't perform a complete
--   transaction, it just reads the current value of the <a>TVar</a>.
readTVarIO :: TVar a -> IO a

-- | Write the supplied value into a TVar
writeTVar :: TVar a -> a -> STM ()

-- | Mutate the contents of a <a>TVar</a>. <i>N.B.</i>, this version is
--   non-strict.
modifyTVar :: TVar a -> (a -> a) -> STM ()

-- | Strict version of <a>modifyTVar</a>.
modifyTVar' :: TVar a -> (a -> a) -> STM ()

-- | Swap the contents of a <a>TVar</a> for a new value.
swapTVar :: TVar a -> a -> STM a

-- | Set the value of returned TVar to True after a given number of
--   microseconds. The caveats associated with threadDelay also apply.
registerDelay :: Int -> IO (TVar Bool)

-- | Make a <a>Weak</a> pointer to a <a>TVar</a>, using the second argument
--   as a finalizer to run when <a>TVar</a> is garbage-collected
mkWeakTVar :: TVar a -> IO () -> IO (Weak (TVar a))


-- | 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.
module Control.Concurrent.STM.TQueue

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

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

-- | <tt>IO</tt> version of <a>newTQueue</a>. This is useful for creating
--   top-level <a>TQueue</a>s using <a>unsafePerformIO</a>, because using
--   <a>atomically</a> inside <a>unsafePerformIO</a> isn't possible.
newTQueueIO :: IO (TQueue a)

-- | Read the next value from the <a>TQueue</a>.
readTQueue :: TQueue 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 :: TQueue a -> STM (Maybe a)

-- | Get the next value from the <tt>TQueue</tt> without removing it,
--   retrying if the channel is empty.
peekTQueue :: TQueue 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 :: TQueue a -> STM (Maybe a)

-- | Write a value to a <a>TQueue</a>.
writeTQueue :: TQueue a -> a -> STM ()

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

-- | Returns <a>True</a> if the supplied <a>TQueue</a> is empty.
isEmptyTQueue :: TQueue a -> STM Bool
instance GHC.Classes.Eq (Control.Concurrent.STM.TQueue.TQueue a)


-- | TMVar: Transactional MVars, for use in the STM monad (GHC only)
module Control.Concurrent.STM.TMVar

-- | A <a>TMVar</a> is a synchronising variable, used for communication
--   between concurrent threads. It can be thought of as a box, which may
--   be empty or full.
data TMVar a

-- | Create a <a>TMVar</a> which contains the supplied value.
newTMVar :: a -> STM (TMVar a)

-- | Create a <a>TMVar</a> which is initially empty.
newEmptyTMVar :: STM (TMVar a)

-- | <tt>IO</tt> version of <a>newTMVar</a>. This is useful for creating
--   top-level <a>TMVar</a>s using <a>unsafePerformIO</a>, because using
--   <a>atomically</a> inside <a>unsafePerformIO</a> isn't possible.
newTMVarIO :: a -> IO (TMVar a)

-- | <tt>IO</tt> version of <a>newEmptyTMVar</a>. This is useful for
--   creating top-level <a>TMVar</a>s using <a>unsafePerformIO</a>, because
--   using <a>atomically</a> inside <a>unsafePerformIO</a> isn't possible.
newEmptyTMVarIO :: IO (TMVar a)

-- | Return the contents of the <a>TMVar</a>. If the <a>TMVar</a> is
--   currently empty, the transaction will <a>retry</a>. After a
--   <a>takeTMVar</a>, the <a>TMVar</a> is left empty.
takeTMVar :: TMVar a -> STM a

-- | Put a value into a <a>TMVar</a>. If the <a>TMVar</a> is currently
--   full, <a>putTMVar</a> will <a>retry</a>.
putTMVar :: TMVar a -> a -> STM ()

-- | This is a combination of <a>takeTMVar</a> and <a>putTMVar</a>; ie. it
--   takes the value from the <a>TMVar</a>, puts it back, and also returns
--   it.
readTMVar :: TMVar a -> STM a

-- | A version of <a>readTMVar</a> which does not retry. Instead it returns
--   <tt>Nothing</tt> if no value is available.
tryReadTMVar :: TMVar a -> STM (Maybe a)

-- | Swap the contents of a <a>TMVar</a> for a new value.
swapTMVar :: TMVar a -> a -> STM a

-- | A version of <a>takeTMVar</a> that does not <a>retry</a>. The
--   <a>tryTakeTMVar</a> function returns <a>Nothing</a> if the
--   <a>TMVar</a> was empty, or <tt><a>Just</a> a</tt> if the <a>TMVar</a>
--   was full with contents <tt>a</tt>. After <a>tryTakeTMVar</a>, the
--   <a>TMVar</a> is left empty.
tryTakeTMVar :: TMVar a -> STM (Maybe a)

-- | A version of <a>putTMVar</a> that does not <a>retry</a>. The
--   <a>tryPutTMVar</a> function attempts to put the value <tt>a</tt> into
--   the <a>TMVar</a>, returning <a>True</a> if it was successful, or
--   <a>False</a> otherwise.
tryPutTMVar :: TMVar a -> a -> STM Bool

-- | Check whether a given <a>TMVar</a> is empty.
isEmptyTMVar :: TMVar a -> STM Bool

-- | Make a <a>Weak</a> pointer to a <a>TMVar</a>, using the second
--   argument as a finalizer to run when the <a>TMVar</a> is
--   garbage-collected.
mkWeakTMVar :: TMVar a -> IO () -> IO (Weak (TMVar a))
instance GHC.Classes.Eq (Control.Concurrent.STM.TMVar.TMVar a)


-- | TChan: Transactional channels (GHC only)
module Control.Concurrent.STM.TChan

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

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

-- | <tt>IO</tt> version of <a>newTChan</a>. This is useful for creating
--   top-level <a>TChan</a>s using <a>unsafePerformIO</a>, because using
--   <a>atomically</a> inside <a>unsafePerformIO</a> isn't possible.
newTChanIO :: IO (TChan 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>.
--   
--   Consider a server that broadcasts messages to clients:
--   
--   <pre>
--   serve :: TChan Message -&gt; Client -&gt; IO loop
--   serve broadcastChan client = do
--       myChan &lt;- dupTChan broadcastChan
--       forever $ do
--           message &lt;- readTChan myChan
--           send client message
--   </pre>
--   
--   The problem with using <a>newTChan</a> to create the broadcast channel
--   is that if it is only written to and never read, items will pile up in
--   memory. By using <a>newBroadcastTChan</a> to create the broadcast
--   channel, items can be garbage collected after clients have seen them.
newBroadcastTChan :: STM (TChan a)

-- | <tt>IO</tt> version of <a>newBroadcastTChan</a>.
newBroadcastTChanIO :: IO (TChan 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 :: TChan a -> STM (TChan a)

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

-- | Read the next value from the <a>TChan</a>.
readTChan :: TChan 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 :: TChan a -> STM (Maybe a)

-- | Get the next value from the <tt>TChan</tt> without removing it,
--   retrying if the channel is empty.
peekTChan :: TChan 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 :: TChan a -> STM (Maybe a)

-- | Write a value to a <a>TChan</a>.
writeTChan :: TChan a -> a -> STM ()

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

-- | Returns <a>True</a> if the supplied <a>TChan</a> is empty.
isEmptyTChan :: TChan a -> STM Bool
instance GHC.Classes.Eq (Control.Concurrent.STM.TChan.TChan a)


-- | <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.
module Control.Concurrent.STM.TBQueue

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

-- | Build and returns a new instance of <a>TBQueue</a>
newTBQueue :: Int -> STM (TBQueue a)

-- | <tt>IO</tt> version of <a>newTBQueue</a>. This is useful for creating
--   top-level <a>TBQueue</a>s using <a>unsafePerformIO</a>, because using
--   <a>atomically</a> inside <a>unsafePerformIO</a> isn't possible.
newTBQueueIO :: Int -> IO (TBQueue a)

-- | Read the next value from the <a>TBQueue</a>.
readTBQueue :: TBQueue 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 :: TBQueue a -> STM (Maybe a)

-- | Get the next value from the <tt>TBQueue</tt> without removing it,
--   retrying if the channel is empty.
peekTBQueue :: TBQueue 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 :: TBQueue a -> STM (Maybe a)

-- | Write a value to a <a>TBQueue</a>; blocks if the queue is full.
writeTBQueue :: TBQueue a -> a -> STM ()

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

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

-- | Returns <a>True</a> if the supplied <a>TBQueue</a> is full.
isFullTBQueue :: TBQueue a -> STM Bool
instance GHC.Classes.Eq (Control.Concurrent.STM.TBQueue.TBQueue a)


-- | TArrays: transactional arrays, for use in the STM monad
module Control.Concurrent.STM.TArray

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


-- | Software Transactional Memory: a modular composable concurrency
--   abstraction. See
--   
--   <ul>
--   <li><i>Composable memory transactions</i>, by Tim Harris, Simon
--   Marlow, Simon Peyton Jones, and Maurice Herlihy, in /ACM Conference on
--   Principles and Practice of Parallel Programming/ 2005.
--   <a>http://research.microsoft.com/Users/simonpj/papers/stm/index.htm</a></li>
--   </ul>
module Control.Concurrent.STM


-- | <a>TSem</a>: transactional semaphores.
module Control.Concurrent.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
newTSem :: Int -> STM TSem
waitTSem :: TSem -> STM ()
signalTSem :: TSem -> STM ()
instance GHC.Classes.Eq Control.Concurrent.STM.TSem.TSem
