X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Control%2FConcurrent%2FMVar.hs;h=bf9fc5c4400e4b042d1dd9e5cea63c81efc0a265;hb=834f685ecc4d8f12c9fb522f6288757c15469fdc;hp=7832c2eca38172dd683743d6716cd8646cd381a4;hpb=7f1f4e7a695c402ddd3a1dc2cc7114e649a78ebc;p=haskell-directory.git

diff --git a/Control/Concurrent/MVar.hs b/Control/Concurrent/MVar.hs
index 7832c2e..bf9fc5c 100644
--- a/Control/Concurrent/MVar.hs
+++ b/Control/Concurrent/MVar.hs
@@ -1,21 +1,21 @@
 -----------------------------------------------------------------------------
--- 
+-- |
 -- Module      :  Control.Concurrent.MVar
 -- Copyright   :  (c) The University of Glasgow 2001
--- License     :  BSD-style (see the file libraries/core/LICENSE)
+-- License     :  BSD-style (see the file libraries/base/LICENSE)
 -- 
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
--- Portability :  non-portable
---
--- $Id: MVar.hs,v 1.1 2001/06/28 14:15:02 simonmar Exp $
+-- Portability :  non-portable (concurrency)
 --
--- MVars: Synchronising variables
+-- Synchronising variables
 --
 -----------------------------------------------------------------------------
 
 module Control.Concurrent.MVar
-	( MVar		-- abstract
+	( 
+	  -- * @MVar@s
+	  MVar		-- abstract
 	, newEmptyMVar  -- :: IO (MVar a)
 	, newMVar 	-- :: a -> IO (MVar a)
 	, takeMVar 	-- :: MVar a -> IO a
@@ -28,15 +28,17 @@ module Control.Concurrent.MVar
 	, withMVar	-- :: MVar a -> (a -> IO b) -> IO b
 	, modifyMVar_ 	-- :: MVar a -> (a -> IO a) -> IO ()
 	, modifyMVar 	-- :: MVar a -> (a -> IO (a,b)) -> IO b
+#ifndef __HUGS__
 	, addMVarFinalizer -- :: MVar a -> IO () -> IO ()
+#endif
     ) where
 
 #ifdef __HUGS__
-import ConcBase	( MVar, newEmptyMVar, newMVar, takeMVar, putMVar,
+import Hugs.ConcBase ( MVar, newEmptyMVar, newMVar, takeMVar, putMVar,
 		  tryTakeMVar, tryPutMVar, isEmptyMVar,
                   readMVar, swapMVar,
 		)
-import Prelude hiding( catch )
+import Hugs.Exception ( throwIO )
 #endif
 
 #ifdef __GLASGOW_HASKELL__
@@ -45,6 +47,7 @@ import GHC.Conc	( MVar, newEmptyMVar, newMVar, takeMVar, putMVar,
 		)
 #endif
 
+import Prelude
 import Control.Exception as Exception
 
 #ifdef __HUGS__
@@ -54,6 +57,10 @@ throw = throwIO
 #endif
 
 #ifdef __GLASGOW_HASKELL__
+{-|
+  This is a combination of 'takeMVar' and 'putMVar'; ie. it takes the value
+  from the 'MVar', puts it back, and also returns it.
+-}
 readMVar :: MVar a -> IO a
 readMVar m =
   block $ do
@@ -61,11 +68,17 @@ readMVar m =
     putMVar m a
     return a
 
+-- |Swap the contents of an 'MVar' for a new value.
 swapMVar :: MVar a -> a -> IO a
 swapMVar mvar new = modifyMVar mvar (\old -> return (new,old))
 #endif
 
--- put back the same value, return something
+{-|
+  'withMVar' is a safe wrapper for operating on the contents of an
+  'MVar'.  This operation is exception-safe: it will replace the
+  original contents of the 'MVar' if an exception is raised (see
+  "Control.Exception").
+-}
 withMVar :: MVar a -> (a -> IO b) -> IO b
 withMVar m io = 
   block $ do
@@ -75,7 +88,11 @@ withMVar m io =
     putMVar m a
     return b
 
--- put back a new value, return ()
+{-|
+  A safe wrapper for modifying the contents of an 'MVar'.  Like 'withMVar', 
+  'modifyMVar' will replace the original contents of the 'MVar' if an
+  exception is raised during the operation.
+-}
 modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
 modifyMVar_ m io = 
   block $ do
@@ -84,7 +101,10 @@ modifyMVar_ m io =
       	    (\e -> do putMVar m a; throw e)
     putMVar m a'
 
--- put back a new value, return something
+{-|
+  A slight variation on 'modifyMVar_' that allows a value to be
+  returned (@b@) in addition to the modified value of the 'MVar'.
+-}
 modifyMVar :: MVar a -> (a -> IO (a,b)) -> IO b
 modifyMVar m io = 
   block $ do