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


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


-- | <a>TBQueue</a> is a bounded version of <tt>TQueue</tt>. The queue has
gra maximum capacity set when it is created. If the queue already
grcontains the maximum number of elements, then <a>writeTBQueue</a>
grblocks until an element is removed from the queue.
gr
grThe implementation is based on the traditional purely-functional queue
grrepresentation that uses two lists to obtain amortised <i>O(1)</i>
grenqueue and dequeue operations.
module Control.Concurrent.STM.TBQueue

-- | <a>TBQueue</a> is an abstract type representing a bounded FIFO
grchannel.
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
grtop-level <a>TBQueue</a>s using <a>unsafePerformIO</a>, because using
gr<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
grreturns <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.
grThis function never retries.
flushTBQueue :: TBQueue a -> STM [a]

-- | Get the next value from the <tt>TBQueue</tt> without removing it,
grretrying if the channel is empty.
peekTBQueue :: TBQueue a -> STM a

-- | A version of <a>peekTBQueue</a> which does not retry. Instead it
grreturns <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
grread. 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)


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

-- | <a>TChan</a> is an abstract type representing an unbounded FIFO
grchannel.
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
grtop-level <a>TChan</a>s using <a>unsafePerformIO</a>, because using
gr<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>
grwill <a>retry</a> even after items have been written to the channel.
grThe only way to read a broadcast channel is to duplicate it with
gr<a>dupTChan</a>.
gr
grConsider a server that broadcasts messages to clients:
gr
gr<pre>
grserve :: TChan Message -&gt; Client -&gt; IO loop
grserve broadcastChan client = do
gr    myChan &lt;- dupTChan broadcastChan
gr    forever $ do
gr        message &lt;- readTChan myChan
gr        send client message
gr</pre>
gr
grThe problem with using <a>newTChan</a> to create the broadcast channel
gris that if it is only written to and never read, items will pile up in
grmemory. By using <a>newBroadcastTChan</a> to create the broadcast
grchannel, 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
grwritten to either channel from then on will be available from both.
grHence this creates a kind of broadcast channel, where data written by
granyone is seen by everyone else.
dupTChan :: TChan a -> STM (TChan a)

-- | Clone a <a>TChan</a>: similar to dupTChan, but the cloned channel
grstarts 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
gr<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,
grretrying if the channel is empty.
peekTChan :: TChan a -> STM a

-- | A version of <a>peekTChan</a> which does not retry. Instead it returns
gr<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
grread.
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
grbetween concurrent threads. It can be thought of as a box, which may
grbe 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
grtop-level <a>TMVar</a>s using <a>unsafePerformIO</a>, because using
gr<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
grcreating top-level <a>TMVar</a>s using <a>unsafePerformIO</a>, because
grusing <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
grcurrently empty, the transaction will <a>retry</a>. After a
gr<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
grfull, <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
grtakes the value from the <a>TMVar</a>, puts it back, and also returns
grit.
readTMVar :: TMVar a -> STM a

-- | A version of <a>readTMVar</a> which does not retry. Instead it returns
gr<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
gr<a>tryTakeTMVar</a> function returns <a>Nothing</a> if the
gr<a>TMVar</a> was empty, or <tt><a>Just</a> a</tt> if the <a>TMVar</a>
grwas full with contents <tt>a</tt>. After <a>tryTakeTMVar</a>, the
gr<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
gr<a>tryPutTMVar</a> function attempts to put the value <tt>a</tt> into
grthe <a>TMVar</a>, returning <a>True</a> if it was successful, or
gr<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
grargument as a finalizer to run when the <a>TMVar</a> is
grgarbage-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
grdifferences:
gr
gr<ul>
gr<li>it has faster throughput than both <tt>TChan</tt> and
gr<tt>Chan</tt> (although the costs are amortised, so the cost of
grindividual operations can vary a lot).</li>
gr<li>it does <i>not</i> provide equivalents of the <tt>dupTChan</tt>
grand <tt>cloneTChan</tt> operations.</li>
gr</ul>
gr
grThe implementation is based on the traditional purely-functional queue
grrepresentation that uses two lists to obtain amortised <i>O(1)</i>
grenqueue and dequeue operations.
module Control.Concurrent.STM.TQueue

-- | <a>TQueue</a> is an abstract type representing an unbounded FIFO
grchannel.
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
grtop-level <a>TQueue</a>s using <a>unsafePerformIO</a>, because using
gr<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
grreturns <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.
grThis function never retries.
flushTQueue :: TQueue a -> STM [a]

-- | Get the next value from the <tt>TQueue</tt> without removing it,
grretrying if the channel is empty.
peekTQueue :: TQueue a -> STM a

