X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Control%2FConcurrent%2FMVar.hs;h=ef1a2e650b60e3e53202c42e4842cae446c7f3f2;hb=86a17d42a36c3272e993854b9bfa2276ae669324;hp=eb1f03ff2c6a91d388af8d6f6c82099d03de2cb1;hpb=f7a485978f04e84b086f1974b88887cc72d832d0;p=haskell-directory.git

diff --git a/Control/Concurrent/MVar.hs b/Control/Concurrent/MVar.hs
index eb1f03f..ef1a2e6 100644
--- a/Control/Concurrent/MVar.hs
+++ b/Control/Concurrent/MVar.hs
@@ -6,14 +6,16 @@
 -- 
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
--- Portability :  non-portable
+-- 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
@@ -34,7 +36,6 @@ import ConcBase	( MVar, newEmptyMVar, newMVar, takeMVar, putMVar,
 		  tryTakeMVar, tryPutMVar, isEmptyMVar,
                   readMVar, swapMVar,
 		)
-import Prelude hiding( catch )
 #endif
 
 #ifdef __GLASGOW_HASKELL__
@@ -43,6 +44,7 @@ import GHC.Conc	( MVar, newEmptyMVar, newMVar, takeMVar, putMVar,
 		)
 #endif
 
+import Prelude
 import Control.Exception as Exception
 
 #ifdef __HUGS__
@@ -52,6 +54,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
@@ -59,11 +65,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
@@ -73,7 +85,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
@@ -82,7 +98,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