Remove commented types in module export lists
[packages/base.git] / 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 , putMVar
27 , tryTakeMVar
28 , tryPutMVar
29 , isEmptyMVar
30 , addMVarFinalizer
31 ) where
32
33 import GHC.Base
34 import Data.Maybe
35
36 data MVar a = MVar (MVar# RealWorld a)
37 {- ^
38 An 'MVar' (pronounced \"em-var\") is a synchronising variable, used
39 for communication between concurrent threads. It can be thought of
40 as a a box, which may be empty or full.
41 -}
42
43 -- pull in Eq (Mvar a) too, to avoid GHC.Conc being an orphan-instance module
44 instance Eq (MVar a) where
45 (MVar mvar1#) == (MVar mvar2#) = sameMVar# mvar1# mvar2#
46
47 {-
48 M-Vars are rendezvous points for concurrent threads. They begin
49 empty, and any attempt to read an empty M-Var blocks. When an M-Var
50 is written, a single blocked thread may be freed. Reading an M-Var
51 toggles its state from full back to empty. Therefore, any value
52 written to an M-Var may only be read once. Multiple reads and writes
53 are allowed, but there must be at least one read between any two
54 writes.
55 -}
56
57 --Defined in IOBase to avoid cycle: data MVar a = MVar (SynchVar# RealWorld a)
58
59 -- |Create an 'MVar' which is initially empty.
60 newEmptyMVar :: IO (MVar a)
61 newEmptyMVar = IO $ \ s# ->
62 case newMVar# s# of
63 (# s2#, svar# #) -> (# s2#, MVar svar# #)
64
65 -- |Create an 'MVar' which contains the supplied value.
66 newMVar :: a -> IO (MVar a)
67 newMVar value =
68 newEmptyMVar >>= \ mvar ->
69 putMVar mvar value >>
70 return mvar
71
72 -- |Return the contents of the 'MVar'. If the 'MVar' is currently
73 -- empty, 'takeMVar' will wait until it is full. After a 'takeMVar',
74 -- the 'MVar' is left empty.
75 --
76 -- There are two further important properties of 'takeMVar':
77 --
78 -- * 'takeMVar' is single-wakeup. That is, if there are multiple
79 -- threads blocked in 'takeMVar', and the 'MVar' becomes full,
80 -- only one thread will be woken up. The runtime guarantees that
81 -- the woken thread completes its 'takeMVar' operation.
82 --
83 -- * When multiple threads are blocked on an 'MVar', they are
84 -- woken up in FIFO order. This is useful for providing
85 -- fairness properties of abstractions built using 'MVar's.
86 --
87 takeMVar :: MVar a -> IO a
88 takeMVar (MVar mvar#) = IO $ \ s# -> takeMVar# mvar# s#
89
90 -- |Put a value into an 'MVar'. If the 'MVar' is currently full,
91 -- 'putMVar' will wait until it becomes empty.
92 --
93 -- There are two further important properties of 'putMVar':
94 --
95 -- * 'putMVar' is single-wakeup. That is, if there are multiple
96 -- threads blocked in 'putMVar', and the 'MVar' becomes empty,
97 -- only one thread will be woken up. The runtime guarantees that
98 -- the woken thread completes its 'putMVar' operation.
99 --
100 -- * When multiple threads are blocked on an 'MVar', they are
101 -- woken up in FIFO order. This is useful for providing
102 -- fairness properties of abstractions built using 'MVar's.
103 --
104 putMVar :: MVar a -> a -> IO ()
105 putMVar (MVar mvar#) x = IO $ \ s# ->
106 case putMVar# mvar# x s# of
107 s2# -> (# s2#, () #)
108
109 -- |A non-blocking version of 'takeMVar'. The 'tryTakeMVar' function
110 -- returns immediately, with 'Nothing' if the 'MVar' was empty, or
111 -- @'Just' a@ if the 'MVar' was full with contents @a@. After 'tryTakeMVar',
112 -- the 'MVar' is left empty.
113 tryTakeMVar :: MVar a -> IO (Maybe a)
114 tryTakeMVar (MVar m) = IO $ \ s ->
115 case tryTakeMVar# m s of
116 (# s', 0#, _ #) -> (# s', Nothing #) -- MVar is empty
117 (# s', _, a #) -> (# s', Just a #) -- MVar is full
118
119 -- |A non-blocking version of 'putMVar'. The 'tryPutMVar' function
120 -- attempts to put the value @a@ into the 'MVar', returning 'True' if
121 -- it was successful, or 'False' otherwise.
122 tryPutMVar :: MVar a -> a -> IO Bool
123 tryPutMVar (MVar mvar#) x = IO $ \ s# ->
124 case tryPutMVar# mvar# x s# of
125 (# s, 0# #) -> (# s, False #)
126 (# s, _ #) -> (# s, True #)
127
128 -- |Check whether a given 'MVar' is empty.
129 --
130 -- Notice that the boolean value returned is just a snapshot of
131 -- the state of the MVar. By the time you get to react on its result,
132 -- the MVar may have been filled (or emptied) - so be extremely
133 -- careful when using this operation. Use 'tryTakeMVar' instead if possible.
134 isEmptyMVar :: MVar a -> IO Bool
135 isEmptyMVar (MVar mv#) = IO $ \ s# ->
136 case isEmptyMVar# mv# s# of
137 (# s2#, flg #) -> (# s2#, not (flg ==# 0#) #)
138
139 -- |Add a finalizer to an 'MVar' (GHC only). See "Foreign.ForeignPtr" and
140 -- "System.Mem.Weak" for more about finalizers.
141 addMVarFinalizer :: MVar a -> IO () -> IO ()
142 addMVarFinalizer (MVar m) finalizer =
143 IO $ \s -> case mkWeak# m () finalizer s of { (# s1, _ #) -> (# s1, () #) }
144