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