[project @ 2004-12-14 12:52:03 by simonmar]

[ghc-base.git] / Control / Concurrent / QSemN.hs

diff --git a/Control/Concurrent/QSemN.hs b/Control/Concurrent/QSemN.hs
index 9ba46a2..56c5e50 100644 (file)
--- a/Control/Concurrent/QSemN.hs
+++ b/Control/Concurrent/QSemN.hs
@@ -6,14 +6,16 @@
 -- 
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
--- Portability :  non-portable
+-- Portability :  non-portable (concurrency)
 --
--- Quantity semaphores
+-- Quantity semaphores in which each thread may wait for an arbitrary
+-- \"amount\".
 --
 -----------------------------------------------------------------------------
 
 module Control.Concurrent.QSemN
-       ( QSemN,        -- abstract
+       (  -- * General Quantity Semaphores
+         QSemN,        -- abstract
          newQSemN,     -- :: Int   -> IO QSemN
          waitQSemN,    -- :: QSemN -> Int -> IO ()
          signalQSemN   -- :: QSemN -> Int -> IO ()
@@ -22,26 +24,36 @@ module Control.Concurrent.QSemN
 import Prelude
 
 import Control.Concurrent.MVar
+import Data.Typeable
 
+#include "Typeable.h"
+
+-- |A 'QSemN' is a quantity semaphore, in which the available
+-- \"quantity\" may be signalled or waited for in arbitrary amounts.
 newtype QSemN = QSemN (MVar (Int,[(Int,MVar ())]))
 
+INSTANCE_TYPEABLE0(QSemN,qSemNTc,"QSemN")
+
+-- |Build a new 'QSemN' with a supplied initial quantity.
 newQSemN :: Int -> IO QSemN 
 newQSemN init = do
    sem <- newMVar (init,[])
    return (QSemN sem)
 
+-- |Wait for the specified quantity to become available
 waitQSemN :: QSemN -> Int -> IO ()
 waitQSemN (QSemN sem) sz = do
   (avail,blocked) <- takeMVar sem   -- gain ex. access
   if (avail - sz) >= 0 then
        -- discharging 'sz' still leaves the semaphore
        -- in an 'unblocked' state.
-     putMVar sem (avail-sz,[])
+     putMVar sem (avail-sz,blocked)
    else do
      block <- newEmptyMVar
      putMVar sem (avail, blocked++[(sz,block)])
      takeMVar block
 
+-- |Signal that a given quantity is now available from the 'QSemN'.
 signalQSemN :: QSemN -> Int  -> IO ()
 signalQSemN (QSemN sem) n = do
    (avail,blocked)   <- takeMVar sem