[commit: base] master: update documentation for getNumCapabilities and setNumCapabilities (7ed7dd8)

[Simon Marlow]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/base

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/7ed7dd84f5e7664d127f329708a230fdabcc2cf8

>---------------------------------------------------------------

commit 7ed7dd84f5e7664d127f329708a230fdabcc2cf8
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Mon Dec 19 14:21:27 2011 +0000

    update documentation for getNumCapabilities and setNumCapabilities

>---------------------------------------------------------------

 GHC/Conc/Sync.lhs |   32 +++++++++++---------------------
 1 files changed, 11 insertions(+), 21 deletions(-)

diff --git a/GHC/Conc/Sync.lhs b/GHC/Conc/Sync.lhs
index dccab3d..aa0ae07 100644
--- a/GHC/Conc/Sync.lhs
+++ b/GHC/Conc/Sync.lhs
@@ -281,21 +281,8 @@ numCapabilities = unsafePerformIO $ getNumCapabilities
 
 {- |
 Returns the number of Haskell threads that can run truly
-simultaneously (on separate physical processors) at any given time.
-The number passed to `forkOn` is interpreted modulo this
-value.
-
-An implementation in which Haskell threads are mapped directly to
-OS threads might return the number of physical processor cores in
-the machine, and 'forkOn' would be implemented using the OS's
-affinity facilities.  An implementation that schedules Haskell
-threads onto a smaller number of OS threads (like GHC) would return
-the number of such OS threads that can be running simultaneously.
-
-GHC notes: this returns the number passed as the argument to the
- at +RTS -N@ flag.  In current implementations, the value is fixed
-when the program starts and never changes, but it is possible that
-in the future the number of capabilities might vary at runtime.
+simultaneously (on separate physical processors) at any given time.  To change
+this value, use 'setNumCapabilities'.
 -}
 getNumCapabilities :: IO Int
 getNumCapabilities = do
@@ -304,12 +291,15 @@ getNumCapabilities = do
 
 {- |
 Set the number of Haskell threads that can run truly simultaneously
-(on separate physical processors) at any given time.
-
-GHC notes: in the current implementation, the value may only be
-/increased/, not decreased, by calling 'setNumCapabilities'.  The
-initial value is given by the @+RTS -N@ flag, and the current value
-may be obtained using 'getNumCapabilities'.
+(on separate physical processors) at any given time.  The number
+passed to `forkOn` is interpreted modulo this value.  The initial
+value is given by the @+RTS -N@ runtime flag.
+
+This is also the number of threads that will participate in parallel
+garbage collection.  It is strongly recommended that the number of
+capabilities is not set larger than the number of physical processor
+cores, and it may often be beneficial to leave one or more cores free
+to avoid contention with other processes in the machine.
 -}
 setNumCapabilities :: Int -> IO ()
 setNumCapabilities i = c_setNumCapabilities (fromIntegral i)