-- | A version of <a>peekTQueue</a> which does not retry. Instead it
grreturns <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
grread.
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
grtop-level <a>TVar</a>s using <a>unsafePerformIO</a>, because using
gr<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
grto
gr
gr<pre>
grreadTVarIO = atomically . readTVar
gr</pre>
gr
grbut works much faster, because it doesn't perform a complete
grtransaction, 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
grnon-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
grmicroseconds. 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
gras 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>
grinterface for mutable arrays.
gr
grIt is currently implemented as <tt>Array ix (TVar e)</tt>, but it may
grbe replaced by a more efficient implementation in the future (the
grinterface 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
grabstraction. See
gr
gr<ul>
gr<li><i>Composable memory transactions</i>, by Tim Harris, Simon
grMarlow, Simon Peyton Jones, and Maurice Herlihy, in <i>ACM Conference
gron Principles and Practice of Parallel Programming</i> 2005.
gr<a>https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/</a></li>
gr</ul>
gr
grThis module only defines the <a>STM</a> monad; you probably want to
grimport <a>Control.Concurrent.STM</a> (which exports
gr<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.
gr
grUsing <a>atomically</a> inside an <a>unsafePerformIO</a> or
gr<a>unsafeInterleaveIO</a> subverts some of guarantees that STM
grprovides. It makes it possible to run a transaction inside of another
grtransaction, depending on when the thunk is evaluated. If a nested
grtransaction is attempted, an exception is thrown by the runtime. It is
grpossible to safely use <a>atomically</a> inside <a>unsafePerformIO</a>
gror <a>unsafeInterleaveIO</a>, but the typechecker does not rule out
grprograms that may attempt nested transactions, meaning that the
grprogrammer must take special care to prevent these.
gr
grHowever, there are functions for creating transactional variables that
grcan always be safely called in <a>unsafePerformIO</a>. See:
gr<a>newTVarIO</a>, <tt>newTChanIO</tt>, <tt>newBroadcastTChanIO</tt>,
gr<tt>newTQueueIO</tt>, <tt>newTBQueueIO</tt>, and <tt>newTMVarIO</tt>.
gr
grUsing <a>unsafePerformIO</a> inside of <a>atomically</a> is also
grdangerous but for different reasons. See <a>unsafeIOToSTM</a> for more
gron this.
atomically :: () => STM a -> IO a

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

-- | <a>alwaysSucceeds</a> adds a new invariant that must be true when
grpassed to <a>alwaysSucceeds</a>, at the end of the current
grtransaction, and at the end of every subsequent transaction. If it
grfails at any of those points then the transaction violating it is
graborted and the exception raised by the invariant is propagated.
alwaysSucceeds :: () => STM a -> STM ()

-- | Retry execution of the current memory transaction because it has seen
grvalues in <a>TVar</a>s which mean that it should not continue (e.g.
grthe <a>TVar</a>s represent a shared buffer that is now empty). The
grimplementation may block the thread until one of the <a>TVar</a>s that
grit has read from has been updated. (GHC only)
retry :: () => STM a

-- | Compose two alternative STM actions (GHC only).
gr
grIf the first action completes without retrying then it forms the
grresult of the <a>orElse</a>. Otherwise, if the first action retries,
grthen the second action is tried in its place. If both actions retry
grthen 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>.
gr
grIn 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>
grmonad.
gr
grThrowing an exception in <tt>STM</tt> aborts the transaction and
grpropagates the exception.
gr
grAlthough <a>throwSTM</a> has a type that is an instance of the type of
gr<a>throw</a>, the two functions are subtly different:
gr
gr<pre>
grthrow e    `seq` x  ===&gt; throw e
grthrowSTM e `seq` x  ===&gt; x
gr</pre>
gr
grThe first example will cause the exception <tt>e</tt> to be raised,
grwhereas the second one won't. In fact, <a>throwSTM</a> will only cause
gran exception to be raised when it is used within the <a>STM</a> monad.
grThe <a>throwSTM</a> variant should be used in preference to
gr<a>throw</a> to raise an exception within the <a>STM</a> monad because
grit guarantees ordering with respect to other <a>STM</a> operations,
grwhereas <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


-- | Software Transactional Memory: a modular composable concurrency
grabstraction. See
gr
gr<ul>
gr<li><i>Composable memory transactions</i>, by Tim Harris, Simon
grMarlow, Simon Peyton Jones, and Maurice Herlihy, in <i>ACM Conference
gron Principles and Practice of Parallel Programming</i> 2005.
gr<a>https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/</a></li>
gr</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
grunits, and units may be acquired or released by <a>waitTSem</a> and
gr<a>signalTSem</a> respectively. When the <a>TSem</a> is empty,
gr<a>waitTSem</a> blocks.
gr
grNote that <a>TSem</a> has no concept of fairness, and there is no
grguarantee that threads blocked in <a>waitTSem</a> will be unblocked in
grthe same order; in fact they will all be unblocked at the same time
grand will fight over the <a>TSem</a>. Hence <a>TSem</a> is not suitable
grif you expect there to be a high number of threads contending for the
grresource. However, like other STM abstractions, <a>TSem</a> is
grcomposable.
data TSem

-- | Construct new <a>TSem</a> with an initial counter value.
gr
grA positive initial counter value denotes availability of units
gr<a>waitTSem</a> can acquire.
gr
grThe initial counter value can be negative which denotes a resource
gr"debt" that requires a respective amount of <a>signalTSem</a>
groperations to counter-balance.
newTSem :: Int -> STM TSem

-- | Wait on <a>TSem</a> (aka <b>P</b> operation).
gr
grThis operation acquires a unit from the semaphore (i.e. decreases the
grinternal counter) and blocks (via <a>retry</a>) if no units are
gravailable (i.e. if the counter is <i>not</i> positive).
waitTSem :: TSem -> STM ()

-- | Signal a <a>TSem</a> (aka <b>V</b> operation).
gr
grThis operation adds/releases a unit back to the semaphore (i.e.
grincrements the internal counter).
signalTSem :: TSem -> STM ()

-- | Multi-signal a <a>TSem</a>
gr
grThis operation adds/releases multiple units back to the semaphore
gr(i.e. increments the internal counter).
gr
gr<pre>
grsignalTSem == signalTSemN 1
gr</pre>
signalTSemN :: Word -> TSem -> STM ()
instance GHC.Classes.Eq Control.Concurrent.STM.TSem.TSem
