@@ -26,8 +26,9 @@
26-- provided for convenience and for consistency with other pure APIs in the
26-- provided for convenience and for consistency with other pure APIs in the
27-- @base@ package.
27-- @base@ package.
29−-- Functions having a 'MonadAsync' constraint work concurrently when used
29+-- Functions having a 'MonadAsync' constraint work concurrently when used with
30−-- with appropriate stream type combinator.
30+-- appropriate stream type combinator. Please be careful to not use 'parallely'
31+-- with infinite streams.
32-- Deconstruction and folds accept a 'SerialT' type instead of a polymorphic
33-- Deconstruction and folds accept a 'SerialT' type instead of a polymorphic
33-- type to ensure that streams always have a concrete monomorphic type by
34-- type to ensure that streams always have a concrete monomorphic type by
@@ -45,7 +46,7 @@ module Streamly.Prelude
48− -- * General Unfold
49+ -- * Generation by Unfolding
50 , unfoldrM
51 , unfoldrM
@@ -63,7 +64,7 @@ module Streamly.Prelude
63 -- * Deconstruction
64 -- * Deconstruction
66− -- * Folding
67+ -- * Elimination by Folding
67 -- ** General Folds
68 -- ** General Folds
@@ -146,7 +147,21 @@ import Streamly.Streams
146-- Construction
147-- Construction
147------------------------------------------------------------------------------
148------------------------------------------------------------------------------
149−-- | Build a Stream by unfolding pure steps starting from a seed.
150+-- | Build a stream by unfolding a /pure/ step function starting from a seed.
151+-- The step function returns the next element in the stream and the next seed
152+-- value. When it is done it returns 'Nothing' and the stream ends. For
159+-- else Just (b, b + 1)
160+-- in toList $ unfoldr f 0
151-- @since 0.1.0
166-- @since 0.1.0
152{-# INLINE unfoldr #-}
167{-# INLINE unfoldr #-}
@@ -158,9 +173,28 @@ unfoldr step = fromStream . go
158 Nothing -> stp
173 Nothing -> stp
159 Just (a, b) -> yld a (go b)
174 Just (a, b) -> yld a (go b)
161−-- | Build a Stream by unfolding monadic steps starting from a seed.
176+-- | Build a stream by unfolding a /monadic/ step function starting from a
177+-- seed. The step function returns the next element in the stream and the next
178+-- seed value. When it is done it returns 'Nothing' and the stream ends. For
163−-- @since 0.1.0
181+-- @
184+-- then return Nothing
185+-- else print b >> return (Just (b, b + 1))
186+-- in runStream $ unfoldrM f 0
164{-# INLINE unfoldrM #-}
198{-# INLINE unfoldrM #-}
165unfoldrM :: (IsStream t, MonadAsync m) => (b -> m (Maybe (a, b))) -> b -> t m a
199unfoldrM :: (IsStream t, MonadAsync m) => (b -> m (Maybe (a, b))) -> b -> t m a
166unfoldrM step = go
200unfoldrM step = go
@@ -181,6 +215,8 @@ fromFoldable = Prelude.foldr cons nil
182-- | Construct a stream from a 'Foldable' containing monadic actions.
216-- | Construct a stream from a 'Foldable' containing monadic actions.
218+-- /Concurrent (do not use with 'parallely' on infinite containers)/
184-- @since 0.3.0
220-- @since 0.3.0
185{-# INLINE fromFoldableM #-}
221{-# INLINE fromFoldableM #-}
186fromFoldableM :: (IsStream t, MonadAsync m, Foldable f) => f (m a) -> t m a
222fromFoldableM :: (IsStream t, MonadAsync m, Foldable f) => f (m a) -> t m a
@@ -209,6 +245,8 @@ once = fromStream . S.once
210-- | Generate a stream by performing a monadic action @n@ times.
246-- | Generate a stream by performing a monadic action @n@ times.
212-- @since 0.1.1
250-- @since 0.1.1
213replicateM :: (IsStream t, MonadAsync m) => Int -> m a -> t m a
251replicateM :: (IsStream t, MonadAsync m) => Int -> m a -> t m a
214replicateM n m = go n
252replicateM n m = go n
@@ -217,6 +255,8 @@ replicateM n m = go n
218-- | Generate a stream by repeatedly executing a monadic action forever.
256-- | Generate a stream by repeatedly executing a monadic action forever.
258+-- /Concurrent, infinite (do not use with 'parallely')/
220-- @since 0.2.0
260-- @since 0.2.0
221repeatM :: (IsStream t, MonadAsync m) => m a -> t m a
261repeatM :: (IsStream t, MonadAsync m) => m a -> t m a
222repeatM = go
262repeatM = go
@@ -233,6 +273,8 @@ iterate step = fromStream . go
233-- | Iterate a monadic function from a seed value, streaming the results
273-- | Iterate a monadic function from a seed value, streaming the results
234-- forever.
274-- forever.
276+-- /Concurrent, infinite (do not use with 'parallely')/
236-- @since 0.1.2
278-- @since 0.1.2
237iterateM :: (IsStream t, MonadAsync m) => (a -> m a) -> a -> t m a
279iterateM :: (IsStream t, MonadAsync m) => (a -> m a) -> a -> t m a
238iterateM step = go
280iterateM step = go
@@ -657,6 +699,8 @@ maximum m = go Nothing (toStream m)
657-- | Replace each element of the stream with the result of a monadic action
699-- | Replace each element of the stream with the result of a monadic action
658-- applied on the element.
700-- applied on the element.
702+-- /Concurrent (do not use with 'parallely' on infinite streams)/
660-- @since 0.1.0
704-- @since 0.1.0
661{-# INLINE mapM #-}
705{-# INLINE mapM #-}
662mapM :: (IsStream t, MonadAsync m) => (a -> m b) -> t m a -> t m b
706mapM :: (IsStream t, MonadAsync m) => (a -> m b) -> t m a -> t m b
@@ -684,6 +728,8 @@ mapM_ f m = go (toStream m)
684-- | Reduce a stream of monadic actions to a stream of the output of those
728-- | Reduce a stream of monadic actions to a stream of the output of those
685-- actions.
729-- actions.
731+-- /Concurrent (do not use with 'parallely' on infinite streams)/
687-- @since 0.1.0
733-- @since 0.1.0
688sequence :: (IsStream t, MonadAsync m) => t m (m a) -> t m a
734sequence :: (IsStream t, MonadAsync m) => t m (m a) -> t m a
689sequence m = go (toStream m)
735sequence m = go (toStream m)