Add min/max handling operations for IntSet/IntMap

[haskell-directory.git] / Control / Concurrent.hs

diff --git a/Control/Concurrent.hs b/Control/Concurrent.hs
index 02f74fb..45d2029 100644 (file)
--- a/Control/Concurrent.hs
+++ b/Control/Concurrent.hs
@@ -77,6 +77,10 @@ module Control.Concurrent (
        -- |This section describes features specific to GHC's
        -- implementation of Concurrent Haskell.
        
        -- |This section describes features specific to GHC's
        -- implementation of Concurrent Haskell.
        

+       -- ** Haskell threads and Operating System threads
+
+       -- $osthreads
+

        -- ** Terminating the program
 
        -- $termination
        -- ** Terminating the program
 
        -- $termination

@@ -92,11 +96,12 @@ import Control.Exception as Exception
 
 #ifdef __GLASGOW_HASKELL__
 import GHC.Conc                ( ThreadId(..), myThreadId, killThread, yield,
 
 #ifdef __GLASGOW_HASKELL__
 import GHC.Conc                ( ThreadId(..), myThreadId, killThread, yield,

-                         threadDelay, threadWaitRead, threadWaitWrite )
+                         threadDelay, threadWaitRead, threadWaitWrite,
+                         forkIO, childHandler )

 import GHC.TopHandler   ( reportStackOverflow, reportError )
 import GHC.IOBase      ( IO(..) )
 import GHC.IOBase      ( unsafeInterleaveIO )
 import GHC.TopHandler   ( reportStackOverflow, reportError )
 import GHC.IOBase      ( IO(..) )
 import GHC.IOBase      ( unsafeInterleaveIO )

-import GHC.IOBase   ( newIORef, readIORef, writeIORef )
+import GHC.IOBase      ( newIORef, readIORef, writeIORef )

 import GHC.Base
 
 import Foreign.StablePtr
 import GHC.Base
 
 import Foreign.StablePtr

@@ -160,79 +165,17 @@ In GHC, threads may also communicate via exceptions.
 -}
 
 {- $blocking
 -}
 
 {- $blocking

-Calling a foreign C procedure (such as @getchar@) that blocks waiting
-for input will block /all/ threads, unless the @threadsafe@ attribute
-is used on the foreign call (and your compiler \/ operating system
-supports it).  GHC's I\/O system uses non-blocking I\/O internally to
-implement thread-friendly I\/O, so calling standard Haskell I\/O
-functions blocks only the thread making the call.
--}
-
--- Thread Ids, specifically the instances of Eq and Ord for these things.
--- The ThreadId type itself is defined in std/PrelConc.lhs.
-
--- Rather than define a new primitve, we use a little helper function
--- cmp_thread in the RTS.
-
-#ifdef __GLASGOW_HASKELL__
-id2TSO :: ThreadId -> ThreadId#
-id2TSO (ThreadId t) = t
-
-foreign import ccall unsafe "cmp_thread" cmp_thread :: ThreadId# -> ThreadId# -> Int
--- Returns -1, 0, 1
-
-cmpThread :: ThreadId -> ThreadId -> Ordering
-cmpThread t1 t2 = 
-   case cmp_thread (id2TSO t1) (id2TSO t2) of
-      -1 -> LT
-      0  -> EQ
-      _  -> GT -- must be 1
-
-instance Eq ThreadId where
-   t1 == t2 = 
-      case t1 `cmpThread` t2 of
-         EQ -> True
-         _  -> False
-
-instance Ord ThreadId where
-   compare = cmpThread
+Different Haskell implementations have different characteristics with
+regard to which operations block /all/ threads.

 
 

-foreign import ccall unsafe "rts_getThreadId" getThreadId :: ThreadId# -> Int
+Using GHC without the @-threaded@ option, all foreign calls will block
+all other Haskell threads in the system, although I\/O operations will
+not.  With the @-threaded@ option, only foreign calls with the @unsafe@
+attribute will block all other threads.

 
 

-instance Show ThreadId where
-   showsPrec d t = 
-       showString "ThreadId " . 
-        showsPrec d (getThreadId (id2TSO t))
-
-{- |
-This 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.
+Using Hugs, all I\/O operations and foreign calls will block all other
+Haskell threads.

 -}
 -}

