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