From: Simon Marlow <simonmar@microsoft.com>
Date: Wed, 5 Dec 2007 09:14:23 +0000 (+0000)
Subject: docs: describe the changes to forkIO, and document forkOnIO
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=c5065603dd9318ef22c9afe12972ee1f80223138;p=ghc-base.git

docs: describe the changes to forkIO, and document forkOnIO
---

diff --git a/GHC/Conc.lhs b/GHC/Conc.lhs
index 233c1f9..498b928 100644
--- a/GHC/Conc.lhs
+++ b/GHC/Conc.lhs
@@ -186,12 +186,15 @@ instance Ord ThreadId where
    compare = cmpThread
 
 {- |
-This sparks off a new thread to run the 'IO' computation passed as the
+Sparks off a new thread to run the 'IO' computation passed as the
 first argument, and returns the 'ThreadId' of the newly created
 thread.
 
 The new thread will be a lightweight thread; if you want to use a foreign
-library that uses thread-local storage, use 'forkOS' instead.
+library that uses thread-local storage, use 'Control.Concurrent.forkOS' instead.
+
+GHC note: the new thread inherits the /blocked/ state of the parent 
+(see 'Control.Exception.block').
 -}
 forkIO :: IO () -> IO ThreadId
 forkIO action = IO $ \ s -> 
@@ -199,6 +202,19 @@ forkIO action = IO $ \ s ->
  where
   action_plus = catchException action childHandler
 
+{- |
+Like 'forkIO', but lets you specify on which CPU the thread is
+created.  Unlike a `forkIO` thread, a thread created by `forkOnIO`
+will stay on the same CPU for its entire lifetime (`forkIO` threads
+can migrate between CPUs according to the scheduling policy).
+`forkOnIO` is useful for overriding the scheduling policy when you
+know in advance how best to distribute the threads.
+
+The `Int` argument specifies the CPU number; it is interpreted modulo
+'numCapabilities' (note that it actually specifies a capability number
+rather than a CPU number, but to a first approximation the two are
+equivalent).
+-}
 forkOnIO :: Int -> IO () -> IO ThreadId
 forkOnIO (I# cpu) action = IO $ \ s -> 
    case (forkOn# cpu action_plus s) of (# s1, id #) -> (# s1, ThreadId id #)
diff --git a/GHC/Exception.lhs b/GHC/Exception.lhs
index 5cee08f..385483a 100644
--- a/GHC/Exception.lhs
+++ b/GHC/Exception.lhs
@@ -83,11 +83,17 @@ catch m k	=  catchException m handler
 -- | Applying 'block' to a computation will
 -- execute that computation with asynchronous exceptions
 -- /blocked/.  That is, any thread which
--- attempts to raise an exception in the current thread will be
+-- attempts to raise an exception in the current thread with 'Control.Exception.throwTo' will be
 -- blocked until asynchronous exceptions are enabled again.  There\'s
 -- no need to worry about re-enabling asynchronous exceptions; that is
 -- done automatically on exiting the scope of
 -- 'block'.
+--
+-- Threads created by 'Control.Concurrent.forkIO' inherit the blocked
+-- state from the parent; that is, to start a thread in blocked mode,
+-- use @block $ forkIO ...@.  This is particularly useful if you need to
+-- establish an exception handler in the forked thread before any
+-- asynchronous exceptions are received.
 block :: IO a -> IO a
 
 -- | To re-enable asynchronous exceptions inside the scope of