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
24 #ifdef __GLASGOW_HASKELL__
29 #ifdef __GLASGOW_HASKELL__
43 #ifdef __GLASGOW_HASKELL__
45 threadDelay, -- :: Int -> IO ()
46 threadWaitRead, -- :: Int -> IO ()
47 threadWaitWrite, -- :: Int -> IO ()
50 -- * Communication abstractions
52 module Control.Concurrent.MVar,
53 module Control.Concurrent.Chan,
54 module Control.Concurrent.QSem,
55 module Control.Concurrent.QSemN,
56 module Control.Concurrent.SampleVar,
58 -- * Merging of streams
60 mergeIO, -- :: [a] -> [a] -> IO [a]
61 nmergeIO, -- :: [[a]] -> IO [a]
65 #ifdef __GLASGOW_HASKELL__
68 rtsSupportsBoundThreads,
75 -- * GHC's implementation of concurrency
77 -- |This section describes features specific to GHC's
78 -- implementation of Concurrent Haskell.
80 -- ** Haskell threads and Operating System threads
84 -- ** Terminating the program
95 import Control.Exception as Exception
97 #ifdef __GLASGOW_HASKELL__
98 import GHC.Conc ( ThreadId(..), myThreadId, killThread, yield,
99 threadDelay, threadWaitRead, threadWaitWrite,
100 forkIO, childHandler )
101 import GHC.TopHandler ( reportStackOverflow, reportError )
102 import GHC.IOBase ( IO(..) )
103 import GHC.IOBase ( unsafeInterleaveIO )
104 import GHC.IOBase ( newIORef, readIORef, writeIORef )
107 import Foreign.StablePtr
108 import Foreign.C.Types ( CInt )
109 import Control.Monad ( when )
116 import Control.Concurrent.MVar
117 import Control.Concurrent.Chan
118 import Control.Concurrent.QSem
119 import Control.Concurrent.QSemN
120 import Control.Concurrent.SampleVar
128 The concurrency extension for Haskell is described in the paper
130 <http://www.haskell.org/ghc/docs/papers/concurrent-haskell.ps.gz>.
132 Concurrency is \"lightweight\", which means that both thread creation
133 and context switching overheads are extremely low. Scheduling of
134 Haskell threads is done internally in the Haskell runtime system, and
135 doesn't make use of any operating system-supplied thread packages.
137 However, if you want to interact with a foreign library that expects your
138 program to use the operating system-supplied thread package, you can do so
139 by using 'forkOS' instead of 'forkIO'.
141 Haskell threads can communicate via 'MVar's, a kind of synchronised
142 mutable variable (see "Control.Concurrent.MVar"). Several common
143 concurrency abstractions can be built from 'MVar's, and these are
144 provided by the "Control.Concurrent" library.
145 In GHC, threads may also communicate via exceptions.
150 Scheduling may be either pre-emptive or co-operative,
151 depending on the implementation of Concurrent Haskell (see below
152 for information related to specific compilers). In a co-operative
153 system, context switches only occur when you use one of the
154 primitives defined in this module. This means that programs such
158 > main = forkIO (write 'a') >> write 'b'
159 > where write c = putChar c >> write c
161 will print either @aaaaaaaaaaaaaa...@ or @bbbbbbbbbbbb...@,
162 instead of some random interleaving of @a@s and @b@s. In
163 practice, cooperative multitasking is sufficient for writing
164 simple graphical user interfaces.
168 Different Haskell implementations have different characteristics with
169 regard to which operations block /all/ threads.
171 Using GHC without the @-threaded@ option, all foreign calls will block
172 all other Haskell threads in the system, although I\/O operations will
173 not. With the @-threaded@ option, only foreign calls with the @unsafe@
174 attribute will block all other threads.
176 Using Hugs, all I\/O operations and foreign calls will block all other
184 mergeIO :: [a] -> [a] -> IO [a]
185 nmergeIO :: [[a]] -> IO [a]
188 -- The 'mergeIO' and 'nmergeIO' functions fork one thread for each
189 -- input list that concurrently evaluates that list; the results are
190 -- merged into a single output list.
192 -- Note: Hugs does not provide these functions, since they require
193 -- preemptive multitasking.
196 = newEmptyMVar >>= \ tail_node ->
197 newMVar tail_node >>= \ tail_list ->
198 newQSem max_buff_size >>= \ e ->
199 newMVar 2 >>= \ branches_running ->
203 forkIO (suckIO branches_running buff ls) >>
204 forkIO (suckIO branches_running buff rs) >>
205 takeMVar tail_node >>= \ val ->
210 = (MVar (MVar [a]), QSem)
212 suckIO :: MVar Int -> Buffer a -> [a] -> IO ()
214 suckIO branches_running buff@(tail_list,e) vs
216 [] -> takeMVar branches_running >>= \ val ->
218 takeMVar tail_list >>= \ node ->
220 putMVar tail_list node
222 putMVar branches_running (val-1)
225 takeMVar tail_list >>= \ node ->
226 newEmptyMVar >>= \ next_node ->
228 takeMVar next_node >>= \ y ->
230 return y) >>= \ next_node_val ->
231 putMVar node (x:next_node_val) >>
232 putMVar tail_list next_node >>
233 suckIO branches_running buff xs
239 newEmptyMVar >>= \ tail_node ->
240 newMVar tail_node >>= \ tail_list ->
241 newQSem max_buff_size >>= \ e ->
242 newMVar len >>= \ branches_running ->
246 mapIO (\ x -> forkIO (suckIO branches_running buff x)) lss >>
247 takeMVar tail_node >>= \ val ->
251 mapIO f xs = sequence (map f xs)
252 #endif /* __HUGS__ */
254 #ifdef __GLASGOW_HASKELL__
255 -- ---------------------------------------------------------------------------
261 Support for multiple operating system threads and bound threads as described
262 below is currently only available in the GHC runtime system if you use the
263 /-threaded/ option when linking.
265 Other Haskell systems do not currently support multiple operating system threads.
267 A bound thread is a haskell thread that is /bound/ to an operating system
268 thread. While the bound thread is still scheduled by the Haskell run-time
269 system, the operating system thread takes care of all the foreign calls made
272 To a foreign library, the bound thread will look exactly like an ordinary
273 operating system thread created using OS functions like @pthread_create@
276 Bound threads can be created using the 'forkOS' function below. All foreign
277 exported functions are run in a bound thread (bound to the OS thread that
278 called the function). Also, the @main@ action of every Haskell program is
279 run in a bound thread.
281 Why do we need this? Because if a foreign library is called from a thread
282 created using 'forkIO', it won't have access to any /thread-local state/ -
283 state variables that have specific values for each OS thread
284 (see POSIX's @pthread_key_create@ or Win32's @TlsAlloc@). Therefore, some
285 libraries (OpenGL, for example) will not work from a thread created using
286 'forkIO'. They work fine in threads created using 'forkOS' or when called
287 from @main@ or from a @foreign export@.
290 -- | 'True' if bound threads are supported.
291 -- If @rtsSupportsBoundThreads@ is 'False', 'isCurrentThreadBound'
292 -- will always return 'False' and both 'forkOS' and 'runInBoundThread' will
294 foreign import ccall rtsSupportsBoundThreads :: Bool
298 Like 'forkIO', this sparks off a new thread to run the 'IO' computation passed as the
299 first argument, and returns the 'ThreadId' of the newly created
302 However, @forkOS@ uses operating system-supplied multithreading support to create
303 a new operating system thread. The new thread is /bound/, which means that
304 all foreign calls made by the 'IO' computation are guaranteed to be executed
305 in this new operating system thread; also, the operating system thread is not
306 used for any other foreign calls.
308 This means that you can use all kinds of foreign libraries from this thread
309 (even those that rely on thread-local state), without the limitations of 'forkIO'.
311 Just to clarify, 'forkOS' is /only/ necessary if you need to associate
312 a Haskell thread with a particular OS thread. It is not necessary if
313 you only need to make non-blocking foreign calls (see "Control.Concurrent#osthreads").
316 forkOS :: IO () -> IO ThreadId
318 foreign export ccall forkOS_entry
319 :: StablePtr (IO ()) -> IO ()
321 foreign import ccall "forkOS_entry" forkOS_entry_reimported
322 :: StablePtr (IO ()) -> IO ()
324 forkOS_entry stableAction = do
325 action <- deRefStablePtr stableAction
328 foreign import ccall forkOS_createThread
329 :: StablePtr (IO ()) -> IO CInt
331 failNonThreaded = fail $ "RTS doesn't support multiple OS threads "
332 ++"(use ghc -threaded when linking)"
335 | rtsSupportsBoundThreads = do
337 let action_plus = Exception.catch action childHandler
338 entry <- newStablePtr (myThreadId >>= putMVar mv >> action_plus)
339 err <- forkOS_createThread entry
340 when (err /= 0) $ fail "Cannot create OS thread."
344 | otherwise = failNonThreaded
346 -- | Returns 'True' if the calling thread is /bound/, that is, if it is
347 -- safe to use foreign libraries that rely on thread-local state from the
349 isCurrentThreadBound :: IO Bool
350 isCurrentThreadBound = IO $ \ s# ->
351 case isCurrentThreadBound# s# of
352 (# s2#, flg #) -> (# s2#, not (flg ==# 0#) #)
356 Run the 'IO' computation passed as the first argument. If the calling thread
357 is not /bound/, a bound thread is created temporarily. @runInBoundThread@
358 doesn't finish until the 'IO' computation finishes.
360 You can wrap a series of foreign function calls that rely on thread-local state
361 with @runInBoundThread@ so that you can use them without knowing whether the
362 current thread is /bound/.
364 runInBoundThread :: IO a -> IO a
366 runInBoundThread action
367 | rtsSupportsBoundThreads = do
368 bound <- isCurrentThreadBound
372 ref <- newIORef undefined
373 let action_plus = Exception.try action >>= writeIORef ref
375 bracket (newStablePtr action_plus)
377 (\cEntry -> forkOS_entry_reimported cEntry >> readIORef ref)
378 case resultOrException of
379 Left exception -> Exception.throw exception
380 Right result -> return result
381 | otherwise = failNonThreaded
384 Run the 'IO' computation passed as the first argument. If the calling thread
385 is /bound/, an unbound thread is created temporarily using 'forkIO'.
386 @runInBoundThread@ doesn't finish until the 'IO' computation finishes.
388 Use this function /only/ in the rare case that you have actually observed a
389 performance loss due to the use of bound threads. A program that
390 doesn't need it's main thread to be bound and makes /heavy/ use of concurrency
391 (e.g. a web server), might want to wrap it's @main@ action in
392 @runInUnboundThread@.
394 runInUnboundThread :: IO a -> IO a
396 runInUnboundThread action = do
397 bound <- isCurrentThreadBound
401 forkIO (Exception.try action >>= putMVar mv)
402 takeMVar mv >>= \either -> case either of
403 Left exception -> Exception.throw exception
404 Right result -> return result
407 #endif /* __GLASGOW_HASKELL__ */
409 -- ---------------------------------------------------------------------------
414 #osthreads# In GHC, threads created by 'forkIO' are lightweight threads, and
415 are managed entirely by the GHC runtime. Typically Haskell
416 threads are an order of magnitude or two more efficient (in
417 terms of both time and space) than operating system threads.
419 The downside of having lightweight threads is that only one can
420 run at a time, so if one thread blocks in a foreign call, for
421 example, the other threads cannot continue. The GHC runtime
422 works around this by making use of full OS threads where
423 necessary. When the program is built with the @-threaded@
424 option (to link against the multithreaded version of the
425 runtime), a thread making a @safe@ foreign call will not block
426 the other threads in the system; another OS thread will take
427 over running Haskell threads until the original call returns.
428 The runtime maintains a pool of these /worker/ threads so that
429 multiple Haskell threads can be involved in external calls
432 The "System.IO" library manages multiplexing in its own way. On
433 Windows systems it uses @safe@ foreign calls to ensure that
434 threads doing I\/O operations don't block the whole runtime,
435 whereas on Unix systems all the currently blocked I\/O reqwests
436 are managed by a single thread (the /IO manager thread/) using
439 The runtime will run a Haskell thread using any of the available
440 worker OS threads. If you need control over which particular OS
441 thread is used to run a given Haskell thread, perhaps because
442 you need to call a foreign library that uses OS-thread-local
443 state, then you need bound threads (see "Control.Concurrent#boundthreads").
445 If you don't use the @-threaded@ option, then the runtime does
446 not make use of multiple OS threads. Foreign calls will block
447 all other running Haskell threads until the call returns. The
448 "System.IO" library still does multiplexing, so there can be multiple
449 threads doing I\/O, and this is handled internally by the runtime using
455 In a standalone GHC program, only the main thread is
456 required to terminate in order for the process to terminate.
457 Thus all other forked threads will simply terminate at the same
458 time as the main thread (the terminology for this kind of
459 behaviour is \"daemonic threads\").
461 If you want the program to wait for child threads to
462 finish before exiting, you need to program this yourself. A
463 simple mechanism is to have each child thread write to an
464 'MVar' when it completes, and have the main
465 thread wait on all the 'MVar's before
468 > myForkIO :: IO () -> IO (MVar ())
470 > mvar <- newEmptyMVar
471 > forkIO (io `finally` putMVar mvar ())
474 Note that we use 'finally' from the
475 "Control.Exception" module to make sure that the
476 'MVar' is written to even if the thread dies or
477 is killed for some reason.
479 A better method is to keep a global list of all child
480 threads which we should wait for at the end of the program:
482 > children :: MVar [MVar ()]
483 > children = unsafePerformIO (newMVar [])
485 > waitForChildren :: IO ()
486 > waitForChildren = do
487 > cs <- takeMVar children
491 > putMVar children ms
495 > forkChild :: IO () -> IO ()
497 > mvar <- newEmptyMVar
498 > childs <- takeMVar children
499 > putMVar children (mvar:childs)
500 > forkIO (io `finally` putMVar mvar ())
503 > later waitForChildren $
506 The main thread principle also applies to calls to Haskell from
507 outside, using @foreign export@. When the @foreign export@ed
508 function is invoked, it starts a new main thread, and it returns
509 when this main thread terminates. If the call causes new
510 threads to be forked, they may remain in the system after the
511 @foreign export@ed function has returned.
516 GHC implements pre-emptive multitasking: the execution of
517 threads are interleaved in a random fashion. More specifically,
518 a thread may be pre-empted whenever it allocates some memory,
519 which unfortunately means that tight loops which do no
520 allocation tend to lock out other threads (this only seems to
521 happen with pathological benchmark-style code, however).
523 The rescheduling timer runs on a 20ms granularity by
524 default, but this may be altered using the
525 @-i\<n\>@ RTS option. After a rescheduling
526 \"tick\" the running thread is pre-empted as soon as
530 @aaaa@ @bbbb@ example may not
531 work too well on GHC (see Scheduling, above), due
532 to the locking on a 'System.IO.Handle'. Only one thread
533 may hold the lock on a 'System.IO.Handle' at any one
534 time, so if a reschedule happens while a thread is holding the
535 lock, the other thread won't be able to run. The upshot is that
536 the switch from @aaaa@ to
537 @bbbbb@ happens infrequently. It can be
538 improved by lowering the reschedule tick period. We also have a
539 patch that causes a reschedule whenever a thread waiting on a
540 lock is woken up, but haven't found it to be useful for anything
541 other than this example :-)