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


-- | Software Transactional Memory
--   
--   Software Transactional Memory, or STM, is an abstraction for
--   concurrent communication. The main benefits of STM are
--   <i>composability</i> and <i>modularity</i>. That is, using STM you can
--   write concurrent abstractions that can be easily composed with any
--   other abstraction built using STM, without exposing the details of how
--   your abstraction ensures safety. This is typically not the case with
--   other forms of concurrent communication, such as locks or
--   <a>MVar</a>s.
@package stm
@version 2.5.0.0


-- | <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

-- | Builds and returns a new instance of <a>TBQueue</a>.
newTBQueue :: Natural -> 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
--   <tt>atomically</tt> inside <a>unsafePerformIO</a> isn't possible.
newTBQueueIO :: Natural -> 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)

-- | Efficiently read the entire contents of a <a>TBQueue</a> into a list.
--   This function never retries.
flushTBQueue :: TBQueue a -> STM [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 ()

-- | Return the length of a <a>TBQueue</a>.
lengthTBQueue :: TBQueue a -> STM Natural

-- | 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)


-- | 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)


-- | 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)


-- | 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)

-- | Efficiently read the entire contents of a <a>TQueue</a> into a list.
--   This function never retries.
flushTQueue :: TQueue a -> STM [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)


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

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

-- | Create a new <a>TVar</a> 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 <a>TVar</a>.
readTVar :: TVar a -> STM a

-- | Return the current value stored in a <a>TVar</a>. 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 <a>TVar</a>.
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 ()

-- | 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
--   <a>STM</a>.
stateTVar :: TVar s -> (s -> (a, s)) -> STM a

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

-- | Switch the value of returned <a>TVar</a> from initial value
--   <a>False</a> to <a>True</a> after a given number of microseconds. The
--   caveats associated with <a>threadDelay</a> 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))


-- | 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 <i>ACM Conference
--   on Principles and Practice of Parallel Programming</i> 2005.
--   <a>https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/</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>).
--   
--   Note that invariant checking (namely the <tt>always</tt> and
--   <tt>alwaysSucceeds</tt> functions) has been removed. See ticket
--   <a>#14324</a> and the <a>removal proposal</a>. Existing users are
--   encouraged to encapsulate their STM operations in safe abstractions
--   which can perform the invariant checking without help from the runtime
--   system.
module Control.Monad.STM

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

-- | Perform a series of STM actions atomically.
--   
--   Using <a>atomically</a> inside an <a>unsafePerformIO</a> or
--   <a>unsafeInterleaveIO</a> subverts some of guarantees that STM
--   provides. It makes it possible to run a transaction inside of another
--   transaction, depending on when the thunk is evaluated. If a nested
--   transaction is attempted, an exception is thrown by the runtime. It is
--   possible to safely use <a>atomically</a> inside <a>unsafePerformIO</a>
--   or <a>unsafeInterleaveIO</a>, but the typechecker does not rule out
--   programs that may attempt nested transactions, meaning that the
--   programmer must take special care to prevent these.
--   
--   However, there are functions for creating transactional variables that
--   can always be safely called in <a>unsafePerformIO</a>. See:
--   <a>newTVarIO</a>, <a>newTChanIO</a>, <a>newBroadcastTChanIO</a>,
--   <a>newTQueueIO</a>, <a>newTBQueueIO</a>, and <a>newTMVarIO</a>.
--   
--   Using <a>unsafePerformIO</a> inside of <a>atomically</a> is also
--   dangerous but for different reasons. See <a>unsafeIOToSTM</a> for more
--   on this.
atomically :: STM a -> IO a

-- | Retry execution of the current memory transaction because it has seen
--   values in <a>TVar</a>s which mean that it should not continue (e.g.
--   the <a>TVar</a>s represent a shared buffer that is now empty). The
--   implementation may block the thread until one of the <a>TVar</a>s that
--   it has read from has been updated. (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 <a>orElse</a>. Otherwise, if the first action retries,
--   then the second action is tried in its place. If both actions retry
--   then the <a>orElse</a> as a whole retries.
orElse :: STM a -> STM a -> STM a

-- | Check that the boolean condition is true and, if not, <a>retry</a>.
--   
--   In other words, <tt>check b = unless b retry</tt>.
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. If the exception is caught via
--   <a>catchSTM</a>, only the changes enclosed by the catch are rolled
--   back; changes made outside of <a>catchSTM</a> persist.
--   
--   If the exception is not caught inside of the <a>STM</a>, it is
--   re-thrown by <a>atomically</a>, and the entire <a>STM</a> is rolled
--   back.
--   
--   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.
--   
--   <tt><a>catchSTM</a> m f</tt> catches any exception thrown by
--   <tt>m</tt> using <a>throwSTM</a>, using the function <tt>f</tt> to
--   handle the exception. If an exception is thrown, any changes made by
--   <tt>m</tt> are rolled back, but changes prior to <tt>m</tt> persist.
catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a
instance Control.Monad.Fix.MonadFix 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 <i>ACM Conference
--   on Principles and Practice of Parallel Programming</i> 2005.
--   <a>https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/</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

-- | 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 :: Integer -> STM TSem

-- | 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 :: TSem -> 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 :: TSem -> 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 :: Natural -> TSem -> STM ()
instance GHC.Classes.Eq Control.Concurrent.STM.TSem.TSem
