1 % -----------------------------------------------------------------------------
2 % $Id: PrelConc.lhs,v 1.20 2000/07/07 11:03:58 simonmar Exp $
4 % (c) The University of Glasgow, 1994-2000
7 \section[PrelConc]{Module @PrelConc@}
9 Basic concurrency stuff
12 {-# OPTIONS -fno-implicit-prelude #-}
17 -- Forking and suchlike
18 , myThreadId -- :: IO ThreadId
19 , killThread -- :: ThreadId -> IO ()
20 , throwTo -- :: ThreadId -> Exception -> IO ()
21 , par -- :: a -> b -> b
22 , seq -- :: a -> b -> b
26 , threadDelay -- :: Int -> IO ()
27 , threadWaitRead -- :: Int -> IO ()
28 , threadWaitWrite -- :: Int -> IO ()
32 , newMVar -- :: a -> IO (MVar a)
33 , newEmptyMVar -- :: IO (MVar a)
34 , takeMVar -- :: MVar a -> IO a
35 , putMVar -- :: MVar a -> a -> IO ()
36 , readMVar -- :: MVar a -> IO a
37 , swapMVar -- :: MVar a -> a -> IO a
38 , tryTakeMVar -- :: MVar a -> IO (Maybe a)
39 , isEmptyMVar -- :: MVar a -> IO Bool
45 import PrelErr ( parError, seqError )
46 import PrelIOBase ( IO(..), MVar(..) )
47 import PrelBase ( Int(..) )
48 import PrelException ( Exception(..), AsyncException(..) )
53 %************************************************************************
55 \subsection{@ThreadId@, @par@, and @fork@}
57 %************************************************************************
60 data ThreadId = ThreadId ThreadId#
61 -- ToDo: data ThreadId = ThreadId (Weak ThreadId#)
62 -- But since ThreadId# is unlifted, the Weak type must use open
65 --forkIO has now been hoisted out into the Concurrent library.
67 killThread :: ThreadId -> IO ()
68 killThread (ThreadId id) = IO $ \ s ->
69 case (killThread# id (AsyncException ThreadKilled) s) of s1 -> (# s1, () #)
71 throwTo :: ThreadId -> Exception -> IO ()
72 throwTo (ThreadId id) ex = IO $ \ s ->
73 case (killThread# id ex s) of s1 -> (# s1, () #)
75 myThreadId :: IO ThreadId
76 myThreadId = IO $ \s ->
77 case (myThreadId# s) of (# s1, id #) -> (# s1, ThreadId id #)
81 case (yield# s) of s1 -> (# s1, () #)
83 -- "seq" is defined a bit wierdly (see below)
85 -- The reason for the strange "0# -> parError" case is that
86 -- it fools the compiler into thinking that seq is non-strict in
87 -- its second argument (even if it inlines seq at the call site).
88 -- If it thinks seq is strict in "y", then it often evaluates
89 -- "y" before "x", which is totally wrong.
91 -- Just before converting from Core to STG there's a bit of magic
92 -- that recognises the seq# and eliminates the duff case.
96 seq x y = case (seq# x) of { 0# -> seqError; _ -> y }
100 par x y = case (par# x) of { 0# -> parError; _ -> y }
103 %************************************************************************
105 \subsection[mvars]{M-Structures}
107 %************************************************************************
109 M-Vars are rendezvous points for concurrent threads. They begin
110 empty, and any attempt to read an empty M-Var blocks. When an M-Var
111 is written, a single blocked thread may be freed. Reading an M-Var
112 toggles its state from full back to empty. Therefore, any value
113 written to an M-Var may only be read once. Multiple reads and writes
114 are allowed, but there must be at least one read between any two
118 --Defined in IOBase to avoid cycle: data MVar a = MVar (SynchVar# RealWorld a)
120 newEmptyMVar :: IO (MVar a)
121 newEmptyMVar = IO $ \ s# ->
123 (# s2#, svar# #) -> (# s2#, MVar svar# #)
125 takeMVar :: MVar a -> IO a
126 takeMVar (MVar mvar#) = IO $ \ s# -> takeMVar# mvar# s#
128 putMVar :: MVar a -> a -> IO ()
129 putMVar (MVar mvar#) x = IO $ \ s# ->
130 case putMVar# mvar# x s# of
133 newMVar :: a -> IO (MVar a)
135 newEmptyMVar >>= \ mvar ->
136 putMVar mvar value >>
139 readMVar :: MVar a -> IO a
141 takeMVar mvar >>= \ value ->
142 putMVar mvar value >>
145 swapMVar :: MVar a -> a -> IO a
147 takeMVar mvar >>= \ old ->
151 -- tryTakeMVar is a non-blocking takeMVar
152 tryTakeMVar :: MVar a -> IO (Maybe a)
153 tryTakeMVar (MVar m) = IO $ \ s ->
154 case tryTakeMVar# m s of
155 (# s, 0#, _ #) -> (# s, Nothing #) -- MVar is empty
156 (# s, _, a #) -> (# s, Just a #) -- MVar is full
159 Low-level op. for checking whether an MVar is filled-in or not.
160 Notice that the boolean value returned is just a snapshot of
161 the state of the MVar. By the time you get to react on its result,
162 the MVar may have been filled (or emptied) - so be extremely
163 careful when using this operation.
165 Use tryTakeMVar instead if possible.
167 If you can re-work your abstractions to avoid having to
168 depend on isEmptyMVar, then you're encouraged to do so,
169 i.e., consider yourself warned about the imprecision in
170 general of isEmptyMVar :-)
172 isEmptyMVar :: MVar a -> IO Bool
173 isEmptyMVar (MVar mv#) = IO $ \ s# ->
174 case isEmptyMVar# mv# s# of
175 (# s2#, flg #) -> (# s2#, not (flg ==# 0#) #)
179 %************************************************************************
181 \subsection{Thread waiting}
183 %************************************************************************
185 @threadDelay@ delays rescheduling of a thread until the indicated
186 number of microseconds have elapsed. Generally, the microseconds are
187 counted by the context switch timer, which ticks in virtual time;
188 however, when there are no runnable threads, we don't accumulate any
189 virtual time, so we start ticking in real time. (The granularity is
190 the effective resolution of the context switch timer, so it is
191 affected by the RTS -C option.)
193 @threadWaitRead@ delays rescheduling of a thread until input on the
194 specified file descriptor is available for reading (just like select).
195 @threadWaitWrite@ is similar, but for writing on a file descriptor.
198 threadDelay, threadWaitRead, threadWaitWrite :: Int -> IO ()
200 threadDelay (I# ms) = IO $ \s -> case delay# ms s of s -> (# s, () #)
201 threadWaitRead (I# fd) = IO $ \s -> case waitRead# fd s of s -> (# s, () #)
202 threadWaitWrite (I# fd) = IO $ \s -> case waitWrite# fd s of s -> (# s, () #)