Remove references to () from types of mkWeak# and friends
[ghc.git] / libraries / base / GHC / MVar.hs
1 {-# LANGUAGE Unsafe #-}
2 {-# LANGUAGE NoImplicitPrelude, MagicHash, UnboxedTuples #-}
3 {-# OPTIONS_GHC -funbox-strict-fields #-}
4 {-# OPTIONS_HADDOCK hide #-}
5
6 -----------------------------------------------------------------------------
7 -- |
8 -- Module : GHC.MVar
9 -- Copyright : (c) The University of Glasgow 2008
10 -- License : see libraries/base/LICENSE
11 --
12 -- Maintainer : cvs-ghc@haskell.org
13 -- Stability : internal
14 -- Portability : non-portable (GHC Extensions)
15 --
16 -- The MVar type
17 --
18 -----------------------------------------------------------------------------
19
20 module GHC.MVar (
21 -- * MVars
22 MVar(..)
23 , newMVar
24 , newEmptyMVar
25 , takeMVar
26 , readMVar
27 , putMVar
28 , tryTakeMVar
29 , tryPutMVar
30 , tryReadMVar
31 , isEmptyMVar
32 , addMVarFinalizer
33 ) where
34
35 import GHC.Base
36
37 data MVar a = MVar (MVar# RealWorld a)
38 {- ^
39 An 'MVar' (pronounced \"em-var\") is a synchronising variable, used
40 for communication between concurrent threads. It can be thought of
41 as a a box, which may be empty or full.
42 -}
43
44 -- pull in Eq (Mvar a) too, to avoid GHC.Conc being an orphan-instance module
45 instance Eq (MVar a) where
46 (MVar mvar1#) == (MVar mvar2#) = isTrue# (sameMVar# mvar1# mvar2#)
47
48 {-
49 M-Vars are rendezvous points for concurrent threads. They begin
50 empty, and any attempt to read an empty M-Var blocks. When an M-Var
51 is written, a single blocked thread may be freed. Reading an M-Var
52 toggles its state from full back to empty. Therefore, any value
53 written to an M-Var may only be read once. Multiple reads and writes
54 are allowed, but there must be at least one read between any two
55 writes.
56 -}
57
58 --Defined in IOBase to avoid cycle: data MVar a = MVar (SynchVar# RealWorld a)
59
60 -- |Create an 'MVar' which is initially empty.
61 newEmptyMVar :: IO (MVar a)
62 newEmptyMVar = IO $ \ s# ->
63 case newMVar# s# of
64 (# s2#, svar# #) -> (# s2#, MVar svar# #)
65
66 -- |Create an 'MVar' which contains the supplied value.
67 newMVar :: a -> IO (MVar a)
68 newMVar value =
69 newEmptyMVar >>= \ mvar ->
70 putMVar mvar value >>
71 return mvar
72
73 -- |Return the contents of the 'MVar'. If the 'MVar' is currently
74 -- empty, 'takeMVar' will wait until it is full. After a 'takeMVar',
75 -- the 'MVar' is left empty.
76 --
77 -- There are two further important properties of 'takeMVar':
78 --
79 -- * 'takeMVar' is single-wakeup. That is, if there are multiple
80 -- threads blocked in 'takeMVar', and the 'MVar' becomes full,
81 -- only one thread will be woken up. The runtime guarantees that
82 -- the woken thread completes its 'takeMVar' operation.
83 --
84 -- * When multiple threads are blocked on an 'MVar', they are
85 -- woken up in FIFO order. This is useful for providing
86 -- fairness properties of abstractions built using 'MVar's.
87 --
88 takeMVar :: MVar a -> IO a
89 takeMVar (MVar mvar#) = IO $ \ s# -> takeMVar# mvar# s#
90
91 -- |Atomically read the contents of an 'MVar'. If the 'MVar' is
92 -- currently empty, 'readMVar' will wait until its full.
93 -- 'readMVar' is guaranteed to receive the next 'putMVar'.
94 --
95 -- 'readMVar' is multiple-wakeup, so when multiple readers are
96 -- blocked on an 'MVar', all of them are woken up at the same time.
97 --
98 -- /Compatibility note:/ Prior to base 4.7, 'readMVar' was a combination
99 -- of 'takeMVar' and 'putMVar'. This mean that in the presence of
100 -- other threads attempting to 'putMVar', 'readMVar' could block.
101 -- Furthermore, 'readMVar' would not receive the next 'putMVar' if there
102 -- was already a pending thread blocked on 'takeMVar'. The old behavior
103 -- can be recovered by implementing 'readMVar as follows:
104 --
105 -- @
106 -- readMVar :: MVar a -> IO a
107 -- readMVar m =
108 -- mask_ $ do
109 -- a <- takeMVar m
110 -- putMVar m a
111 -- return a
112 -- @
113 readMVar :: MVar a -> IO a
114 readMVar (MVar mvar#) = IO $ \ s# -> readMVar# mvar# s#
115
116 -- |Put a value into an 'MVar'. If the 'MVar' is currently full,
117 -- 'putMVar' will wait until it becomes empty.
118 --
119 -- There are two further important properties of 'putMVar':
120 --
121 -- * 'putMVar' is single-wakeup. That is, if there are multiple
122 -- threads blocked in 'putMVar', and the 'MVar' becomes empty,
123 -- only one thread will be woken up. The runtime guarantees that
124 -- the woken thread completes its 'putMVar' operation.
125 --
126 -- * When multiple threads are blocked on an 'MVar', they are
127 -- woken up in FIFO order. This is useful for providing
128 -- fairness properties of abstractions built using 'MVar's.
129 --
130 putMVar :: MVar a -> a -> IO ()
131 putMVar (MVar mvar#) x = IO $ \ s# ->
132 case putMVar# mvar# x s# of
133 s2# -> (# s2#, () #)
134
135 -- |A non-blocking version of 'takeMVar'. The 'tryTakeMVar' function
136 -- returns immediately, with 'Nothing' if the 'MVar' was empty, or
137 -- @'Just' a@ if the 'MVar' was full with contents @a@. After 'tryTakeMVar',
138 -- the 'MVar' is left empty.
139 tryTakeMVar :: MVar a -> IO (Maybe a)
140 tryTakeMVar (MVar m) = IO $ \ s ->
141 case tryTakeMVar# m s of
142 (# s', 0#, _ #) -> (# s', Nothing #) -- MVar is empty
143 (# s', _, a #) -> (# s', Just a #) -- MVar is full
144
145 -- |A non-blocking version of 'putMVar'. The 'tryPutMVar' function
146 -- attempts to put the value @a@ into the 'MVar', returning 'True' if
147 -- it was successful, or 'False' otherwise.
148 tryPutMVar :: MVar a -> a -> IO Bool
149 tryPutMVar (MVar mvar#) x = IO $ \ s# ->
150 case tryPutMVar# mvar# x s# of
151 (# s, 0# #) -> (# s, False #)
152 (# s, _ #) -> (# s, True #)
153
154 -- |A non-blocking version of 'readMVar'. The 'tryReadMVar' function
155 -- returns immediately, with 'Nothing' if the 'MVar' was empty, or
156 -- @'Just' a@ if the 'MVar' was full with contents @a@.
157 --
158 -- @since 4.7.0.0
159 tryReadMVar :: MVar a -> IO (Maybe a)
160 tryReadMVar (MVar m) = IO $ \ s ->
161 case tryReadMVar# m s of
162 (# s', 0#, _ #) -> (# s', Nothing #) -- MVar is empty
163 (# s', _, a #) -> (# s', Just a #) -- MVar is full
164
165 -- |Check whether a given 'MVar' is empty.
166 --
167 -- Notice that the boolean value returned is just a snapshot of
168 -- the state of the MVar. By the time you get to react on its result,
169 -- the MVar may have been filled (or emptied) - so be extremely
170 -- careful when using this operation. Use 'tryTakeMVar' instead if possible.
171 isEmptyMVar :: MVar a -> IO Bool
172 isEmptyMVar (MVar mv#) = IO $ \ s# ->
173 case isEmptyMVar# mv# s# of
174 (# s2#, flg #) -> (# s2#, isTrue# (flg /=# 0#) #)
175
176 -- |Add a finalizer to an 'MVar' (GHC only). See "Foreign.ForeignPtr" and
177 -- "System.Mem.Weak" for more about finalizers.
178 addMVarFinalizer :: MVar a -> IO () -> IO ()
179 addMVarFinalizer (MVar m) (IO finalizer) =
180 IO $ \s -> case mkWeak# m () finalizer' s of { (# s1, _ #) -> (# s1, () #) }
181 where
182 finalizer' :: State# RealWorld -> State# RealWorld
183 finalizer' s' = case finalizer s' of (# s'', () #) -> s''
184