ce08faa6007a436cf653cd51d21719e8a0f85fca
[packages/base.git] / Control / Concurrent.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE CPP
3 , ForeignFunctionInterface
4 , MagicHash
5 , UnboxedTuples
6 , ScopedTypeVariables
7 #-}
8 {-# OPTIONS_GHC -fno-warn-unused-imports #-}
9 {-# OPTIONS_GHC -fno-warn-deprecations #-}
10 -- kludge for the Control.Concurrent.QSem, Control.Concurrent.QSemN
11 -- and Control.Concurrent.SampleVar imports.
12
13 -----------------------------------------------------------------------------
14 -- |
15 -- Module : Control.Concurrent
16 -- Copyright : (c) The University of Glasgow 2001
17 -- License : BSD-style (see the file libraries/base/LICENSE)
18 --
19 -- Maintainer : libraries@haskell.org
20 -- Stability : experimental
21 -- Portability : non-portable (concurrency)
22 --
23 -- A common interface to a collection of useful concurrency
24 -- abstractions.
25 --
26 -----------------------------------------------------------------------------
27
28 module Control.Concurrent (
29 -- * Concurrent Haskell
30
31 -- $conc_intro
32
33 -- * Basic concurrency operations
34
35 ThreadId,
36 #ifdef __GLASGOW_HASKELL__
37 myThreadId,
38 #endif
39
40 forkIO,
41 #ifdef __GLASGOW_HASKELL__
42 forkFinally,
43 forkIOWithUnmask,
44 killThread,
45 throwTo,
46 #endif
47
48 -- ** Threads with affinity
49 forkOn,
50 forkOnWithUnmask,
51 getNumCapabilities,
52 setNumCapabilities,
53 threadCapability,
54
55 -- * Scheduling
56
57 -- $conc_scheduling
58 yield,
59
60 -- ** Blocking
61
62 -- $blocking
63
64 #ifdef __GLASGOW_HASKELL__
65 -- ** Waiting
66 threadDelay,
67 threadWaitRead,
68 threadWaitWrite,
69 threadWaitReadSTM,
70 threadWaitWriteSTM,
71 #endif
72
73 -- * Communication abstractions
74
75 module Control.Concurrent.MVar,
76 module Control.Concurrent.Chan,
77 module Control.Concurrent.QSem,
78 module Control.Concurrent.QSemN,
79
80 #ifdef __GLASGOW_HASKELL__
81 -- * Bound Threads
82 -- $boundthreads
83 rtsSupportsBoundThreads,
84 forkOS,
85 isCurrentThreadBound,
86 runInBoundThread,
87 runInUnboundThread,
88 #endif
89
90 -- * Weak references to ThreadIds
91 mkWeakThreadId,
92
93 -- * GHC's implementation of concurrency
94
95 -- |This section describes features specific to GHC's
96 -- implementation of Concurrent Haskell.
97
98 -- ** Haskell threads and Operating System threads
99
100 -- $osthreads
101
102 -- ** Terminating the program
103
104 -- $termination
105
106 -- ** Pre-emption
107
108 -- $preemption
109
110 -- ** Deadlock
111
112 -- $deadlock
113
114 ) where
115
116 import Prelude
117
118 import Control.Exception.Base as Exception
119
120 #ifdef __GLASGOW_HASKELL__
121 import GHC.Exception
122 import GHC.Conc hiding (threadWaitRead, threadWaitWrite,
123 threadWaitReadSTM, threadWaitWriteSTM)
124 import qualified GHC.Conc
125 import GHC.IO ( IO(..), unsafeInterleaveIO, unsafeUnmask )
126 import GHC.IORef ( newIORef, readIORef, writeIORef )
127 import GHC.Base
128
129 import System.Posix.Types ( Fd )
130 import Foreign.StablePtr
131 import Foreign.C.Types
132 import Control.Monad
133
134 #ifdef mingw32_HOST_OS
135 import Foreign.C
136 import System.IO
137 import Data.Maybe (Maybe(..))
138 #endif
139 #endif
140
141 #ifdef __HUGS__
142 import Hugs.ConcBase
143 #endif
144
145 import Control.Concurrent.MVar
146 import Control.Concurrent.Chan
147 import Control.Concurrent.QSem
148 import Control.Concurrent.QSemN
149
150 #ifdef __HUGS__
151 type ThreadId = ()
152 #endif
153
154 {- $conc_intro
155
156 The concurrency extension for Haskell is described in the paper
157 /Concurrent Haskell/
158 <http://www.haskell.org/ghc/docs/papers/concurrent-haskell.ps.gz>.
159
160 Concurrency is \"lightweight\", which means that both thread creation
161 and context switching overheads are extremely low. Scheduling of
162 Haskell threads is done internally in the Haskell runtime system, and
163 doesn't make use of any operating system-supplied thread packages.
164
165 However, if you want to interact with a foreign library that expects your
166 program to use the operating system-supplied thread package, you can do so
167 by using 'forkOS' instead of 'forkIO'.
168
169 Haskell threads can communicate via 'MVar's, a kind of synchronised
170 mutable variable (see "Control.Concurrent.MVar"). Several common
171 concurrency abstractions can be built from 'MVar's, and these are
172 provided by the "Control.Concurrent" library.
173 In GHC, threads may also communicate via exceptions.
174 -}
175
176 {- $conc_scheduling
177
178 Scheduling may be either pre-emptive or co-operative,
179 depending on the implementation of Concurrent Haskell (see below
180 for information related to specific compilers). In a co-operative
181 system, context switches only occur when you use one of the
182 primitives defined in this module. This means that programs such
183 as:
184
185
186 > main = forkIO (write 'a') >> write 'b'
187 > where write c = putChar c >> write c
188
189 will print either @aaaaaaaaaaaaaa...@ or @bbbbbbbbbbbb...@,
190 instead of some random interleaving of @a@s and @b@s. In
191 practice, cooperative multitasking is sufficient for writing
192 simple graphical user interfaces.
193 -}
194
195 {- $blocking
196 Different Haskell implementations have different characteristics with
197 regard to which operations block /all/ threads.
198
199 Using GHC without the @-threaded@ option, all foreign calls will block
200 all other Haskell threads in the system, although I\/O operations will
201 not. With the @-threaded@ option, only foreign calls with the @unsafe@
202 attribute will block all other threads.
203
204 Using Hugs, all I\/O operations and foreign calls will block all other
205 Haskell threads.
206 -}
207
208 -- | fork a thread and call the supplied function when the thread is about
209 -- to terminate, with an exception or a returned value. The function is
210 -- called with asynchronous exceptions masked.
211 --
212 -- > forkFinally action and_then =
213 -- > mask $ \restore ->
214 -- > forkIO $ try (restore action) >>= and_then
215 --
216 -- This function is useful for informing the parent when a child
217 -- terminates, for example.
218 --
219 forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId
220 forkFinally action and_then =
221 mask $ \restore ->
222 forkIO $ try (restore action) >>= and_then
223
224 #ifdef __GLASGOW_HASKELL__
225 -- ---------------------------------------------------------------------------
226 -- Bound Threads
227
228 {- $boundthreads
229 #boundthreads#
230
231 Support for multiple operating system threads and bound threads as described
232 below is currently only available in the GHC runtime system if you use the
233 /-threaded/ option when linking.
234
235 Other Haskell systems do not currently support multiple operating system threads.
236
237 A bound thread is a haskell thread that is /bound/ to an operating system
238 thread. While the bound thread is still scheduled by the Haskell run-time
239 system, the operating system thread takes care of all the foreign calls made
240 by the bound thread.
241
242 To a foreign library, the bound thread will look exactly like an ordinary
243 operating system thread created using OS functions like @pthread_create@
244 or @CreateThread@.
245
246 Bound threads can be created using the 'forkOS' function below. All foreign
247 exported functions are run in a bound thread (bound to the OS thread that
248 called the function). Also, the @main@ action of every Haskell program is
249 run in a bound thread.
250
251 Why do we need this? Because if a foreign library is called from a thread
252 created using 'forkIO', it won't have access to any /thread-local state/ -
253 state variables that have specific values for each OS thread
254 (see POSIX's @pthread_key_create@ or Win32's @TlsAlloc@). Therefore, some
255 libraries (OpenGL, for example) will not work from a thread created using
256 'forkIO'. They work fine in threads created using 'forkOS' or when called
257 from @main@ or from a @foreign export@.
258
259 In terms of performance, 'forkOS' (aka bound) threads are much more
260 expensive than 'forkIO' (aka unbound) threads, because a 'forkOS'
261 thread is tied to a particular OS thread, whereas a 'forkIO' thread
262 can be run by any OS thread. Context-switching between a 'forkOS'
263 thread and a 'forkIO' thread is many times more expensive than between
264 two 'forkIO' threads.
265
266 Note in particular that the main program thread (the thread running
267 @Main.main@) is always a bound thread, so for good concurrency
268 performance you should ensure that the main thread is not doing
269 repeated communication with other threads in the system. Typically
270 this means forking subthreads to do the work using 'forkIO', and
271 waiting for the results in the main thread.
272
273 -}
274
275 -- | 'True' if bound threads are supported.
276 -- If @rtsSupportsBoundThreads@ is 'False', 'isCurrentThreadBound'
277 -- will always return 'False' and both 'forkOS' and 'runInBoundThread' will
278 -- fail.
279 foreign import ccall rtsSupportsBoundThreads :: Bool
280
281
282 {- |
283 Like 'forkIO', this sparks off a new thread to run the 'IO'
284 computation passed as the first argument, and returns the 'ThreadId'
285 of the newly created thread.
286
287 However, 'forkOS' creates a /bound/ thread, which is necessary if you
288 need to call foreign (non-Haskell) libraries that make use of
289 thread-local state, such as OpenGL (see "Control.Concurrent#boundthreads").
290
291 Using 'forkOS' instead of 'forkIO' makes no difference at all to the
292 scheduling behaviour of the Haskell runtime system. It is a common
293 misconception that you need to use 'forkOS' instead of 'forkIO' to
294 avoid blocking all the Haskell threads when making a foreign call;
295 this isn't the case. To allow foreign calls to be made without
296 blocking all the Haskell threads (with GHC), it is only necessary to
297 use the @-threaded@ option when linking your program, and to make sure
298 the foreign import is not marked @unsafe@.
299 -}
300
301 forkOS :: IO () -> IO ThreadId
302
303 foreign export ccall forkOS_entry
304 :: StablePtr (IO ()) -> IO ()
305
306 foreign import ccall "forkOS_entry" forkOS_entry_reimported
307 :: StablePtr (IO ()) -> IO ()
308
309 forkOS_entry :: StablePtr (IO ()) -> IO ()
310 forkOS_entry stableAction = do
311 action <- deRefStablePtr stableAction
312 action
313
314 foreign import ccall forkOS_createThread
315 :: StablePtr (IO ()) -> IO CInt
316
317 failNonThreaded :: IO a
318 failNonThreaded = fail $ "RTS doesn't support multiple OS threads "
319 ++"(use ghc -threaded when linking)"
320
321 forkOS action0
322 | rtsSupportsBoundThreads = do
323 mv <- newEmptyMVar
324 b <- Exception.getMaskingState
325 let
326 -- async exceptions are masked in the child if they are masked
327 -- in the parent, as for forkIO (see #1048). forkOS_createThread
328 -- creates a thread with exceptions masked by default.
329 action1 = case b of
330 Unmasked -> unsafeUnmask action0
331 MaskedInterruptible -> action0
332 MaskedUninterruptible -> uninterruptibleMask_ action0
333
334 action_plus = Exception.catch action1 childHandler
335
336 entry <- newStablePtr (myThreadId >>= putMVar mv >> action_plus)
337 err <- forkOS_createThread entry
338 when (err /= 0) $ fail "Cannot create OS thread."
339 tid <- takeMVar mv
340 freeStablePtr entry
341 return tid
342 | otherwise = failNonThreaded
343
344 -- | Returns 'True' if the calling thread is /bound/, that is, if it is
345 -- safe to use foreign libraries that rely on thread-local state from the
346 -- calling thread.
347 isCurrentThreadBound :: IO Bool
348 isCurrentThreadBound = IO $ \ s# ->
349 case isCurrentThreadBound# s# of
350 (# s2#, flg #) -> (# s2#, not (flg ==# 0#) #)
351
352
353 {- |
354 Run the 'IO' computation passed as the first argument. If the calling thread
355 is not /bound/, a bound thread is created temporarily. @runInBoundThread@
356 doesn't finish until the 'IO' computation finishes.
357
358 You can wrap a series of foreign function calls that rely on thread-local state
359 with @runInBoundThread@ so that you can use them without knowing whether the
360 current thread is /bound/.
361 -}
362 runInBoundThread :: IO a -> IO a
363
364 runInBoundThread action
365 | rtsSupportsBoundThreads = do
366 bound <- isCurrentThreadBound
367 if bound
368 then action
369 else do
370 ref <- newIORef undefined
371 let action_plus = Exception.try action >>= writeIORef ref
372 bracket (newStablePtr action_plus)
373 freeStablePtr
374 (\cEntry -> forkOS_entry_reimported cEntry >> readIORef ref) >>=
375 unsafeResult
376 | otherwise = failNonThreaded
377
378 {- |
379 Run the 'IO' computation passed as the first argument. If the calling thread
380 is /bound/, an unbound thread is created temporarily using 'forkIO'.
381 @runInBoundThread@ doesn't finish until the 'IO' computation finishes.
382
383 Use this function /only/ in the rare case that you have actually observed a
384 performance loss due to the use of bound threads. A program that
385 doesn't need it's main thread to be bound and makes /heavy/ use of concurrency
386 (e.g. a web server), might want to wrap it's @main@ action in
387 @runInUnboundThread@.
388
389 Note that exceptions which are thrown to the current thread are thrown in turn
390 to the thread that is executing the given computation. This ensures there's
391 always a way of killing the forked thread.
392 -}
393 runInUnboundThread :: IO a -> IO a
394
395 runInUnboundThread action = do
396 bound <- isCurrentThreadBound
397 if bound
398 then do
399 mv <- newEmptyMVar
400 mask $ \restore -> do
401 tid <- forkIO $ Exception.try (restore action) >>= putMVar mv
402 let wait = takeMVar mv `Exception.catch` \(e :: SomeException) ->
403 Exception.throwTo tid e >> wait
404 wait >>= unsafeResult
405 else action
406
407 unsafeResult :: Either SomeException a -> IO a
408 unsafeResult = either Exception.throwIO return
409 #endif /* __GLASGOW_HASKELL__ */
410
411 #ifdef __GLASGOW_HASKELL__
412 -- ---------------------------------------------------------------------------
413 -- threadWaitRead/threadWaitWrite
414
415 -- | Block the current thread until data is available to read on the
416 -- given file descriptor (GHC only).
417 --
418 -- This will throw an 'IOError' if the file descriptor was closed
419 -- while this thread was blocked. To safely close a file descriptor
420 -- that has been used with 'threadWaitRead', use
421 -- 'GHC.Conc.closeFdWith'.
422 threadWaitRead :: Fd -> IO ()
423 threadWaitRead fd
424 #ifdef mingw32_HOST_OS
425 -- we have no IO manager implementing threadWaitRead on Windows.
426 -- fdReady does the right thing, but we have to call it in a
427 -- separate thread, otherwise threadWaitRead won't be interruptible,
428 -- and this only works with -threaded.
429 | threaded = withThread (waitFd fd 0)
430 | otherwise = case fd of
431 0 -> do _ <- hWaitForInput stdin (-1)
432 return ()
433 -- hWaitForInput does work properly, but we can only
434 -- do this for stdin since we know its FD.
435 _ -> error "threadWaitRead requires -threaded on Windows, or use System.IO.hWaitForInput"
436 #else
437 = GHC.Conc.threadWaitRead fd
438 #endif
439
440 -- | Block the current thread until data can be written to the
441 -- given file descriptor (GHC only).
442 --
443 -- This will throw an 'IOError' if the file descriptor was closed
444 -- while this thread was blocked. To safely close a file descriptor
445 -- that has been used with 'threadWaitWrite', use
446 -- 'GHC.Conc.closeFdWith'.
447 threadWaitWrite :: Fd -> IO ()
448 threadWaitWrite fd
449 #ifdef mingw32_HOST_OS
450 | threaded = withThread (waitFd fd 1)
451 | otherwise = error "threadWaitWrite requires -threaded on Windows"
452 #else
453 = GHC.Conc.threadWaitWrite fd
454 #endif
455
456 -- | Returns an STM action that can be used to wait for data
457 -- to read from a file descriptor. The second returned value
458 -- is an IO action that can be used to deregister interest
459 -- in the file descriptor.
460 threadWaitReadSTM :: Fd -> IO (STM (), IO ())
461 threadWaitReadSTM fd
462 #ifdef mingw32_HOST_OS
463 | threaded = do v <- newTVarIO Nothing
464 mask_ $ void $ forkIO $ do result <- try (waitFd fd 0)
465 atomically (writeTVar v $ Just result)
466 let waitAction = do result <- readTVar v
467 case result of
468 Nothing -> retry
469 Just (Right ()) -> return ()
470 Just (Left e) -> throwSTM (e :: IOException)
471 let killAction = return ()
472 return (waitAction, killAction)
473 | otherwise = error "threadWaitReadSTM requires -threaded on Windows"
474 #else
475 = GHC.Conc.threadWaitReadSTM fd
476 #endif
477
478 -- | Returns an STM action that can be used to wait until data
479 -- can be written to a file descriptor. The second returned value
480 -- is an IO action that can be used to deregister interest
481 -- in the file descriptor.
482 threadWaitWriteSTM :: Fd -> IO (STM (), IO ())
483 threadWaitWriteSTM fd
484 #ifdef mingw32_HOST_OS
485 | threaded = do v <- newTVarIO Nothing
486 mask_ $ void $ forkIO $ do result <- try (waitFd fd 1)
487 atomically (writeTVar v $ Just result)
488 let waitAction = do result <- readTVar v
489 case result of
490 Nothing -> retry
491 Just (Right ()) -> return ()
492 Just (Left e) -> throwSTM (e :: IOException)
493 let killAction = return ()
494 return (waitAction, killAction)
495 | otherwise = error "threadWaitWriteSTM requires -threaded on Windows"
496 #else
497 = GHC.Conc.threadWaitWriteSTM fd
498 #endif
499
500 #ifdef mingw32_HOST_OS
501 foreign import ccall unsafe "rtsSupportsBoundThreads" threaded :: Bool
502
503 withThread :: IO a -> IO a
504 withThread io = do
505 m <- newEmptyMVar
506 _ <- mask_ $ forkIO $ try io >>= putMVar m
507 x <- takeMVar m
508 case x of
509 Right a -> return a
510 Left e -> throwIO (e :: IOException)
511
512 waitFd :: Fd -> CInt -> IO ()
513 waitFd fd write = do
514 throwErrnoIfMinus1_ "fdReady" $
515 fdReady (fromIntegral fd) write iNFINITE 0
516
517 iNFINITE :: CInt
518 iNFINITE = 0xFFFFFFFF -- urgh
519
520 foreign import ccall safe "fdReady"
521 fdReady :: CInt -> CInt -> CInt -> CInt -> IO CInt
522 #endif
523
524 -- ---------------------------------------------------------------------------
525 -- More docs
526
527 {- $osthreads
528
529 #osthreads# In GHC, threads created by 'forkIO' are lightweight threads, and
530 are managed entirely by the GHC runtime. Typically Haskell
531 threads are an order of magnitude or two more efficient (in
532 terms of both time and space) than operating system threads.
533
534 The downside of having lightweight threads is that only one can
535 run at a time, so if one thread blocks in a foreign call, for
536 example, the other threads cannot continue. The GHC runtime
537 works around this by making use of full OS threads where
538 necessary. When the program is built with the @-threaded@
539 option (to link against the multithreaded version of the
540 runtime), a thread making a @safe@ foreign call will not block
541 the other threads in the system; another OS thread will take
542 over running Haskell threads until the original call returns.
543 The runtime maintains a pool of these /worker/ threads so that
544 multiple Haskell threads can be involved in external calls
545 simultaneously.
546
547 The "System.IO" library manages multiplexing in its own way. On
548 Windows systems it uses @safe@ foreign calls to ensure that
549 threads doing I\/O operations don't block the whole runtime,
550 whereas on Unix systems all the currently blocked I\/O requests
551 are managed by a single thread (the /IO manager thread/) using
552 a mechanism such as @epoll@ or @kqueue@, depending on what is
553 provided by the host operating system.
554
555 The runtime will run a Haskell thread using any of the available
556 worker OS threads. If you need control over which particular OS
557 thread is used to run a given Haskell thread, perhaps because
558 you need to call a foreign library that uses OS-thread-local
559 state, then you need bound threads (see "Control.Concurrent#boundthreads").
560
561 If you don't use the @-threaded@ option, then the runtime does
562 not make use of multiple OS threads. Foreign calls will block
563 all other running Haskell threads until the call returns. The
564 "System.IO" library still does multiplexing, so there can be multiple
565 threads doing I\/O, and this is handled internally by the runtime using
566 @select@.
567 -}
568
569 {- $termination
570
571 In a standalone GHC program, only the main thread is
572 required to terminate in order for the process to terminate.
573 Thus all other forked threads will simply terminate at the same
574 time as the main thread (the terminology for this kind of
575 behaviour is \"daemonic threads\").
576
577 If you want the program to wait for child threads to
578 finish before exiting, you need to program this yourself. A
579 simple mechanism is to have each child thread write to an
580 'MVar' when it completes, and have the main
581 thread wait on all the 'MVar's before
582 exiting:
583
584 > myForkIO :: IO () -> IO (MVar ())
585 > myForkIO io = do
586 > mvar <- newEmptyMVar
587 > forkFinally io (\_ -> putMVar mvar ())
588 > return mvar
589
590 Note that we use 'forkFinally' to make sure that the
591 'MVar' is written to even if the thread dies or
592 is killed for some reason.
593
594 A better method is to keep a global list of all child
595 threads which we should wait for at the end of the program:
596
597 > children :: MVar [MVar ()]
598 > children = unsafePerformIO (newMVar [])
599 >
600 > waitForChildren :: IO ()
601 > waitForChildren = do
602 > cs <- takeMVar children
603 > case cs of
604 > [] -> return ()
605 > m:ms -> do
606 > putMVar children ms
607 > takeMVar m
608 > waitForChildren
609 >
610 > forkChild :: IO () -> IO ThreadId
611 > forkChild io = do
612 > mvar <- newEmptyMVar
613 > childs <- takeMVar children
614 > putMVar children (mvar:childs)
615 > forkFinally io (\_ -> putMVar mvar ())
616 >
617 > main =
618 > later waitForChildren $
619 > ...
620
621 The main thread principle also applies to calls to Haskell from
622 outside, using @foreign export@. When the @foreign export@ed
623 function is invoked, it starts a new main thread, and it returns
624 when this main thread terminates. If the call causes new
625 threads to be forked, they may remain in the system after the
626 @foreign export@ed function has returned.
627 -}
628
629 {- $preemption
630
631 GHC implements pre-emptive multitasking: the execution of
632 threads are interleaved in a random fashion. More specifically,
633 a thread may be pre-empted whenever it allocates some memory,
634 which unfortunately means that tight loops which do no
635 allocation tend to lock out other threads (this only seems to
636 happen with pathological benchmark-style code, however).
637
638 The rescheduling timer runs on a 20ms granularity by
639 default, but this may be altered using the
640 @-i\<n\>@ RTS option. After a rescheduling
641 \"tick\" the running thread is pre-empted as soon as
642 possible.
643
644 One final note: the
645 @aaaa@ @bbbb@ example may not
646 work too well on GHC (see Scheduling, above), due
647 to the locking on a 'System.IO.Handle'. Only one thread
648 may hold the lock on a 'System.IO.Handle' at any one
649 time, so if a reschedule happens while a thread is holding the
650 lock, the other thread won't be able to run. The upshot is that
651 the switch from @aaaa@ to
652 @bbbbb@ happens infrequently. It can be
653 improved by lowering the reschedule tick period. We also have a
654 patch that causes a reschedule whenever a thread waiting on a
655 lock is woken up, but haven't found it to be useful for anything
656 other than this example :-)
657 -}
658
659 {- $deadlock
660
661 GHC attempts to detect when threads are deadlocked using the garbage
662 collector. A thread that is not reachable (cannot be found by
663 following pointers from live objects) must be deadlocked, and in this
664 case the thread is sent an exception. The exception is either
665 'BlockedIndefinitelyOnMVar', 'BlockedIndefinitelyOnSTM',
666 'NonTermination', or 'Deadlock', depending on the way in which the
667 thread is deadlocked.
668
669 Note that this feature is intended for debugging, and should not be
670 relied on for the correct operation of your program. There is no
671 guarantee that the garbage collector will be accurate enough to detect
672 your deadlock, and no guarantee that the garbage collector will run in
673 a timely enough manner. Basically, the same caveats as for finalizers
674 apply to deadlock detection.
675
676 There is a subtle interaction between deadlock detection and
677 finalizers (as created by 'Foreign.Concurrent.newForeignPtr' or the
678 functions in "System.Mem.Weak"): if a thread is blocked waiting for a
679 finalizer to run, then the thread will be considered deadlocked and
680 sent an exception. So preferably don't do this, but if you have no
681 alternative then it is possible to prevent the thread from being
682 considered deadlocked by making a 'StablePtr' pointing to it. Don't
683 forget to release the 'StablePtr' later with 'freeStablePtr'.
684 -}
685
686 #endif /* __GLASGOW_HASKELL__ */