/usr/share/doc/libghc-stm-doc/html/src/Control-Monad-STM.html is in libghc-stm-doc 2.4.4.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<!-- Generated by HsColour, http://code.haskell.org/~malcolm/hscolour/ -->
<title>Control/Monad/STM.hs</title>
<link type='text/css' rel='stylesheet' href='hscolour.css' />
</head>
<body>
<pre><a name="line-1"></a><span class='hs-comment'>{-# OPTIONS_GHC -fno-warn-orphans #-}</span>
<a name="line-2"></a><span class='hs-comment'>{-# LANGUAGE CPP, MagicHash, UnboxedTuples #-}</span>
<a name="line-3"></a>
<a name="line-4"></a><span class='hs-cpp'>#if __GLASGOW_HASKELL__ >= 701</span>
<a name="line-5"></a><span class='hs-comment'>{-# LANGUAGE Trustworthy #-}</span>
<a name="line-6"></a><span class='hs-cpp'>#endif</span>
<a name="line-7"></a>
<a name="line-8"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span>
<a name="line-9"></a><span class='hs-comment'>-- |</span>
<a name="line-10"></a><span class='hs-comment'>-- Module : Control.Monad.STM</span>
<a name="line-11"></a><span class='hs-comment'>-- Copyright : (c) The University of Glasgow 2004</span>
<a name="line-12"></a><span class='hs-comment'>-- License : BSD-style (see the file libraries/base/LICENSE)</span>
<a name="line-13"></a><span class='hs-comment'>--</span>
<a name="line-14"></a><span class='hs-comment'>-- Maintainer : libraries@haskell.org</span>
<a name="line-15"></a><span class='hs-comment'>-- Stability : experimental</span>
<a name="line-16"></a><span class='hs-comment'>-- Portability : non-portable (requires STM)</span>
<a name="line-17"></a><span class='hs-comment'>--</span>
<a name="line-18"></a><span class='hs-comment'>-- Software Transactional Memory: a modular composable concurrency</span>
<a name="line-19"></a><span class='hs-comment'>-- abstraction. See</span>
<a name="line-20"></a><span class='hs-comment'>--</span>
<a name="line-21"></a><span class='hs-comment'>-- * /Composable memory transactions/, by Tim Harris, Simon Marlow, Simon</span>
<a name="line-22"></a><span class='hs-comment'>-- Peyton Jones, and Maurice Herlihy, in /ACM Conference on Principles</span>
<a name="line-23"></a><span class='hs-comment'>-- and Practice of Parallel Programming/ 2005.</span>
<a name="line-24"></a><span class='hs-comment'>-- <<a href="http://research.microsoft.com/Users/simonpj/papers/stm/index.htm">http://research.microsoft.com/Users/simonpj/papers/stm/index.htm</a>></span>
<a name="line-25"></a><span class='hs-comment'>--</span>
<a name="line-26"></a><span class='hs-comment'>-- This module only defines the 'STM' monad; you probably want to</span>
<a name="line-27"></a><span class='hs-comment'>-- import "Control.Concurrent.STM" (which exports "Control.Monad.STM").</span>
<a name="line-28"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span>
<a name="line-29"></a>
<a name="line-30"></a><span class='hs-keyword'>module</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Monad</span><span class='hs-varop'>.</span><span class='hs-conid'>STM</span> <span class='hs-layout'>(</span>
<a name="line-31"></a> <span class='hs-conid'>STM</span><span class='hs-layout'>,</span>
<a name="line-32"></a> <span class='hs-varid'>atomically</span><span class='hs-layout'>,</span>
<a name="line-33"></a><span class='hs-cpp'>#ifdef __GLASGOW_HASKELL__</span>
<a name="line-34"></a> <span class='hs-varid'>always</span><span class='hs-layout'>,</span>
<a name="line-35"></a> <span class='hs-varid'>alwaysSucceeds</span><span class='hs-layout'>,</span>
<a name="line-36"></a> <span class='hs-varid'>retry</span><span class='hs-layout'>,</span>
<a name="line-37"></a> <span class='hs-varid'>orElse</span><span class='hs-layout'>,</span>
<a name="line-38"></a> <span class='hs-varid'>check</span><span class='hs-layout'>,</span>
<a name="line-39"></a><span class='hs-cpp'>#endif</span>
<a name="line-40"></a> <span class='hs-varid'>throwSTM</span><span class='hs-layout'>,</span>
<a name="line-41"></a> <span class='hs-varid'>catchSTM</span>
<a name="line-42"></a> <span class='hs-layout'>)</span> <span class='hs-keyword'>where</span>
<a name="line-43"></a>
<a name="line-44"></a><span class='hs-cpp'>#ifdef __GLASGOW_HASKELL__</span>
<a name="line-45"></a><span class='hs-cpp'>#if ! (MIN_VERSION_base(4,3,0))</span>
<a name="line-46"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>GHC</span><span class='hs-varop'>.</span><span class='hs-conid'>Conc</span> <span class='hs-varid'>hiding</span> <span class='hs-layout'>(</span><span class='hs-varid'>catchSTM</span><span class='hs-layout'>)</span>
<a name="line-47"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Monad</span> <span class='hs-layout'>(</span> <span class='hs-conid'>MonadPlus</span><span class='hs-layout'>(</span><span class='hs-keyglyph'>..</span><span class='hs-layout'>)</span> <span class='hs-layout'>)</span>
<a name="line-48"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Exception</span>
<a name="line-49"></a><span class='hs-cpp'>#else</span>
<a name="line-50"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>GHC</span><span class='hs-varop'>.</span><span class='hs-conid'>Conc</span>
<a name="line-51"></a><span class='hs-cpp'>#endif</span>
<a name="line-52"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>GHC</span><span class='hs-varop'>.</span><span class='hs-conid'>Exts</span>
<a name="line-53"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Monad</span><span class='hs-varop'>.</span><span class='hs-conid'>Fix</span>
<a name="line-54"></a><span class='hs-cpp'>#else</span>
<a name="line-55"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Sequential</span><span class='hs-varop'>.</span><span class='hs-conid'>STM</span>
<a name="line-56"></a><span class='hs-cpp'>#endif</span>
<a name="line-57"></a>
<a name="line-58"></a><span class='hs-cpp'>#ifdef __GLASGOW_HASKELL__</span>
<a name="line-59"></a><span class='hs-cpp'>#if ! (MIN_VERSION_base(4,3,0))</span>
<a name="line-60"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Applicative</span>
<a name="line-61"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Monad</span> <span class='hs-layout'>(</span><span class='hs-varid'>ap</span><span class='hs-layout'>)</span>
<a name="line-62"></a><span class='hs-cpp'>#endif</span>
<a name="line-63"></a><span class='hs-cpp'>#endif</span>
<a name="line-64"></a>
<a name="line-65"></a>
<a name="line-66"></a><span class='hs-cpp'>#ifdef __GLASGOW_HASKELL__</span>
<a name="line-67"></a><span class='hs-cpp'>#if ! (MIN_VERSION_base(4,3,0))</span>
<a name="line-68"></a><a name="instance%20MonadPlus%20STM"></a><span class='hs-keyword'>instance</span> <span class='hs-conid'>MonadPlus</span> <span class='hs-conid'>STM</span> <span class='hs-keyword'>where</span>
<a name="line-69"></a> <span class='hs-varid'>mzero</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>retry</span>
<a name="line-70"></a> <span class='hs-varid'>mplus</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>orElse</span>
<a name="line-71"></a>
<a name="line-72"></a><a name="instance%20Applicative%20STM"></a><span class='hs-keyword'>instance</span> <span class='hs-conid'>Applicative</span> <span class='hs-conid'>STM</span> <span class='hs-keyword'>where</span>
<a name="line-73"></a> <span class='hs-varid'>pure</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>return</span>
<a name="line-74"></a> <span class='hs-layout'>(</span><span class='hs-varop'><*></span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>ap</span>
<a name="line-75"></a>
<a name="line-76"></a><a name="instance%20Alternative%20STM"></a><span class='hs-keyword'>instance</span> <span class='hs-conid'>Alternative</span> <span class='hs-conid'>STM</span> <span class='hs-keyword'>where</span>
<a name="line-77"></a> <span class='hs-varid'>empty</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>retry</span>
<a name="line-78"></a> <span class='hs-layout'>(</span><span class='hs-varop'><|></span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>orElse</span>
<a name="line-79"></a><span class='hs-cpp'>#endif</span>
<a name="line-80"></a>
<a name="line-81"></a><a name="check"></a><span class='hs-definition'>check</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Bool</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>STM</span> <span class='hs-conid'>()</span>
<a name="line-82"></a><span class='hs-definition'>check</span> <span class='hs-varid'>b</span> <span class='hs-keyglyph'>=</span> <span class='hs-keyword'>if</span> <span class='hs-varid'>b</span> <span class='hs-keyword'>then</span> <span class='hs-varid'>return</span> <span class='hs-conid'>()</span> <span class='hs-keyword'>else</span> <span class='hs-varid'>retry</span>
<a name="line-83"></a><span class='hs-cpp'>#endif</span>
<a name="line-84"></a>
<a name="line-85"></a><span class='hs-cpp'>#if ! (MIN_VERSION_base(4,3,0))</span>
<a name="line-86"></a><a name="catchSTM"></a><span class='hs-comment'>-- |Exception handling within STM actions.</span>
<a name="line-87"></a><span class='hs-definition'>catchSTM</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Exception</span> <span class='hs-varid'>e</span> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>STM</span> <span class='hs-varid'>a</span> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-varid'>e</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>STM</span> <span class='hs-varid'>a</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>STM</span> <span class='hs-varid'>a</span>
<a name="line-88"></a><span class='hs-definition'>catchSTM</span> <span class='hs-layout'>(</span><span class='hs-conid'>STM</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span> <span class='hs-varid'>handler</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>STM</span> <span class='hs-varop'>$</span> <span class='hs-varid'>catchSTM</span><span class='hs-cpp'>#</span> <span class='hs-varid'>m</span> <span class='hs-varid'>handler'</span>
<a name="line-89"></a> <span class='hs-keyword'>where</span>
<a name="line-90"></a> <span class='hs-varid'>handler'</span> <span class='hs-varid'>e</span> <span class='hs-keyglyph'>=</span> <span class='hs-keyword'>case</span> <span class='hs-varid'>fromException</span> <span class='hs-varid'>e</span> <span class='hs-keyword'>of</span>
<a name="line-91"></a> <span class='hs-conid'>Just</span> <span class='hs-varid'>e'</span> <span class='hs-keyglyph'>-></span> <span class='hs-keyword'>case</span> <span class='hs-varid'>handler</span> <span class='hs-varid'>e'</span> <span class='hs-keyword'>of</span> <span class='hs-conid'>STM</span> <span class='hs-varid'>m'</span> <span class='hs-keyglyph'>-></span> <span class='hs-varid'>m'</span>
<a name="line-92"></a> <span class='hs-conid'>Nothing</span> <span class='hs-keyglyph'>-></span> <span class='hs-varid'>raiseIO</span><span class='hs-cpp'>#</span> <span class='hs-varid'>e</span>
<a name="line-93"></a>
<a name="line-94"></a><a name="throwSTM"></a><span class='hs-comment'>-- | A variant of 'throw' that can only be used within the 'STM' monad.</span>
<a name="line-95"></a><span class='hs-comment'>--</span>
<a name="line-96"></a><span class='hs-comment'>-- Throwing an exception in @STM@ aborts the transaction and propagates the</span>
<a name="line-97"></a><span class='hs-comment'>-- exception.</span>
<a name="line-98"></a><span class='hs-comment'>--</span>
<a name="line-99"></a><span class='hs-comment'>-- Although 'throwSTM' has a type that is an instance of the type of 'throw', the</span>
<a name="line-100"></a><span class='hs-comment'>-- two functions are subtly different:</span>
<a name="line-101"></a><span class='hs-comment'>--</span>
<a name="line-102"></a><span class='hs-comment'>-- > throw e `seq` x ===> throw e</span>
<a name="line-103"></a><span class='hs-comment'>-- > throwSTM e `seq` x ===> x</span>
<a name="line-104"></a><span class='hs-comment'>--</span>
<a name="line-105"></a><span class='hs-comment'>-- The first example will cause the exception @e@ to be raised,</span>
<a name="line-106"></a><span class='hs-comment'>-- whereas the second one won\'t. In fact, 'throwSTM' will only cause</span>
<a name="line-107"></a><span class='hs-comment'>-- an exception to be raised when it is used within the 'STM' monad.</span>
<a name="line-108"></a><span class='hs-comment'>-- The 'throwSTM' variant should be used in preference to 'throw' to</span>
<a name="line-109"></a><span class='hs-comment'>-- raise an exception within the 'STM' monad because it guarantees</span>
<a name="line-110"></a><span class='hs-comment'>-- ordering with respect to other 'STM' operations, whereas 'throw'</span>
<a name="line-111"></a><span class='hs-comment'>-- does not.</span>
<a name="line-112"></a><span class='hs-definition'>throwSTM</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Exception</span> <span class='hs-varid'>e</span> <span class='hs-keyglyph'>=></span> <span class='hs-varid'>e</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>STM</span> <span class='hs-varid'>a</span>
<a name="line-113"></a><span class='hs-definition'>throwSTM</span> <span class='hs-varid'>e</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>STM</span> <span class='hs-varop'>$</span> <span class='hs-varid'>raiseIO</span><span class='hs-cpp'>#</span> <span class='hs-layout'>(</span><span class='hs-varid'>toException</span> <span class='hs-varid'>e</span><span class='hs-layout'>)</span>
<a name="line-114"></a><span class='hs-cpp'>#endif</span>
<a name="line-115"></a>
<a name="line-116"></a>
<a name="line-117"></a><a name="STMret"></a><span class='hs-keyword'>data</span> <span class='hs-conid'>STMret</span> <span class='hs-varid'>a</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>STMret</span> <span class='hs-layout'>(</span><span class='hs-conid'>State</span><span class='hs-cpp'>#</span> <span class='hs-conid'>RealWorld</span><span class='hs-layout'>)</span> <span class='hs-varid'>a</span>
<a name="line-118"></a>
<a name="line-119"></a><a name="liftSTM"></a><span class='hs-definition'>liftSTM</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>STM</span> <span class='hs-varid'>a</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>State</span><span class='hs-cpp'>#</span> <span class='hs-conid'>RealWorld</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>STMret</span> <span class='hs-varid'>a</span>
<a name="line-120"></a><span class='hs-definition'>liftSTM</span> <span class='hs-layout'>(</span><span class='hs-conid'>STM</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>=</span> <span class='hs-keyglyph'>\</span><span class='hs-varid'>s</span> <span class='hs-keyglyph'>-></span> <span class='hs-keyword'>case</span> <span class='hs-varid'>m</span> <span class='hs-varid'>s</span> <span class='hs-keyword'>of</span> <span class='hs-layout'>(</span><span class='hs-cpp'>#</span> <span class='hs-varid'>s'</span><span class='hs-layout'>,</span> <span class='hs-varid'>r</span> <span class='hs-cpp'>#</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>STMret</span> <span class='hs-varid'>s'</span> <span class='hs-varid'>r</span>
<a name="line-121"></a>
<a name="line-122"></a><a name="instance%20MonadFix%20STM"></a><span class='hs-keyword'>instance</span> <span class='hs-conid'>MonadFix</span> <span class='hs-conid'>STM</span> <span class='hs-keyword'>where</span>
<a name="line-123"></a> <span class='hs-varid'>mfix</span> <span class='hs-varid'>k</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>STM</span> <span class='hs-varop'>$</span> <span class='hs-keyglyph'>\</span><span class='hs-varid'>s</span> <span class='hs-keyglyph'>-></span>
<a name="line-124"></a> <span class='hs-keyword'>let</span> <span class='hs-varid'>ans</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>liftSTM</span> <span class='hs-layout'>(</span><span class='hs-varid'>k</span> <span class='hs-varid'>r</span><span class='hs-layout'>)</span> <span class='hs-varid'>s</span>
<a name="line-125"></a> <span class='hs-conid'>STMret</span> <span class='hs-keyword'>_</span> <span class='hs-varid'>r</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>ans</span>
<a name="line-126"></a> <span class='hs-keyword'>in</span> <span class='hs-keyword'>case</span> <span class='hs-varid'>ans</span> <span class='hs-keyword'>of</span> <span class='hs-conid'>STMret</span> <span class='hs-varid'>s'</span> <span class='hs-varid'>x</span> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-cpp'>#</span> <span class='hs-varid'>s'</span><span class='hs-layout'>,</span> <span class='hs-varid'>x</span> <span class='hs-cpp'>#</span><span class='hs-layout'>)</span>
</pre></body>
</html>
|