1 -----------------------------------------------------------------------------
3 -- Module : Control.Concurrent
4 -- Copyright : (c) The University of Glasgow 2001
5 -- License : BSD-style (see the file libraries/base/LICENSE)
7 -- Maintainer : libraries@haskell.org
8 -- Stability : experimental
9 -- Portability : non-portable (concurrency)
11 -- A common interface to a collection of useful concurrency
14 -----------------------------------------------------------------------------
16 module Control.Concurrent (
17 -- * Concurrent Haskell
21 -- * Basic concurrency operations
39 #ifdef __GLASGOW_HASKELL__
41 threadDelay, -- :: Int -> IO ()
42 threadWaitRead, -- :: Int -> IO ()
43 threadWaitWrite, -- :: Int -> IO ()
46 -- * Communication abstractions
48 module Control.Concurrent.MVar,
49 module Control.Concurrent.Chan,
50 module Control.Concurrent.QSem,
51 module Control.Concurrent.QSemN,
52 module Control.Concurrent.SampleVar,
54 -- * Merging of streams
55 mergeIO, -- :: [a] -> [a] -> IO [a]
56 nmergeIO, -- :: [[a]] -> IO [a]
59 -- * GHC's implementation of concurrency
61 -- |This section describes features specific to GHC's
62 -- implementation of Concurrent Haskell.
64 -- ** Terminating the program
76 import Control.Exception as Exception
78 #ifdef __GLASGOW_HASKELL__
80 import GHC.TopHandler ( reportStackOverflow, reportError )
81 import GHC.IOBase ( IO(..) )
82 import GHC.IOBase ( unsafeInterleaveIO )
87 import IOExts ( unsafeInterleaveIO )
91 import Control.Concurrent.MVar
92 import Control.Concurrent.Chan
93 import Control.Concurrent.QSem
94 import Control.Concurrent.QSemN
95 import Control.Concurrent.SampleVar
99 The concurrency extension for Haskell is described in the paper
101 <http://www.haskell.org/ghc/docs/papers/concurrent-haskell.ps.gz>.
103 Concurrency is \"lightweight\", which means that both thread creation
104 and context switching overheads are extremely low. Scheduling of
105 Haskell threads is done internally in the Haskell runtime system, and
106 doesn't make use of any operating system-supplied thread packages.
108 Haskell threads can communicate via 'MVar's, a kind of synchronised
109 mutable variable (see "Control.Concurrent.MVar"). Several common
110 concurrency abstractions can be built from 'MVar's, and these are
111 provided by the "Concurrent" library. Threads may also communicate
117 Scheduling may be either pre-emptive or co-operative,
118 depending on the implementation of Concurrent Haskell (see below
119 for imformation related to specific compilers). In a co-operative
120 system, context switches only occur when you use one of the
121 primitives defined in this module. This means that programs such
125 > main = forkIO (write 'a') >> write 'b'
126 > where write c = putChar c >> write c
128 will print either @aaaaaaaaaaaaaa...@ or @bbbbbbbbbbbb...@,
129 instead of some random interleaving of @a@s and @b@s. In
130 practice, cooperative multitasking is sufficient for writing
131 simple graphical user interfaces.
135 Calling a foreign C procedure (such as @getchar@) that blocks waiting
136 for input will block /all/ threads, unless the @threadsafe@ attribute
137 is used on the foreign call (and your compiler \/ operating system
138 supports it). GHC's I\/O system uses non-blocking I\/O internally to
139 implement thread-friendly I\/O, so calling standard Haskell I\/O
140 functions blocks only the thread making the call.
143 -- Thread Ids, specifically the instances of Eq and Ord for these things.
144 -- The ThreadId type itself is defined in std/PrelConc.lhs.
146 -- Rather than define a new primitve, we use a little helper function
147 -- cmp_thread in the RTS.
149 #ifdef __GLASGOW_HASKELL__
150 foreign import ccall unsafe "cmp_thread" cmp_thread :: Addr# -> Addr# -> Int
153 cmpThread :: ThreadId -> ThreadId -> Ordering
154 cmpThread (ThreadId t1) (ThreadId t2) =
155 case cmp_thread (unsafeCoerce# t1) (unsafeCoerce# t2) of
160 instance Eq ThreadId where
162 case t1 `cmpThread` t2 of
166 instance Ord ThreadId where
169 foreign import ccall unsafe "rts_getThreadId" getThreadId :: Addr# -> Int
171 instance Show ThreadId where
172 showsPrec d (ThreadId t) =
173 showString "ThreadId " .
174 showsPrec d (getThreadId (unsafeCoerce# t))
177 This sparks off a new thread to run the 'IO' computation passed as the
178 first argument, and returns the 'ThreadId' of the newly created
181 forkIO :: IO () -> IO ThreadId
182 forkIO action = IO $ \ s ->
183 case (fork# action_plus s) of (# s1, id #) -> (# s1, ThreadId id #)
185 action_plus = Exception.catch action childHandler
187 childHandler :: Exception -> IO ()
188 childHandler err = Exception.catch (real_handler err) childHandler
190 real_handler :: Exception -> IO ()
193 -- ignore thread GC and killThread exceptions:
194 BlockedOnDeadMVar -> return ()
195 AsyncException ThreadKilled -> return ()
197 -- report all others:
198 AsyncException StackOverflow -> reportStackOverflow False
199 ErrorCall s -> reportError False s
200 other -> reportError False (showsPrec 0 other "\n")
202 #endif /* __GLASGOW_HASKELL__ */
208 mergeIO :: [a] -> [a] -> IO [a]
209 nmergeIO :: [[a]] -> IO [a]
212 -- The 'mergeIO' and 'nmergeIO' functions fork one thread for each
213 -- input list that concurrently evaluates that list; the results are
214 -- merged into a single output list.
216 -- Note: Hugs does not provide these functions, since they require
217 -- preemptive multitasking.
220 = newEmptyMVar >>= \ tail_node ->
221 newMVar tail_node >>= \ tail_list ->
222 newQSem max_buff_size >>= \ e ->
223 newMVar 2 >>= \ branches_running ->
227 forkIO (suckIO branches_running buff ls) >>
228 forkIO (suckIO branches_running buff rs) >>
229 takeMVar tail_node >>= \ val ->
234 = (MVar (MVar [a]), QSem)
236 suckIO :: MVar Int -> Buffer a -> [a] -> IO ()
238 suckIO branches_running buff@(tail_list,e) vs
240 [] -> takeMVar branches_running >>= \ val ->
242 takeMVar tail_list >>= \ node ->
244 putMVar tail_list node
246 putMVar branches_running (val-1)
249 takeMVar tail_list >>= \ node ->
250 newEmptyMVar >>= \ next_node ->
252 takeMVar next_node >>= \ y ->
254 return y) >>= \ next_node_val ->
255 putMVar node (x:next_node_val) >>
256 putMVar tail_list next_node >>
257 suckIO branches_running buff xs
263 newEmptyMVar >>= \ tail_node ->
264 newMVar tail_node >>= \ tail_list ->
265 newQSem max_buff_size >>= \ e ->
266 newMVar len >>= \ branches_running ->
270 mapIO (\ x -> forkIO (suckIO branches_running buff x)) lss >>
271 takeMVar tail_node >>= \ val ->
275 mapIO f xs = sequence (map f xs)
277 -- ---------------------------------------------------------------------------
282 In a standalone GHC program, only the main thread is
283 required to terminate in order for the process to terminate.
284 Thus all other forked threads will simply terminate at the same
285 time as the main thread (the terminology for this kind of
286 behaviour is \"daemonic threads\").
288 If you want the program to wait for child threads to
289 finish before exiting, you need to program this yourself. A
290 simple mechanism is to have each child thread write to an
291 'MVar' when it completes, and have the main
292 thread wait on all the 'MVar's before
295 > myForkIO :: IO () -> IO (MVar ())
297 > mvar \<- newEmptyMVar
298 > forkIO (io \`finally\` putMVar mvar ())
301 Note that we use 'finally' from the
302 "Exception" module to make sure that the
303 'MVar' is written to even if the thread dies or
304 is killed for some reason.
306 A better method is to keep a global list of all child
307 threads which we should wait for at the end of the program:
309 > children :: MVar [MVar ()]
310 > children = unsafePerformIO (newMVar [])
312 > waitForChildren :: IO ()
313 > waitForChildren = do
314 > (mvar:mvars) \<- takeMVar children
315 > putMVar children mvars
319 > forkChild :: IO () -> IO ()
321 > mvar \<- newEmptyMVar
322 > forkIO (p \`finally\` putMVar mvar ())
323 > childs \<- takeMVar children
324 > putMVar children (mvar:childs)
326 > later = flip finally
329 > later waitForChildren $
332 The main thread principle also applies to calls to Haskell from
333 outside, using @foreign export@. When the @foreign export@ed
334 function is invoked, it starts a new main thread, and it returns
335 when this main thread terminates. If the call causes new
336 threads to be forked, they may remain in the system after the
337 @foreign export@ed function has returned.
342 GHC implements pre-emptive multitasking: the execution of
343 threads are interleaved in a random fashion. More specifically,
344 a thread may be pre-empted whenever it allocates some memory,
345 which unfortunately means that tight loops which do no
346 allocation tend to lock out other threads (this only seems to
347 happen with pathalogical benchmark-style code, however).
349 The rescheduling timer runs on a 20ms granularity by
350 default, but this may be altered using the
351 @-i<n>@ RTS option. After a rescheduling
352 \"tick\" the running thread is pre-empted as soon as
356 @aaaa@ @bbbb@ example may not
357 work too well on GHC (see Scheduling, above), due
358 to the locking on a 'Handle'. Only one thread
359 may hold the lock on a 'Handle' at any one
360 time, so if a reschedule happens while a thread is holding the
361 lock, the other thread won't be able to run. The upshot is that
362 the switch from @aaaa@ to
363 @bbbbb@ happens infrequently. It can be
364 improved by lowering the reschedule tick period. We also have a
365 patch that causes a reschedule whenever a thread waiting on a
366 lock is woken up, but haven't found it to be useful for anything
367 other than this example :-)