X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=compiler%2FbasicTypes%2FUniqSupply.lhs;h=493bfbe6dba572509c119692d2c51782f114b1a6;hp=e7a2d1e649a4f4eaa19ee0604378fd87c4990aec;hb=edc0bafd3fcd01b85a2e8894e5dfe149eb0e0857;hpb=97ca9e73c862b8d7db581d2f63230c04524c797c

diff --git a/compiler/basicTypes/UniqSupply.lhs b/compiler/basicTypes/UniqSupply.lhs
index e7a2d1e..493bfbe 100644
--- a/compiler/basicTypes/UniqSupply.lhs
+++ b/compiler/basicTypes/UniqSupply.lhs
@@ -4,63 +4,48 @@
 %
 
 \begin{code}
-{-# OPTIONS -w #-}
--- The above warning supression flag is a temporary kludge.
--- While working on this module you are encouraged to remove it and fix
--- any warnings in the module. See
---     http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle#Warnings
--- for details
-
 module UniqSupply (
-
+        -- * Main data type
         UniqSupply, -- Abstractly
 
+        -- ** Operations on supplies
         uniqFromSupply, uniqsFromSupply, -- basic ops
-
-        UniqSM, -- type: unique supply monad
-        initUs, initUs_,
-        lazyThenUs, lazyMapUs,
-        mapAndUnzipM,
-        MonadUnique(..),
+        takeUniqFromSupply,
 
         mkSplitUniqSupply,
         splitUniqSupply, listSplitUniqSupply,
 
-        -- Deprecated:
+        -- * Unique supply monad and its abstraction
+        UniqSM, MonadUnique(..),
+
+        -- ** Operations on the monad
+        initUs, initUs_,
+        lazyThenUs, lazyMapUs,
+
+        -- ** Deprecated operations on 'UniqSM'
         getUniqueUs, getUs, returnUs, thenUs, mapUs
   ) where
 
-#include "HsVersions.h"
-
 import Unique
 import FastTypes
 
 import MonadUtils
 import Control.Monad
-import Control.Monad.Fix
-#if __GLASGOW_HASKELL__ >= 607
-import GHC.IOBase (unsafeDupableInterleaveIO)
-#else
-import System.IO.Unsafe ( unsafeInterleaveIO )
-unsafeDupableInterleaveIO :: IO a -> IO a
-unsafeDupableInterleaveIO = unsafeInterleaveIO
-#endif
+import GHC.IO (unsafeDupableInterleaveIO)
 
 \end{code}
 
-
 %************************************************************************
 %*                                                                      *
 \subsection{Splittable Unique supply: @UniqSupply@}
 %*                                                                      *
 %************************************************************************
 
-A value of type @UniqSupply@ is unique, and it can
-supply {\em one} distinct @Unique@.  Also, from the supply, one can
-also manufacture an arbitrary number of further @UniqueSupplies@,
-which will be distinct from the first and from all others.
-
 \begin{code}
+-- | A value of type 'UniqSupply' is unique, and it can
+-- supply /one/ distinct 'Unique'.  Also, from the supply, one can
+-- also manufacture an arbitrary number of further 'UniqueSupply' values,
+-- which will be distinct from the first and from all others.
 data UniqSupply
   = MkSplitUniqSupply FastInt   -- make the Unique with this
                    UniqSupply UniqSupply
@@ -69,11 +54,21 @@ data UniqSupply
 
 \begin{code}
 mkSplitUniqSupply :: Char -> IO UniqSupply
+-- ^ Create a unique supply out of thin air. The character given must
+-- be distinct from those of all calls to this function in the compiler
+-- for the values generated to be truly unique.
 
 splitUniqSupply :: UniqSupply -> (UniqSupply, UniqSupply)
-listSplitUniqSupply :: UniqSupply -> [UniqSupply] -- Infinite
+-- ^ Build two 'UniqSupply' from a single one, each of which
+-- can supply its own 'Unique'.
+listSplitUniqSupply :: UniqSupply -> [UniqSupply]
+-- ^ Create an infinite list of 'UniqSupply' from a single one
 uniqFromSupply  :: UniqSupply -> Unique
+-- ^ Obtain the 'Unique' from this particular 'UniqSupply'
 uniqsFromSupply :: UniqSupply -> [Unique] -- Infinite
+-- ^ Obtain an infinite list of 'Unique' that can be generated by constant splitting of the supply
+takeUniqFromSupply :: UniqSupply -> (Unique, UniqSupply)
+-- ^ Obtain the 'Unique' from this particular 'UniqSupply', and a new supply
 \end{code}
 
 \begin{code}
@@ -102,6 +97,7 @@ listSplitUniqSupply  (MkSplitUniqSupply _ s1 s2) = s1 : listSplitUniqSupply s2
 \begin{code}
 uniqFromSupply  (MkSplitUniqSupply n _ _)  = mkUniqueGrimily (iBox n)
 uniqsFromSupply (MkSplitUniqSupply n _ s2) = mkUniqueGrimily (iBox n) : uniqsFromSupply s2
+takeUniqFromSupply (MkSplitUniqSupply n s1 _) = (mkUniqueGrimily (iBox n), s1)
 \end{code}
 
 %************************************************************************
@@ -111,6 +107,7 @@ uniqsFromSupply (MkSplitUniqSupply n _ s2) = mkUniqueGrimily (iBox n) : uniqsFro
 %************************************************************************
 
 \begin{code}
+-- | A monad which just gives the ability to obtain 'Unique's
 newtype UniqSM result = USM { unUSM :: UniqSupply -> (result, UniqSupply) }
 
 instance Monad UniqSM where
@@ -128,12 +125,13 @@ instance Applicative UniqSM where
                             (ff, us')  -> case x us' of
                               (xx, us'') -> (ff xx, us'')
 
--- the initUs function also returns the final UniqSupply; initUs_ drops it
-initUs :: UniqSupply -> UniqSM a -> (a,UniqSupply)
+-- | Run the 'UniqSM' action, returning the final 'UniqSupply'
+initUs :: UniqSupply -> UniqSM a -> (a, UniqSupply)
 initUs init_us m = case unUSM m init_us of { (r,us) -> (r,us) }
 
+-- | Run the 'UniqSM' action, discarding the final 'UniqSupply'
 initUs_ :: UniqSupply -> UniqSM a -> a
-initUs_ init_us m = case unUSM m init_us of { (r,us) -> r }
+initUs_ init_us m = case unUSM m init_us of { (r, _) -> r }
 
 {-# INLINE thenUs #-}
 {-# INLINE lazyThenUs #-}
@@ -162,9 +160,6 @@ thenUs_ (USM expr) (USM cont)
 returnUs :: a -> UniqSM a
 returnUs result = USM (\us -> (result, us))
 
-withUs :: (UniqSupply -> (a, UniqSupply)) -> UniqSM a
-withUs f = USM (\us -> f us)    -- Ha ha!
-
 getUs :: UniqSM UniqSupply
 getUs = USM (\us -> splitUniqSupply us)
 
@@ -194,7 +189,7 @@ getUniquesUs = USM (\us -> case splitUniqSupply us of
                            (us1,us2) -> (uniqsFromSupply us1, us2))
 
 mapUs :: (a -> UniqSM b) -> [a] -> UniqSM [b]
-mapUs f []     = returnUs []
+mapUs _ []     = returnUs []
 mapUs f (x:xs)
   = f x         `thenUs` \ r  ->
     mapUs f xs  `thenUs` \ rs ->
@@ -202,12 +197,12 @@ mapUs f (x:xs)
 \end{code}
 
 \begin{code}
-{-# -- SPECIALIZE mapM          :: (a -> UniqSM b) -> [a] -> UniqSM [b] #-}
-{-# -- SPECIALIZE mapAndUnzipM  :: (a -> UniqSM (b,c))   -> [a] -> UniqSM ([b],[c]) #-}
-{-# -- SPECIALIZE mapAndUnzip3M :: (a -> UniqSM (b,c,d)) -> [a] -> UniqSM ([b],[c],[d]) #-}
+-- {-# SPECIALIZE mapM          :: (a -> UniqSM b) -> [a] -> UniqSM [b] #-}
+-- {-# SPECIALIZE mapAndUnzipM  :: (a -> UniqSM (b,c))   -> [a] -> UniqSM ([b],[c]) #-}
+-- {-# SPECIALIZE mapAndUnzip3M :: (a -> UniqSM (b,c,d)) -> [a] -> UniqSM ([b],[c],[d]) #-}
 
 lazyMapUs :: (a -> UniqSM b) -> [a] -> UniqSM [b]
-lazyMapUs f []     = returnUs []
+lazyMapUs _ []     = returnUs []
 lazyMapUs f (x:xs)
   = f x             `lazyThenUs` \ r  ->
     lazyMapUs f xs  `lazyThenUs` \ rs ->