<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Control.Monad.STM</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Control-Monad-STM.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Control-Monad-STM.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">stm-2.2.0.1: Software Transactional Memory</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>non-portable (requires STM)</td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Maintainer</th><td>libraries@haskell.org</td></tr></table><p class="caption">Control.Monad.STM</p></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Software Transactional Memory: a modular composable concurrency
abstraction. See
</p><ul><li> <em>Composable memory transactions</em>, by Tim Harris, Simon Marlow, Simon
Peyton Jones, and Maurice Herlihy, in /ACM Conference on Principles
and Practice of Parallel Programming/ 2005.
<a href="http://research.microsoft.com/Users/simonpj/papers/stm/index.htm">http://research.microsoft.com/Users/simonpj/papers/stm/index.htm</a>
</li></ul><p>This module only defines the <code><a href="Control-Monad-STM.html#t:STM">STM</a></code> monad; you probably want to
import <a href="Control-Concurrent-STM.html">Control.Concurrent.STM</a> (which exports <a href="Control-Monad-STM.html">Control.Monad.STM</a>).
</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><span class="keyword">data</span> <a href="#t:STM">STM</a> a</li><li class="src short"><a href="#v:atomically">atomically</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:always">always</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Bool.html#t:Bool">Bool</a> -> <a href="Control-Monad-STM.html#t:STM">STM</a> ()</li><li class="src short"><a href="#v:alwaysSucceeds">alwaysSucceeds</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="Control-Monad-STM.html#t:STM">STM</a> ()</li><li class="src short"><a href="#v:retry">retry</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a</li><li class="src short"><a href="#v:orElse">orElse</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="Control-Monad-STM.html#t:STM">STM</a> a</li><li class="src short"><a href="#v:check">check</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Bool.html#t:Bool">Bool</a> -> <a href="Control-Monad-STM.html#t:STM">STM</a> a</li><li class="src short"><a href="#v:throwSTM">throwSTM</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#t:Exception">Exception</a> e => e -> <a href="Control-Monad-STM.html#t:STM">STM</a> a</li><li class="src short"><a href="#v:catchSTM">catchSTM</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#t:Exception">Exception</a> e => <a href="Control-Monad-STM.html#t:STM">STM</a> a -> (e -> <a href="Control-Monad-STM.html#t:STM">STM</a> a) -> <a href="Control-Monad-STM.html#t:STM">STM</a> a</li></ul></div><div id="interface"><h1>Documentation</h1><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:STM" class="def">STM</a> a </p><div class="doc"><p>A monad supporting atomic memory transactions.
</p></div><div class="subs instances"><p id="control.i:STM" class="caption collapser" onclick="toggleSection('i:STM')">Instances</p><div id="section.i:STM" class="show"><table><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> <a href="Control-Monad-STM.html#t:STM">STM</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Functor">Functor</a> <a href="Control-Monad-STM.html#t:STM">STM</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Typeable.html#t:Typeable1">Typeable1</a> <a href="Control-Monad-STM.html#t:STM">STM</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:MonadPlus">MonadPlus</a> <a href="Control-Monad-STM.html#t:STM">STM</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Applicative.html#t:Applicative">Applicative</a> <a href="Control-Monad-STM.html#t:STM">STM</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Applicative.html#t:Alternative">Alternative</a> <a href="Control-Monad-STM.html#t:STM">STM</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/array-0.3.0.2/Data-Array-MArray.html#t:MArray">MArray</a> <a href="Control-Concurrent-STM-TArray.html#t:TArray">TArray</a> e <a href="Control-Monad-STM.html#t:STM">STM</a></td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><a name="v:atomically" class="def">atomically</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/System-IO.html#t:IO">IO</a> a</p><div class="doc"><p>Perform a series of STM actions atomically.
</p><p>You cannot use <code><a href="Control-Monad-STM.html#v:atomically">atomically</a></code> inside an <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/System-IO-Unsafe.html#v:unsafePerformIO">unsafePerformIO</a></code> or <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/System-IO-Unsafe.html#v:unsafeInterleaveIO">unsafeInterleaveIO</a></code>.
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.)
</p><p>However, see <code><a href="Control-Concurrent-STM-TVar.html#v:newTVarIO">newTVarIO</a></code>, which can be called inside <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/System-IO-Unsafe.html#v:unsafePerformIO">unsafePerformIO</a></code>,
and which allows top-level TVars to be allocated.
</p></div></div><div class="top"><p class="src"><a name="v:always" class="def">always</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Bool.html#t:Bool">Bool</a> -> <a href="Control-Monad-STM.html#t:STM">STM</a> ()</p><div class="doc"><p>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.
</p></div></div><div class="top"><p class="src"><a name="v:alwaysSucceeds" class="def">alwaysSucceeds</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="Control-Monad-STM.html#t:STM">STM</a> ()</p><div class="doc"><p>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.
</p></div></div><div class="top"><p class="src"><a name="v:retry" class="def">retry</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a</p><div class="doc"><p>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)
</p></div></div><div class="top"><p class="src"><a name="v:orElse" class="def">orElse</a> :: <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="Control-Monad-STM.html#t:STM">STM</a> a -> <a href="Control-Monad-STM.html#t:STM">STM</a> a</p><div class="doc"><p>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.
</p></div></div><div class="top"><p class="src"><a name="v:check" class="def">check</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Bool.html#t:Bool">Bool</a> -> <a href="Control-Monad-STM.html#t:STM">STM</a> a<a href="src/Control-Monad-STM.html#check" class="link">Source</a></p></div><div class="top"><p class="src"><a name="v:throwSTM" class="def">throwSTM</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#t:Exception">Exception</a> e => e -> <a href="Control-Monad-STM.html#t:STM">STM</a> a</p><div class="doc"><p>A variant of <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#v:throw">throw</a></code> that can only be used within the <code><a href="Control-Monad-STM.html#t:STM">STM</a></code> monad.
</p><p>Throwing an exception in <code>STM</code> aborts the transaction and propagates the
exception.
</p><p>Although <code><a href="Control-Monad-STM.html#v:throwSTM">throwSTM</a></code> has a type that is an instance of the type of <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#v:throw">throw</a></code>, the
two functions are subtly different:
</p><pre> throw e `seq` x ===> throw e
throwSTM e `seq` x ===> x
</pre><p>The first example will cause the exception <code>e</code> to be raised,
whereas the second one won't. In fact, <code><a href="Control-Monad-STM.html#v:throwSTM">throwSTM</a></code> will only cause
an exception to be raised when it is used within the <code><a href="Control-Monad-STM.html#t:STM">STM</a></code> monad.
The <code><a href="Control-Monad-STM.html#v:throwSTM">throwSTM</a></code> variant should be used in preference to <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#v:throw">throw</a></code> to
raise an exception within the <code><a href="Control-Monad-STM.html#t:STM">STM</a></code> monad because it guarantees
ordering with respect to other <code><a href="Control-Monad-STM.html#t:STM">STM</a></code> operations, whereas <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#v:throw">throw</a></code>
does not.
</p></div></div><div class="top"><p class="src"><a name="v:catchSTM" class="def">catchSTM</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#t:Exception">Exception</a> e => <a href="Control-Monad-STM.html#t:STM">STM</a> a -> (e -> <a href="Control-Monad-STM.html#t:STM">STM</a> a) -> <a href="Control-Monad-STM.html#t:STM">STM</a> a</p><div class="doc"><p>Exception handling within STM actions.
</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.9.2</p></div></body></html>
