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


-- | Software Transactional Memory
°5u
°5uSoftware Transactional Memory, or STM, is an abstraction for
°5uconcurrent communication. The main benefits of STM are
°5u<i>composability</i> and <i>modularity</i>. That is, using STM you can
°5uwrite concurrent abstractions that can be easily composed with any
°5uother abstraction built using STM, without exposing the details of how
°5uyour abstraction ensures safety. This is typically not the case with
°5uother forms of concurrent communication, such as locks or
°5u<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
°5ua maximum capacity set when it is created. If the queue already
°5ucontains the maximum number of elements, then <a>writeTBQueue</a>
°5ublocks until an element is removed from the queue.
°5u
°5uThe implementation is based on the traditional purely-functional queue
°5urepresentation that uses two lists to obtain amortised <i>O(1)</i>
°5uenqueue and dequeue operations.
module Control.Concurrent.STM.TBQueue

-- | <a>TBQueue</a> is an abstract type representing a bounded FIFO
°5uchannel.
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
°5utop-level <a>TBQueue</a>s using <a>unsafePerformIO</a>, because using
°5u<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
°5ureturns <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.
°5uThis function never retries.
flushTBQueue :: TBQueue a -> STM [a]

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

-- | A version of <a>peekTBQueue</a> which does not retry. Instead it
°5ureturns <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
°5uread. 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
°5uchannel.
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
°5utop-level <a>TChan</a>s using <a>unsafePerformIO</a>, because using
°5u<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>
°5uwill <a>retry</a> even after items have been written to the channel.
°5uThe only way to read a broadcast channel is to duplicate it with
°5u<a>dupTChan</a>.
°5u
°5uConsider a server that broadcasts messages to clients:
°5u
°5u<pre>
°5userve :: TChan Message -&gt; Client -&gt; IO loop
°5userve broadcastChan client = do
°5u    myChan &lt;- dupTChan broadcastChan
°5u    forever $ do
°5u        message &lt;- readTChan myChan
°5u        send client message
°5u</pre>
°5u
°5uThe problem with using <a>newTChan</a> to create the broadcast channel
°5uis that if it is only written to and never read, items will pile up in
°5umemory. By using <a>newBroadcastTChan</a> to create the broadcast
°5uchannel, 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
°5uwritten to either channel from then on will be available from both.
°5uHence this creates a kind of broadcast channel, where data written by
°5uanyone is seen by everyone else.
dupTChan :: TChan a -> STM (TChan a)

-- | Clone a <a>TChan</a>: similar to dupTChan, but the cloned channel
°5ustarts 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
°5u<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,
°5uretrying if the channel is empty.
peekTChan :: TChan a -> STM a

-- | A version of <a>peekTChan</a> which does not retry. Instead it returns
°5u<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
°5uread.
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
°5ubetween concurrent threads. It can be thought of as a box, which may
°5ube 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
°5utop-level <a>TMVar</a>s using <a>unsafePerformIO</a>, because using
°5u<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
°5ucreating top-level <a>TMVar</a>s using <a>unsafePerformIO</a>, because
°5uusing <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
°5ucurrently empty, the transaction will <a>retry</a>. After a
°5u<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
°5ufull, <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
°5utakes the value from the <a>TMVar</a>, puts it back, and also returns
°5uit.
readTMVar :: TMVar a -> STM a

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

-- | <a>TQueue</a> is an abstract type representing an unbounded FIFO
°5uchannel.
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
°5utop-level <a>TQueue</a>s using <a>unsafePerformIO</a>, because using
°5u<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
°5ureturns <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.
°5uThis function never retries.
flushTQueue :: TQueue a -> STM [a]

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

