diff --git a/src/Control/Concurrent/Chan/Unagi.hs b/src/Control/Concurrent/Chan/Unagi.hs --- a/src/Control/Concurrent/Chan/Unagi.hs +++ b/src/Control/Concurrent/Chan/Unagi.hs @@ -38,8 +38,8 @@ newChan = newChanStarting (maxBound - 10) -- lets us test counter overflow in tests and normal course of operation --- | Return a lazy list representing the contents of the supplied OutChan, much --- like System.IO.hGetContents. +-- | Return a lazy infinite list representing the contents of the supplied +-- OutChan, much like System.IO.hGetContents. getChanContents :: OutChan a -> IO [a] getChanContents ch = unsafeInterleaveIO (do x <- unsafeInterleaveIO $ readChan ch diff --git a/src/Control/Concurrent/Chan/Unagi/Bounded.hs b/src/Control/Concurrent/Chan/Unagi/Bounded.hs --- a/src/Control/Concurrent/Chan/Unagi/Bounded.hs +++ b/src/Control/Concurrent/Chan/Unagi/Bounded.hs @@ -48,8 +48,8 @@ newChan size = newChanStarting (maxBound - 10) size -- lets us test counter overflow in tests and normal course of operation --- | Return a lazy list representing the contents of the supplied OutChan, much --- like System.IO.hGetContents. +-- | Return a lazy infinite list representing the contents of the supplied +-- OutChan, much like System.IO.hGetContents. getChanContents :: OutChan a -> IO [a] getChanContents ch = unsafeInterleaveIO (do x <- unsafeInterleaveIO $ readChan ch diff --git a/src/Control/Concurrent/Chan/Unagi/Bounded/Internal.hs b/src/Control/Concurrent/Chan/Unagi/Bounded/Internal.hs --- a/src/Control/Concurrent/Chan/Unagi/Bounded/Internal.hs +++ b/src/Control/Concurrent/Chan/Unagi/Bounded/Internal.hs @@ -302,6 +302,8 @@ -- -- - a blocking @IO@ action that returns the element when it becomes available. -- +-- /Note/: This is a destructive operation. See 'UT.Element' for more details. +-- -- /Note re. exceptions/: When an async exception is raised during a @tryReadChan@ -- the message that the read would have returned is likely to be lost, just as -- it would be when raised directly after this function returns. diff --git a/src/Control/Concurrent/Chan/Unagi/Internal.hs b/src/Control/Concurrent/Chan/Unagi/Internal.hs --- a/src/Control/Concurrent/Chan/Unagi/Internal.hs +++ b/src/Control/Concurrent/Chan/Unagi/Internal.hs @@ -211,6 +211,8 @@ -- -- - a blocking @IO@ action that returns the element when it becomes available. -- +-- /Note/: This is a destructive operation. See 'UT.Element' for more details. +-- -- If you're using this function exclusively you might find the implementation -- in "Control.Concurrent.Chan.Unagi.NoBlocking" is faster. -- diff --git a/src/Control/Concurrent/Chan/Unagi/NoBlocking/Internal.hs b/src/Control/Concurrent/Chan/Unagi/NoBlocking/Internal.hs --- a/src/Control/Concurrent/Chan/Unagi/NoBlocking/Internal.hs +++ b/src/Control/Concurrent/Chan/Unagi/NoBlocking/Internal.hs @@ -142,6 +142,8 @@ -- | Returns immediately with an @'UT.Element' a@ future, which returns one -- unique element when it becomes available via 'UT.tryRead'. -- +-- /Note/: This is a destructive operation. See 'UT.Element' for more details. +-- -- /Note re. exceptions/: When an async exception is raised during a @tryReadChan@ -- the message that the read would have returned is likely to be lost, just as -- it would be when raised directly after this function returns. diff --git a/src/Control/Concurrent/Chan/Unagi/NoBlocking/Types.hs b/src/Control/Concurrent/Chan/Unagi/NoBlocking/Types.hs --- a/src/Control/Concurrent/Chan/Unagi/NoBlocking/Types.hs +++ b/src/Control/Concurrent/Chan/Unagi/NoBlocking/Types.hs @@ -1,3 +1,4 @@ +{-# LANGUAGE CPP #-} module Control.Concurrent.Chan.Unagi.NoBlocking.Types where import Control.Applicative @@ -5,6 +6,9 @@ import Control.Monad import Data.Maybe +#if __GLASGOW_HASKELL__ >= 800 +import Control.Monad.Fail +#endif -- Mostly here to avoid unfortunate name clash with our internal Stream type @@ -26,6 +30,17 @@ -- item. The value returned by @tryRead@ moves monotonically from @Nothing@ -- to @Just a@ when and if an element becomes available, and is idempotent at -- that point. +-- +-- So for instance: +-- +-- @ +-- (in, out) <- newChan +-- (el, _) <- tryReadChan out -- READ FROM EMPTY CHAN +-- writeChan in "msg1" +-- writeChan in "msg2" +-- readChan out -- RETURNS "msg2" +-- tryRead el -- RETURNS "msg1" (which would otherwise be lost) +-- @ newtype Element a = Element { tryRead :: IO (Maybe a) } -- Instances cribbed from MaybeT, from transformers v0.4.2.0 @@ -41,13 +56,16 @@ (<|>) = mplus instance Monad Element where - fail _ = Element (return Nothing) return = Element . return . return x >>= f = Element $ do v <- tryRead x case v of Nothing -> return Nothing Just y -> tryRead (f y) +#if __GLASGOW_HASKELL__ >= 800 +instance MonadFail Element where +#endif + fail _ = Element (return Nothing) instance MonadPlus Element where mzero = Element (return Nothing) diff --git a/src/Control/Concurrent/Chan/Unagi/NoBlocking/Unboxed/Internal.hs b/src/Control/Concurrent/Chan/Unagi/NoBlocking/Unboxed/Internal.hs --- a/src/Control/Concurrent/Chan/Unagi/NoBlocking/Unboxed/Internal.hs +++ b/src/Control/Concurrent/Chan/Unagi/NoBlocking/Unboxed/Internal.hs @@ -178,6 +178,8 @@ -- | Returns immediately with an @'UT.Element' a@ future, which returns one -- unique element when it becomes available via 'UT.tryRead'. -- +-- /Note/: This is a destructive operation. See 'UT.Element' for more details. +-- -- /Note re. exceptions/: When an async exception is raised during a @tryReadChan@ -- the message that the read would have returned is likely to be lost, just as -- it would be when raised directly after this function returns. diff --git a/src/Control/Concurrent/Chan/Unagi/Unboxed.hs b/src/Control/Concurrent/Chan/Unagi/Unboxed.hs --- a/src/Control/Concurrent/Chan/Unagi/Unboxed.hs +++ b/src/Control/Concurrent/Chan/Unagi/Unboxed.hs @@ -39,8 +39,8 @@ newChan = newChanStarting (maxBound - 10) -- lets us test counter overflow in tests and normal course of operation --- | Return a lazy list representing the contents of the supplied OutChan, much --- like System.IO.hGetContents. +-- | Return a lazy infinite list representing the contents of the supplied +-- OutChan, much like System.IO.hGetContents. getChanContents :: UnagiPrim a=> OutChan a -> IO [a] getChanContents ch = unsafeInterleaveIO (do x <- unsafeInterleaveIO $ readChan ch diff --git a/src/Control/Concurrent/Chan/Unagi/Unboxed/Internal.hs b/src/Control/Concurrent/Chan/Unagi/Unboxed/Internal.hs --- a/src/Control/Concurrent/Chan/Unagi/Unboxed/Internal.hs +++ b/src/Control/Concurrent/Chan/Unagi/Unboxed/Internal.hs @@ -340,11 +340,6 @@ --- TODO we might want also a blocking `IO a` returned here, or use an opaque --- Element type supporting blocking, since otherwise calling `tryReadChan` we --- give up the ability to block on that element. Please open an issue if you --- need this in the meantime. And also handling of lost elements on async --- exceptions. And also isActive... -- | Returns immediately with: -- @@ -352,6 +347,8 @@ -- becomes available via 'UT.tryRead'. -- -- - a blocking @IO@ action that returns the element when it becomes available. +-- +-- /Note/: This is a destructive operation. See 'UT.Element' for more details. -- -- If you're using this function exclusively you might find the implementation -- in "Control.Concurrent.Chan.Unagi.NoBlocking.Unboxed" is faster. diff --git a/unagi-chan.cabal b/unagi-chan.cabal --- a/unagi-chan.cabal +++ b/unagi-chan.cabal @@ -1,5 +1,5 @@ name: unagi-chan -version: 0.4.1.2 +version: 0.4.1.3 synopsis: Fast concurrent queues with a Chan-like API, and more @@ -54,7 +54,7 @@ --extra-doc-files: images/*.png --cabal-version: >=1.18 extra-source-files: CHANGELOG.markdown -Tested-With: GHC ==7.8.4 || ==7.10.3 || ==8.0.2 || ==8.2.2 || ==8.4.4 || ==8.6.4 +Tested-With: GHC ==7.8.4 || ==7.10.3 || ==8.0.2 || ==8.2.2 || ==8.4.4 || ==8.6.4 || ==8.8.1 source-repository head type: git