c3a5ef2 · streamly · git.iko.soy

git.iko.soy/streamly

make docs of unfoldrM and iterateM more precise

And improve the "writing concurrent programs" section in tutorial

commitc3a5ef2826f21472edfa034c50190de57d6bbfeb authorHarendra Kumar <harendra.kumar@gmail.com> dateSun 27 May 2018, 18:56 (8 years ago) parent6692959

2 files changed+26−14

compare with master

unifiedsplit

src/Streamly/Prelude.hs+10−3 src/Streamly/Tutorial.hs+16−11

src/Streamly/Prelude.hs+10−3

@@ -191,8 +191,10 @@ unfoldr step = fromStream . go

191191-- 2

192192-- 3

193193-- @

194−-- When run concurrently, the next unfold can run concurrently while previously

195−-- generated value is being processed by the next stream stage.

194+-- When run concurrently, the next unfold step can run concurrently with the

195+-- processing of the output of the previous step. Note that more than one step

196+-- cannot run concurrently as the next step depends on the output of the

197+-- previous step.

196198--

197199-- @

198200-- (asyncly $ S.unfoldrM (\\n -> liftIO (threadDelay 1000000) >> return (Just (n, n + 1))) 0)

@@ -296,6 +298,11 @@ iterate step = fromStream . go

296298-- | Iterate a monadic function from a seed value, streaming the results

297299-- forever.

298300--

301+-- When run concurrently, the next iteration can run concurrently with the

302+-- processing of the previous iteration. Note that more than one iteration

303+-- cannot run concurrently as the next iteration depends on the output of the

304+-- previous iteration.

305+--

299306-- @

300307-- runStream $ serially $ S.take 10 $ S.iterateM

301308-- (\\x -> threadDelay 1000000 >> print x >> return (x + 1)) 0

@@ -304,7 +311,7 @@ iterate step = fromStream . go

304311-- (\\x -> threadDelay 1000000 >> print x >> return (x + 1)) 0

305312-- @

306313--

307−-- /Concurrent, infinite (do not use with 'parallely')/

314+-- /Concurrent/

308315--

309316-- @since 0.1.2

310317iterateM :: (IsStream t, MonadAsync m) => (a -> m a) -> a -> t m a

src/Streamly/Tutorial.hs+16−11

@@ -40,9 +40,6 @@ module Streamly.Tutorial

4040 -- * Flavors of Streams

4141 -- $flavors

4242

43− -- * Writing Concurrent Programs

44− -- $programs

45−

4643 -- * Imports and Supporting Code

4744 -- $imports

4845

@@ -129,6 +126,9 @@ module Streamly.Tutorial

129126 -- * Reactive Programming

130127 -- $reactive

131128

129+ -- * Writing Concurrent Programs

130+ -- $programs

131+

132132 -- * Performance

133133 -- $performance

134134

@@ -238,14 +238,19 @@ import Control.Monad.Trans.Class (MonadTrans (lift))

238238--

239239-- When writing concurrent programs it is advised to not use the concurrent

240240-- style stream combinators blindly at the top level. That might create too

241−-- much concurrency where it is not even required and therefore degrade

242−-- performance. Please be aware of what all APIs that you have used may become

243−-- concurrent when you use a concurrency combinator. For example if you have a

244−-- 'repeatM' somewhere in your program and you use 'parallely' on top, the

245−-- 'repeatM' becomes fully parallel, resulting into an infinite parallel

246−-- execution . Instead start with a default serial program and add concurrent

247−-- combinators where necessary, and use the 'serially' combinator to suppress

248−-- unnecessary concurrency.

241+-- much concurrency where it is not even required, and can even degrade

242+-- performance in some cases. In some cases it can also lead to surprising

243+-- behavior because of some code that is supposed to be serial becoming

244+-- concurrent. Please be aware that all concurrency capable APIs that you may

245+-- have used under the scope of a concurrent stream combinator will become

246+-- concurrent. For example if you have a 'repeatM' somewhere in your program

247+-- and you use 'parallely' on top, the 'repeatM' becomes fully parallel,

248+-- resulting into an infinite parallel execution . Instead, use the

249+-- /Keep It Serial and Stupid/ principle, start with the default serial

250+-- composition and enable concurrent combinators only when and where necessary.

251+-- When you use a concurrent combinator you can use an explicit 'serially'

252+-- combinator to suppress any unnecessary concurrency under the scope of that

253+-- combinator.

249254

250255-- $monadtransformers

251256--