diff --git a/BoundedChan.cabal b/BoundedChan.cabal --- a/BoundedChan.cabal +++ b/BoundedChan.cabal @@ -1,20 +1,26 @@ -name: BoundedChan -category: Concurrency -version: 1.0.0.0 -license: BSD3 -author: Adam Wick -maintainer: Adam Wick -stability: stable -build-type: Simple +name: BoundedChan +category: Concurrency +version: 1.0.0.1 +license: BSD3 +license-file: LICENSE +author: Adam Wick +maintainer: Adam Wick +stability: stable +build-type: Simple cabal-version: >= 1.6 -tested-with: GHC ==6.10 -synopsis: Implementation of bounded Chans. -description: This library introduces BoundedChan. BoundedChan works exactly - like Chan -- and, indeed, has the exact same interface -- but - is guaranteed to operate in a bounded amount of space. +tested-with: GHC == 6.10 +synopsis: Implementation of bounded channels. +description: This library introduces BoundedChan. BoundedChans differ from + Chans in that they are guaranteed to contain no more than a + certain number of elements. -Library +library build-depends: base >= 3, array exposed-modules: Control.Concurrent.BoundedChan - GHC-Options: -O2 -Wall -funbox-strict-fields + ghc-options: -O2 -Wall -funbox-strict-fields -fno-cse + if impl(ghc >= 6.8) + ghc-options: -fwarn-tabs +source-repository head + type: git + location: git://code.haskell.org/BoundedChan.git diff --git a/Control/Concurrent/BoundedChan.hs b/Control/Concurrent/BoundedChan.hs --- a/Control/Concurrent/BoundedChan.hs +++ b/Control/Concurrent/BoundedChan.hs @@ -1,12 +1,10 @@ --- |Implements bounded channels. In these channels, you can give a --- rough maximum number of elements, and you will be guaranteed that no more --- than that number of elements will be pending within the channel. --- --- This boundedness is ideal when you will be (or may be) writing to a channel --- faster than you are able to read from it. +-- |Implements bounded channels. These channels differ from normal 'Chan's in +-- that they are guaranteed to contain no more than a certain number of +-- elements. This is ideal when you may be writing to a channel faster than you +-- are able to read from it. -- --- This module supports all the functions of Control.Concurrent.Chan except --- unGetChan and dupChan, which are not supported for bounded channels. +-- This module supports all the functions of "Control.Concurrent.Chan" except +-- 'unGetChan' and 'dupChan', which are not supported for bounded channels. module Control.Concurrent.BoundedChan( BoundedChan , newBoundedChan @@ -18,12 +16,13 @@ ) where -import Control.Concurrent.MVar -import Control.Monad(replicateM) -import Data.Array -import System.IO.Unsafe(unsafeInterleaveIO) +import Control.Concurrent.MVar (MVar, isEmptyMVar, newEmptyMVar, newMVar, + putMVar, takeMVar) +import Control.Monad (replicateM) +import Data.Array (Array, (!), listArray) +import System.IO.Unsafe (unsafeInterleaveIO) --- |BoundedChan is an abstract data type representing an unbounded channel. +-- |'BoundedChan' is an abstract data type representing a bounded channel. data BoundedChan a = BC { _size :: Int , _contents :: Array Int (MVar a) @@ -32,12 +31,13 @@ } -- LOCK ORDERING: A -> B -> C --- |Create a new bounded chan with size n. +-- |@newBoundedChan n@ returns a channel than can contain no more than @n@ +-- elements. newBoundedChan :: Int -> IO (BoundedChan a) newBoundedChan x = do - entls <- replicateM x newEmptyMVar - wpos <- newMVar 0 - rpos <- newMVar 0 + entls <- replicateM x newEmptyMVar + wpos <- newMVar 0 + rpos <- newMVar 0 let entries = listArray (0, x - 1) entls return (BC x entries wpos rpos) @@ -50,7 +50,7 @@ putMVar wposMV $! (wpos + 1) `mod` size putMVar (contents ! wpos) x --- |Read an element from the channel. If the channel is empty, this routine +-- |Read an element from the channel. If the channel is empty, this routine -- will block until it is able to read. readChan :: BoundedChan a -> IO a readChan (BC size contents _ rposMV) = do @@ -58,20 +58,23 @@ putMVar rposMV $! (rpos + 1) `mod` size takeMVar (contents ! rpos) +-- |Returns 'True' if the supplied channel is empty. isEmptyChan :: BoundedChan a -> IO Bool isEmptyChan (BC _ contents _ rposMV) = do rpos <- takeMVar rposMV - res <- isEmptyMVar (contents ! rpos) + res <- isEmptyMVar (contents ! rpos) putMVar rposMV rpos return res +-- |Return a lazy list representing the contents of the supplied channel. getChanContents :: BoundedChan a -> IO [a] getChanContents ch = unsafeInterleaveIO $ do - x <- readChan ch - xs <- getChanContents ch - return (x:xs) + x <- readChan ch + xs <- getChanContents ch + return (x:xs) +{-# NOINLINE getChanContents #-} --- |Write a list of elements to the channel. Note that this may block as it --- writes the list into the channel. +-- |Write a list of elements to the channel. If the channel becomes full, this +-- routine will block until it is able to write. writeList2Chan :: BoundedChan a -> [a] -> IO () -writeList2Chan ch ls = mapM_ (writeChan ch) ls +writeList2Chan = mapM_ . writeChan diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +Copyright (c) 2009, Galois, Inc. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of the Galois, Inc. nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE.