Rename atomicReadMVar and friends to readMVar, replacing old readMVar.
[packages/base.git] / GHC / MVar.hs
1 {-# LANGUAGE Unsafe, DeriveDataTypeable #-}
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 import Data.Maybe
37 import Data.Typeable
38
39 data MVar a = MVar (MVar# RealWorld a) deriving( Typeable )
40 {- ^
41 An 'MVar' (pronounced \"em-var\") is a synchronising variable, used
42 for communication between concurrent threads. It can be thought of
43 as a a box, which may be empty or full.
44 -}
45
46 -- pull in Eq (Mvar a) too, to avoid GHC.Conc being an orphan-instance module
47 instance Eq (MVar a) where
48 (MVar mvar1#) == (MVar mvar2#) = sameMVar# mvar1# mvar2#
49
50 {-
51 M-Vars are rendezvous points for concurrent threads. They begin
52 empty, and any attempt to read an empty M-Var blocks. When an M-Var
53 is written, a single blocked thread may be freed. Reading an M-Var
54 toggles its state from full back to empty. Therefore, any value
55 written to an M-Var may only be read once. Multiple reads and writes
56 are allowed, but there must be at least one read between any two
57 writes.
58 -}
59
60 --Defined in IOBase to avoid cycle: data MVar a = MVar (SynchVar# RealWorld a)
61
62 -- |Create an 'MVar' which is initially empty.
63 newEmptyMVar :: IO (MVar a)
64 newEmptyMVar = IO $ \ s# ->
65 case newMVar# s# of
66 (# s2#, svar# #) -> (# s2#, MVar svar# #)
67
68 -- |Create an 'MVar' which contains the supplied value.
69 newMVar :: a -> IO (MVar a)
70 newMVar value =
71 newEmptyMVar >>= \ mvar ->
72 putMVar mvar value >>
73 return mvar
74
75 -- |Return the contents of the 'MVar'. If the 'MVar' is currently
76 -- empty, 'takeMVar' will wait until it is full. After a 'takeMVar',
77 -- the 'MVar' is left empty.
78 --
79 -- There are two further important properties of 'takeMVar':
80 --
81 -- * 'takeMVar' is single-wakeup. That is, if there are multiple
82 -- threads blocked in 'takeMVar', and the 'MVar' becomes full,
83 -- only one thread will be woken up. The runtime guarantees that
84 -- the woken thread completes its 'takeMVar' operation.
85 --
86 -- * When multiple threads are blocked on an 'MVar', they are
87 -- woken up in FIFO order. This is useful for providing
88 -- fairness properties of abstractions built using 'MVar's.
89 --
90 takeMVar :: MVar a -> IO a
91 takeMVar (MVar mvar#) = IO $ \ s# -> takeMVar# mvar# s#
92
93 -- |Atomically read the contents of an 'MVar'. If the 'MVar' is
94 -- currently empty, 'readMVar' will wait until its full.
95 -- 'readMVar' is guaranteed to receive the next 'putMVar'.
96 --
97 -- 'readMVar' is multiple-wakeup, so when multiple readers are
98 -- blocked on an 'MVar', all of them are woken up at the same time.
99 --
100 -- /Compatibility note:/ Prior to base 4.7, 'readMVar' was a combination
101 -- of 'takeMVar' and 'putMVar'. This mean that in the presence of
102 -- other threads attempting to 'putMVar', 'readMVar' could block.
103 -- Furthermore, 'readMVar' would not be serviced immediately if there
104 -- were already pending thread blocked on 'takeMVar'. The old behavior
105 -- can be recovered by implementing 'readMVar as follows:
106 --
107 -- @
108 -- readMVar :: MVar a -> IO a
109 -- readMVar m =
110 -- mask_ $ do
111 -- a <- takeMVar m
112 -- putMVar m a
113 -- return a
114 -- @
115 readMVar :: MVar a -> IO a
116 readMVar (MVar mvar#) = IO $ \ s# -> readMVar# mvar# s#
117
118 -- |Put a value into an 'MVar'. If the 'MVar' is currently full,
119 -- 'putMVar' will wait until it becomes empty.
120 --
121 -- There are two further important properties of 'putMVar':
122 --
123 -- * 'putMVar' is single-wakeup. That is, if there are multiple
124 -- threads blocked in 'putMVar', and the 'MVar' becomes empty,
125 -- only one thread will be woken up. The runtime guarantees that
126 -- the woken thread completes its 'putMVar' operation.
127 --
128 -- * When multiple threads are blocked on an 'MVar', they are
129 -- woken up in FIFO order. This is useful for providing
130 -- fairness properties of abstractions built using 'MVar's.
131 --
132 putMVar :: MVar a -> a -> IO ()
133 putMVar (MVar mvar#) x = IO $ \ s# ->
134 case putMVar# mvar# x s# of
135 s2# -> (# s2#, () #)
136
137 -- |A non-blocking version of 'takeMVar'. The 'tryTakeMVar' function
138 -- returns immediately, with 'Nothing' if the 'MVar' was empty, or
139 -- @'Just' a@ if the 'MVar' was full with contents @a@. After 'tryTakeMVar',
140 -- the 'MVar' is left empty.
141 tryTakeMVar :: MVar a -> IO (Maybe a)
142 tryTakeMVar (MVar m) = IO $ \ s ->
143 case tryTakeMVar# m s of
144 (# s', 0#, _ #) -> (# s', Nothing #) -- MVar is empty
145 (# s', _, a #) -> (# s', Just a #) -- MVar is full
146
147 -- |A non-blocking version of 'putMVar'. The 'tryPutMVar' function
148 -- attempts to put the value @a@ into the 'MVar', returning 'True' if
149 -- it was successful, or 'False' otherwise.
150 tryPutMVar :: MVar a -> a -> IO Bool
151 tryPutMVar (MVar mvar#) x = IO $ \ s# ->
152 case tryPutMVar# mvar# x s# of
153 (# s, 0# #) -> (# s, False #)
154 (# s, _ #) -> (# s, True #)
155
156 -- |A non-blocking version of 'readMVar'. The 'tryReadMVar' function
157 -- returns immediately, with 'Nothing' if the 'MVar' was empty, or
158 -- @'Just' a@ if the 'MVar' was full with contents @a@.
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#, not (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) finalizer =
180 IO $ \s -> case mkWeak# m () finalizer s of { (# s1, _ #) -> (# s1, () #) }
181