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