@@ -19,9 +19,15 @@
19-- Streaming and concurrency together enable expressing reactive applications
19-- Streaming and concurrency together enable expressing reactive applications
20-- conveniently. See 'Streamly.Examples' for a simple SDL based FRP example.
20-- conveniently. See 'Streamly.Examples' for a simple SDL based FRP example.
22+-- Streamly streams are very much like the Haskell lists and most of the
23+-- functions that work on lists have a counterpart that works on streams.
24+-- However, streamly streams can be generated, consumed or combined
22−-- In this tutorial we will go over the basic concepts and how to use the
25+-- concurrently. In this tutorial we will go over the basic concepts and how to
26+-- use the library. The documentation of @Streamly@ module has more details on
27+-- core APIs. For more APIs for constructing, folding, filtering, mapping and
28+-- zipping etc. see the documentation of @Streamly.Prelude@ module. For
23−-- library. For examples and other ways to use the library see
29+-- examples and other ways to use the library see the module
24−-- the module @Streamly.Examples@ as well.
30+-- @Streamly.Examples@ as well.
26module Streamly.Tutorial
32module Streamly.Tutorial
@@ -34,28 +40,28 @@ module Streamly.Tutorial
34 -- ** Eliminating Streams
40 -- ** Eliminating Streams
35 -- $eliminating
41 -- $eliminating
37− -- * Folding Streams
43+ -- * Combining Streams
38− -- $folding
44+ -- $combining
40− -- * Semigroup Style Composition
46+ -- ** Semigroup Style
41 -- $semigroup
47 -- $semigroup
43− -- ** Serial composition ('<>')
49+ -- *** Serial composition ('<>')
44 -- $serial
50 -- $serial
46− -- ** Async composition ('<|')
52+ -- *** Async composition ('<|')
47 -- $parallel
53 -- $parallel
49− -- ** Interleaved composition ('<=>')
55+ -- *** Interleaved composition ('<=>')
50 -- $interleaved
56 -- $interleaved
52− -- ** Parallel composition ('<|>')
58+ -- *** Fair Concurrent composition ('<|>')
53 -- $fairParallel
59 -- $fairParallel
55− -- ** Custom composition
61+ -- *** Custom composition
56 -- $custom
62 -- $custom
58− -- * Monoid Style composition
64+ -- ** Monoid Style
59 -- $monoid
65 -- $monoid
61 -- * Transforming Streams
67 -- * Transforming Streams
@@ -64,16 +70,16 @@ module Streamly.Tutorial
64 -- ** Monad
70 -- ** Monad
67− -- *** Serial Iterations ('StreamT')
73+ -- *** Serial Composition ('StreamT')
68 -- $regularSerial
74 -- $regularSerial
70− -- *** Concurrent Iterations ('AsyncT')
76+ -- *** Async Composition ('AsyncT')
71 -- $concurrentNesting
77 -- $concurrentNesting
73− -- *** Interleaved Iterations ('InterleavedT')
79+ -- *** Interleaved Composition ('InterleavedT')
74 -- $interleavedNesting
80 -- $interleavedNesting
76− -- *** Fairly Concurrent Iterations ('ParallelT')
82+ -- *** Fair Concurrent Composition ('ParallelT')
77 -- $fairlyConcurrentNesting
83 -- $fairlyConcurrentNesting
79 -- *** Exercise
85 -- *** Exercise
@@ -85,9 +91,6 @@ module Streamly.Tutorial
85 -- ** Functor
91 -- ** Functor
86 -- $functor
92 -- $functor
88− -- * Summary of Compositions
89− -- $compositionSummary
91 -- * Zipping Streams
94 -- * Zipping Streams
92 -- $zipping
95 -- $zipping
@@ -97,6 +100,9 @@ module Streamly.Tutorial
97 -- ** Parallel Zipping
100 -- ** Parallel Zipping
98 -- $parallelzip
101 -- $parallelzip
103+ -- * Summary of Compositions
104+ -- $compositionSummary
100 -- * Concurrent Programming Examples
106 -- * Concurrent Programming Examples
101 -- $concurrent
107 -- $concurrent
@@ -153,6 +159,9 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
154-- return 1 <> return 2 <> return 3 :: StreamT IO Int
160-- return 1 <> return 2 <> return 3 :: StreamT IO Int
163+-- For more ways to construct or generate a stream see the module
164+-- @Streamly.Prelude@.
157-- $eliminating
166-- $eliminating
@@ -181,7 +190,8 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
181-- print xs
190-- print xs
184−-- For other ways to eliminate a stream see the module @Streamly.Prelude@.
193+-- For other ways to eliminate or fold a stream see the module
194+-- @Streamly.Prelude@.
186-- $semigroup
196-- $semigroup
187-- Streams of the same type can be combined into a composite stream in many
197-- Streams of the same type can be combined into a composite stream in many
@@ -577,20 +587,29 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
578-- $functor
588-- $functor
580−-- The simplest transformation on a stream is mapping a function on
590+-- 'fmap' transforms a stream by mapping a function on all elements of the
581−-- all elements of the stream using 'fmap'.
591+-- stream. The functor instance of each stream type defines 'fmap' to be
592+-- precisely the same as 'liftM', and therefore 'fmap' is always serial
593+-- irrespective of the type. For concurrent mapping, alternative versions of
594+-- 'fmap', namely, 'asyncMap' and 'parMap' are provided.
584-- import Streamly
597-- import Streamly
586-- main = (toList $ serially $ fmap show $ each [1..10]) >>= print
599-- main = (toList $ serially $ fmap show $ each [1..10]) >>= print
602+-- Also see the 'mapM' and 'sequence' functions for mapping actions, in the
603+-- @Streamly.Prelude@ module.
589-- $applicative
605-- $applicative
591−-- Applicative is a special case of monad and behaves just like the monadic
607+-- Applicative is precisely the same as the 'ap' operation of 'Monad'. For
608+-- zipping and parallel applicatives separate types 'ZipStream' and 'ZipAsync'
592−-- composition. The following example runs all iterations serially and takes a
611+-- The following example runs all iterations serially and takes a total 17
593−-- total 17 seconds (1 + 3 + 4 + 2 + 3 + 4):
612+-- seconds (1 + 3 + 4 + 2 + 3 + 4):
596-- import Streamly
615-- import Streamly
@@ -661,9 +680,6 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
661-- [(1,3),(2,3),(1,4),(2,4)]
680-- [(1,3),(2,3),(1,4),(2,4)]
667-- $compositionSummary
683-- $compositionSummary
669-- The following table summarizes the types for monadic compositions and the
685-- The following table summarizes the types for monadic compositions and the
@@ -690,11 +706,12 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
690-- streams are combined together using a zip function producing a new
706-- streams are combined together using a zip function producing a new
691-- stream of outputs. Two different types are provided for serial and
707-- stream of outputs. Two different types are provided for serial and
692-- concurrent zipping. These types provide an applicative instance that zips
708-- concurrent zipping. These types provide an applicative instance that zips
693−-- the argument streams.
709+-- the argument streams. Also see the zipping function in the @Streamly.Prelude@
695-- $serialzip
712-- $serialzip
697−-- 'StreamZip' zips streams serially:
714+-- 'ZipStream' zips streams serially:
700-- import Streamly
717-- import Streamly
@@ -721,7 +738,7 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
722-- $parallelzip
739-- $parallelzip
724−-- 'AsyncZip' zips streams concurrently:
741+-- 'ZipAsync' zips streams concurrently:
727-- import Streamly
744-- import Streamly
@@ -764,7 +781,7 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
764-- import Data.List (sum)
781-- import Data.List (sum)
766-- main = do
783-- main = do
767−-- squares \<- toList $ serially $ foldMapWith (<|) (\x -\> return $ x * x) [1..100]
784+-- squares \<- toList $ serially $ forEachWith (<|) [1..100] $ \\x -\> return $ x * x
768-- print $ sum squares
785-- print $ sum squares
@@ -779,8 +796,8 @@ import Control.Monad.Trans.Class (MonadTrans (lift))
780-- main = do
797-- main = do
781-- z \<- toList $ asyncly $ do
798-- z \<- toList $ asyncly $ do
782−-- xsq \<- foldMapWith (\<|) (\\x -> return $ x * x) [1..100]
799+-- xsq \<- forEachWith (\<|) [1..100] $ \\x -> return $ x * x
783−-- ysq \<- foldMapWith (\<|) (\\x -> return $ x * x) [1..100]
800+-- ysq \<- forEachWith (\<|) [1..100] $ \\x -> return $ x * x
784-- return $ sqrt (xsq + ysq)
801-- return $ sqrt (xsq + ysq)
785-- print $ sum z
802-- print $ sum z