add install-includes: field
[packages/pretty.git] / Control / Concurrent / SampleVar.hs
1 -----------------------------------------------------------------------------
2 -- |
3 -- Module : Control.Concurrent.SampleVar
4 -- Copyright : (c) The University of Glasgow 2001
5 -- License : BSD-style (see the file libraries/base/LICENSE)
6 --
7 -- Maintainer : libraries@haskell.org
8 -- Stability : experimental
9 -- Portability : non-portable (concurrency)
10 --
11 -- Sample variables
12 --
13 -----------------------------------------------------------------------------
14
15 module Control.Concurrent.SampleVar
16 (
17 -- * Sample Variables
18 SampleVar, -- :: type _ =
19
20 newEmptySampleVar, -- :: IO (SampleVar a)
21 newSampleVar, -- :: a -> IO (SampleVar a)
22 emptySampleVar, -- :: SampleVar a -> IO ()
23 readSampleVar, -- :: SampleVar a -> IO a
24 writeSampleVar, -- :: SampleVar a -> a -> IO ()
25 isEmptySampleVar, -- :: SampleVar a -> IO Bool
26
27 ) where
28
29 import Prelude
30
31 import Control.Concurrent.MVar
32
33 -- |
34 -- Sample variables are slightly different from a normal 'MVar':
35 --
36 -- * Reading an empty 'SampleVar' causes the reader to block.
37 -- (same as 'takeMVar' on empty 'MVar')
38 --
39 -- * Reading a filled 'SampleVar' empties it and returns value.
40 -- (same as 'takeMVar')
41 --
42 -- * Writing to an empty 'SampleVar' fills it with a value, and
43 -- potentially, wakes up a blocked reader (same as for 'putMVar' on
44 -- empty 'MVar').
45 --
46 -- * Writing to a filled 'SampleVar' overwrites the current value.
47 -- (different from 'putMVar' on full 'MVar'.)
48
49 type SampleVar a
50 = MVar (Int, -- 1 == full
51 -- 0 == empty
52 -- <0 no of readers blocked
53 MVar a)
54
55 -- |Build a new, empty, 'SampleVar'
56 newEmptySampleVar :: IO (SampleVar a)
57 newEmptySampleVar = do
58 v <- newEmptyMVar
59 newMVar (0,v)
60
61 -- |Build a 'SampleVar' with an initial value.
62 newSampleVar :: a -> IO (SampleVar a)
63 newSampleVar a = do
64 v <- newEmptyMVar
65 putMVar v a
66 newMVar (1,v)
67
68 -- |If the SampleVar is full, leave it empty. Otherwise, do nothing.
69 emptySampleVar :: SampleVar a -> IO ()
70 emptySampleVar v = do
71 (readers, var) <- takeMVar v
72 if readers > 0 then do
73 takeMVar var
74 putMVar v (0,var)
75 else
76 putMVar v (readers,var)
77
78 -- |Wait for a value to become available, then take it and return.
79 readSampleVar :: SampleVar a -> IO a
80 readSampleVar svar = do
81 --
82 -- filled => make empty and grab sample
83 -- not filled => try to grab value, empty when read val.
84 --
85 (readers,val) <- takeMVar svar
86 putMVar svar (readers-1,val)
87 takeMVar val
88
89 -- |Write a value into the 'SampleVar', overwriting any previous value that
90 -- was there.
91 writeSampleVar :: SampleVar a -> a -> IO ()
92 writeSampleVar svar v = do
93 --
94 -- filled => overwrite
95 -- not filled => fill, write val
96 --
97 (readers,val) <- takeMVar svar
98 case readers of
99 1 ->
100 swapMVar val v >>
101 putMVar svar (1,val)
102 _ ->
103 putMVar val v >>
104 putMVar svar (min 1 (readers+1), val)
105
106 -- | Returns 'True' if the 'SampleVar' is currently empty.
107 --
108 -- Note that this function is only useful if you know that no other
109 -- threads can be modifying the state of the 'SampleVar', because
110 -- otherwise the state of the 'SampleVar' may have changed by the time
111 -- you see the result of 'isEmptySampleVar'.
112 --
113 isEmptySampleVar :: SampleVar a -> IO Bool
114 isEmptySampleVar svar = do
115 (readers,val) <- readMVar svar
116 return (readers == 0)
117