-forkIO :: IO () -> IO ThreadId
-forkIO action = IO $ \ s -> 
-   case (fork# action_plus s) of (# s1, id #) -> (# s1, ThreadId id #)
- where
-  action_plus = Exception.catch action childHandler
-
-childHandler :: Exception -> IO ()
-childHandler err = Exception.catch (real_handler err) childHandler
-
-real_handler :: Exception -> IO ()
-real_handler ex =
-  case ex of
-       -- ignore thread GC and killThread exceptions:
-       BlockedOnDeadMVar            -> return ()
-       AsyncException ThreadKilled  -> return ()
-
-       -- report all others:
-       AsyncException StackOverflow -> reportStackOverflow False
-       other       -> reportError False other
-
-#endif /* __GLASGOW_HASKELL__ */

 
 #ifndef __HUGS__
 max_buff_size :: Int
 
 #ifndef __HUGS__
 max_buff_size :: Int

@@ -313,6 +256,7 @@ nmergeIO lss
 -- Bound Threads
 
 {- $boundthreads
 -- Bound Threads
 
 {- $boundthreads

+   #boundthreads#

 
 Support for multiple operating system threads and bound threads as described
 below is currently only available in the GHC runtime system if you use the
 
 Support for multiple operating system threads and bound threads as described
 below is currently only available in the GHC runtime system if you use the

@@ -363,6 +307,15 @@ used for any other foreign calls.
 
 This means that you can use all kinds of foreign libraries from this thread 
 (even those that rely on thread-local state), without the limitations of 'forkIO'.
 
 This means that you can use all kinds of foreign libraries from this thread 
 (even those that rely on thread-local state), without the limitations of 'forkIO'.

+
+Just to clarify, 'forkOS' is /only/ necessary if you need to associate
+a Haskell thread with a particular OS thread.  It is not necessary if
+you only need to make non-blocking foreign calls (see
+"Control.Concurrent#osthreads").  Neither is it necessary if you want
+to run threads in parallel on a multiprocessor: threads created with
+'forkIO' will be shared out amongst the running CPUs (using GHC,
+@-threaded@, and the @+RTS -N@ runtime option).
+

 -}
 forkOS :: IO () -> IO ThreadId
 
 -}
 forkOS :: IO () -> IO ThreadId
 

@@ -460,6 +413,47 @@ runInUnboundThread action = do
 -- ---------------------------------------------------------------------------
 -- More docs
 
 -- ---------------------------------------------------------------------------
 -- More docs
 

+{- $osthreads
+
+      #osthreads# In GHC, threads created by 'forkIO' are lightweight threads, and
+      are managed entirely by the GHC runtime.  Typically Haskell
+      threads are an order of magnitude or two more efficient (in
+      terms of both time and space) than operating system threads.
+
+      The downside of having lightweight threads is that only one can
+      run at a time, so if one thread blocks in a foreign call, for
+      example, the other threads cannot continue.  The GHC runtime
+      works around this by making use of full OS threads where
+      necessary.  When the program is built with the @-threaded@
+      option (to link against the multithreaded version of the
+      runtime), a thread making a @safe@ foreign call will not block
+      the other threads in the system; another OS thread will take
+      over running Haskell threads until the original call returns.
+      The runtime maintains a pool of these /worker/ threads so that
+      multiple Haskell threads can be involved in external calls
+      simultaneously.
+
+      The "System.IO" library manages multiplexing in its own way.  On
+      Windows systems it uses @safe@ foreign calls to ensure that
+      threads doing I\/O operations don't block the whole runtime,
+      whereas on Unix systems all the currently blocked I\/O reqwests
+      are managed by a single thread (the /IO manager thread/) using
+      @select@.
+
+      The runtime will run a Haskell thread using any of the available
+      worker OS threads.  If you need control over which particular OS
+      thread is used to run a given Haskell thread, perhaps because
+      you need to call a foreign library that uses OS-thread-local
+      state, then you need bound threads (see "Control.Concurrent#boundthreads").
+
+      If you don't use the @-threaded@ option, then the runtime does
+      not make use of multiple OS threads.  Foreign calls will block
+      all other running Haskell threads until the call returns.  The
+      "System.IO" library still does multiplexing, so there can be multiple
+      threads doing I\/O, and this is handled internally by the runtime using
+      @select@.
+-}
+

 {- $termination
 
       In a standalone GHC program, only the main thread is
 {- $termination
 
       In a standalone GHC program, only the main thread is

@@ -477,8 +471,8 @@ runInUnboundThread action = do
 
 >   myForkIO :: IO () -> IO (MVar ())
 >   myForkIO io = do
 
 >   myForkIO :: IO () -> IO (MVar ())
 >   myForkIO io = do

->     mvar \<- newEmptyMVar
->     forkIO (io \`finally\` putMVar mvar ())
+>     mvar <- newEmptyMVar
+>     forkIO (io `finally` putMVar mvar ())

 >     return mvar
 
       Note that we use 'finally' from the
 >     return mvar
 
       Note that we use 'finally' from the

@@ -489,25 +483,26 @@ runInUnboundThread action = do
       A better method is to keep a global list of all child
       threads which we should wait for at the end of the program:
 
       A better method is to keep a global list of all child
       threads which we should wait for at the end of the program:
 

->     children :: MVar [MVar ()]
->     children = unsafePerformIO (newMVar [])
->     
->     waitForChildren :: IO ()
->     waitForChildren = do
->      (mvar:mvars) \<- takeMVar children
->      putMVar children mvars
->      takeMVar mvar
->      waitForChildren
->     
->     forkChild :: IO () -> IO ()
->     forkChild io = do
->       mvar \<- newEmptyMVar
->       forkIO (p \`finally\` putMVar mvar ())
->       childs \<- takeMVar children
->       putMVar children (mvar:childs)
->     
->     later = flip finally
->     
+>    children :: MVar [MVar ()]
+>    children = unsafePerformIO (newMVar [])
+>    
+>    waitForChildren :: IO ()
+>    waitForChildren = do
+>      cs <- takeMVar children
+>      case cs of
+>        []   -> return ()
+>        m:ms -> do
+>          putMVar children ms
+>          takeMVar m
+>          waitForChildren
+>    
+>    forkChild :: IO () -> IO ()
+>    forkChild io = do
+>       mvar <- newEmptyMVar
+>       childs <- takeMVar children
+>       putMVar children (mvar:childs)
+>       forkIO (io `finally` putMVar mvar ())
+>

 >     main =
 >      later waitForChildren $
 >      ...
 >     main =
 >      later waitForChildren $
 >      ...