-- | A version of <a>peekTQueue</a> which does not retry. Instead it
°5ureturns <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
°5uread.
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
°5utop-level <a>TVar</a>s using <a>unsafePerformIO</a>, because using
°5u<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
°5uto
°5u
°5u<pre>
°5ureadTVarIO = atomically . readTVar
°5u</pre>
°5u
°5ubut works much faster, because it doesn't perform a complete
°5utransaction, 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
°5unon-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
°5umicroseconds. 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
°5uas 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>
°5uinterface for mutable arrays.
°5u
°5uIt is currently implemented as <tt>Array ix (TVar e)</tt>, but it may
°5ube replaced by a more efficient implementation in the future (the
°5uinterface 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
°5uabstraction. See
°5u
°5u<ul>
°5u<li><i>Composable memory transactions</i>, by Tim Harris, Simon
°5uMarlow, Simon Peyton Jones, and Maurice Herlihy, in <i>ACM Conference
°5uon Principles and Practice of Parallel Programming</i> 2005.
°5u<a>https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/</a></li>
°5u</ul>
°5u
°5uThis module only defines the <a>STM</a> monad; you probably want to
°5uimport <a>Control.Concurrent.STM</a> (which exports
°5u<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.
°5u
°5uUsing <a>atomically</a> inside an <a>unsafePerformIO</a> or
°5u<a>unsafeInterleaveIO</a> subverts some of guarantees that STM
°5uprovides. It makes it possible to run a transaction inside of another
°5utransaction, depending on when the thunk is evaluated. If a nested
°5utransaction is attempted, an exception is thrown by the runtime. It is
°5upossible to safely use <a>atomically</a> inside <a>unsafePerformIO</a>
°5uor <a>unsafeInterleaveIO</a>, but the typechecker does not rule out
°5uprograms that may attempt nested transactions, meaning that the
°5uprogrammer must take special care to prevent these.
°5u
°5uHowever, there are functions for creating transactional variables that
°5ucan always be safely called in <a>unsafePerformIO</a>. See:
°5u<a>newTVarIO</a>, <tt>newTChanIO</tt>, <tt>newBroadcastTChanIO</tt>,
°5u<tt>newTQueueIO</tt>, <tt>newTBQueueIO</tt>, and <tt>newTMVarIO</tt>.
°5u
°5uUsing <a>unsafePerformIO</a> inside of <a>atomically</a> is also
°5udangerous but for different reasons. See <a>unsafeIOToSTM</a> for more
°5uon this.
atomically :: () => STM a -> IO a

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

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

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

-- | Compose two alternative STM actions (GHC only).
°5u
°5uIf the first action completes without retrying then it forms the
°5uresult of the <a>orElse</a>. Otherwise, if the first action retries,
°5uthen the second action is tried in its place. If both actions retry
°5uthen 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>.
°5u
°5uIn 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>
°5umonad.
°5u
°5uThrowing an exception in <tt>STM</tt> aborts the transaction and
°5upropagates the exception.
°5u
°5uAlthough <a>throwSTM</a> has a type that is an instance of the type of
°5u<a>throw</a>, the two functions are subtly different:
°5u
°5u<pre>
°5uthrow e    `seq` x  ===&gt; throw e
°5uthrowSTM e `seq` x  ===&gt; x
°5u</pre>
°5u
°5uThe first example will cause the exception <tt>e</tt> to be raised,
°5uwhereas the second one won't. In fact, <a>throwSTM</a> will only cause
°5uan exception to be raised when it is used within the <a>STM</a> monad.
°5uThe <a>throwSTM</a> variant should be used in preference to
°5u<a>throw</a> to raise an exception within the <a>STM</a> monad because
°5uit guarantees ordering with respect to other <a>STM</a> operations,
°5uwhereas <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
°5uabstraction. See
°5u
°5u<ul>
°5u<li><i>Composable memory transactions</i>, by Tim Harris, Simon
°5uMarlow, Simon Peyton Jones, and Maurice Herlihy, in <i>ACM Conference
°5uon Principles and Practice of Parallel Programming</i> 2005.
°5u<a>https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/</a></li>
°5u</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
°5uunits, and units may be acquired or released by <a>waitTSem</a> and
°5u<a>signalTSem</a> respectively. When the <a>TSem</a> is empty,
°5u<a>waitTSem</a> blocks.
°5u
°5uNote that <a>TSem</a> has no concept of fairness, and there is no
°5uguarantee that threads blocked in <a>waitTSem</a> will be unblocked in
°5uthe same order; in fact they will all be unblocked at the same time
°5uand will fight over the <a>TSem</a>. Hence <a>TSem</a> is not suitable
°5uif you expect there to be a high number of threads contending for the
°5uresource. However, like other STM abstractions, <a>TSem</a> is
°5ucomposable.
data TSem

-- | Construct new <a>TSem</a> with an initial counter value.
°5u
°5uA positive initial counter value denotes availability of units
°5u<a>waitTSem</a> can acquire.
°5u
°5uThe initial counter value can be negative which denotes a resource
°5u"debt" that requires a respective amount of <a>signalTSem</a>
°5uoperations to counter-balance.
newTSem :: Int -> STM TSem

-- | Wait on <a>TSem</a> (aka <b>P</b> operation).
°5u
°5uThis operation acquires a unit from the semaphore (i.e. decreases the
°5uinternal counter) and blocks (via <a>retry</a>) if no units are
°5uavailable (i.e. if the counter is <i>not</i> positive).
waitTSem :: TSem -> STM ()

-- | Signal a <a>TSem</a> (aka <b>V</b> operation).
°5u
°5uThis operation adds/releases a unit back to the semaphore (i.e.
°5uincrements the internal counter).
signalTSem :: TSem -> STM ()

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