1{-# OPTIONS_GHC -fno-warn-unused-imports #-}
3-- Module : Streamly.Tutorial
4-- Copyright : (c) 2017 Harendra Kumar
7-- Maintainer : harendra.kumar@gmail.com
9-- Streamly is a general computing framework based on streaming IO. The IO
10-- monad and pure lists are a special case of streamly. On one hand, streamly
11-- extends the lists of pure values to lists of monadic actions, on the other
12-- hand it extends the IO monad with concurrent non-determinism. In simple
13-- imperative terms we can say that streamly extends the IO monad with @for@
14-- loops and nested @for@ loops with concurrency support. You can understand
15-- this analogy better once you can go through this tutorial.
17-- Streaming in general enables writing modular, composable and scalable
18-- applications with ease, and concurrency allows you to make them scale and
19-- perform well. Streamly enables writing scalable concurrent applications
20-- without being aware of threads or synchronization. No explicit thread
21-- control is needed, where applicable the concurrency rate is automatically
22-- controlled based on the demand by the consumer. However, combinators can be
23-- used to fine tune the concurrency control.
25-- Streaming and concurrency together enable expressing reactive applications
26-- conveniently. See the @CirclingSquare@ example in the examples directory for
27-- a simple SDL based FRP example. To summarize, streamly provides a unified
28-- computing framework for streaming, non-determinism and functional reactive
29-- programming in an elegant and simple API that is a natural extension of pure
30-- lists to monadic streams.
32-- In this tutorial we will go over the basic concepts and how to
33-- use the library. See the last section for further reading resources.
35module Streamly.Tutorial
40 -- * Concurrent Streams
43 -- * Combining Streams
46 -- * Imports and Supporting Code
49 -- * Generating Streams
52 -- * Generating Streams Concurrently
53 -- $generatingConcurrently
55 -- * Eliminating Streams
58 -- * Concurrent Pipeline Stages
59 -- $concurrentApplication
61 -- * Transforming Streams
64 -- * Mapping Concurrently
65 -- $concurrentTransformation
72 -- *** Deep Serial Composition ('Serial')
75 -- *** Wide Serial Composition ('WSerial')
78 -- *** Deep Ahead Composition ('Ahead')
81 -- *** Deep Asynchronous Composition ('Async')
84 -- *** Wide Asynchronous Composition ('WAsync')
87 -- *** Parallel Asynchronous Composition ('Parallel')
90 -- *** Custom composition
102 -- *** Deep Serial Nesting ('Serial')
105 -- *** Wide Serial Nesting ('WSerial')
106 -- $interleavedNesting
108 -- *** Deep Ahead Nesting ('Ahead')
111 -- *** Deep Asynchronous Nesting ('Async')
112 -- $concurrentNesting
114 -- *** Wide Asynchronous Nesting ('WAsync')
117 -- *** Parallel Asynchronous Nesting ('Parallel')
135 -- ** Parallel Zipping
138 -- * Monad transformers
139 -- $monadtransformers
141 -- * Concurrent Programming
144 -- * Reactive Programming
147 -- * Writing Concurrent Programs
153 -- * Interoperation with Streaming Libraries
156 -- * Comparison with Existing Packages
159 -- * Where to go next?
165import Streamly.Prelude
167import Control.Applicative
169import Control.Monad.IO.Class (MonadIO(..))
170import Control.Monad.Trans.Class (MonadTrans (lift))
174-- The way a list represents a sequence of pure values, a stream represents a
175-- sequence of monadic actions. The monadic stream API offered by Streamly is
176-- very close to the Haskell "Prelude" pure lists' API, it can be considered as a
177-- natural extension of lists to monadic actions. Streamly streams provide
178-- concurrent composition and merging of streams. It can be considered as a
179-- concurrent list transformer. In contrast to the "Prelude" lists, merging or
180-- appending streams of arbitrary length is scalable and inexpensive.
182-- The basic stream type is 'Serial', it represents a sequence of IO actions,
183-- and is a 'Monad'. The 'Serial' monad is almost a drop in replacement for
184-- the 'IO' monad, IO monad is a special case of the 'Serial' monad; IO monad
185-- represents a single IO action whereas the 'Serial' monad represents a series
186-- of IO actions. The only change you need to make to go from 'IO' to 'Serial'
187-- is to use 'runStream' to run the monad and to prefix the IO actions with
188-- either 'yieldM' or 'liftIO'. If you use liftIO you can switch from 'Serial'
189-- to IO monad by simply removing the 'runStream' function; no other changes
190-- are needed unless you have used some stream specific composition or
193-- Similarly, the 'Serial' type is almost a drop in replacement for pure lists,
194-- pure lists are a special case of monadic streams. If you use 'nil' in place
195-- of '[]' and '|:' in place ':' you can replace a list with a 'Serial' stream.
196-- The only difference is that the elements must be monadic type and to operate
197-- on the streams we must use the corresponding functions from
198-- "Streamly.Prelude" instead of using the base "Prelude".
202-- Many stream operations can be done concurrently:
204-- * Streams can be generated concurrently.
206-- * Streams can be merged concurrently.
208-- * Multiple stages in a streaming pipeline can run concurrently.
210-- * Streams can be mapped and zipped concurrently.
212-- * In monadic composition they combine like a list transformer,
213-- providing concurrent non-determinism.
215-- There are three basic concurrent stream styles, 'Ahead', 'Async', and
216-- 'Parallel'. The 'Ahead' style streams are similar to 'Serial' except that
217-- they can speculatively execute multiple stream actions concurrently in
218-- advance. 'Ahead' would return exactly the same stream as 'Serial' except
219-- that it may execute the actions concurrently. The 'Async' style streams,
220-- like 'Ahead', speculatively execute multiple stream actions in advance but
221-- return the results in their finishing order rather than in the stream
222-- traversal order. 'Parallel' is like 'Async' except that it provides
223-- unbounded parallelism instead of controlled parallelism.
225-- For easy reference, we can classify the stream types based on /execution order/,
226-- /consumption order/, and /bounded or unbounded/ concurrency.
227-- Execution could be serial (i.e. synchronous) or asynchronous. In serial
228-- execution we execute the next action in the stream only after the previous
229-- one has finished executing. In asynchronous execution multiple actions in
230-- the stream can be executed asynchronously i.e. the next action can start
231-- executing even before the first one has finished. Consumption order
232-- determines the order in which the outputs generated by the composition are
233-- consumed. Consumption could be serial or asynchronous. In serial
234-- consumption, the outputs are consumed in the traversal order, in
235-- asynchronous consumption the outputs are consumed as they arrive i.e. first
236-- come first serve order.
239-- +------------+--------------+--------------+--------------+
240-- | Type | Execution | Consumption | Concurrency |
241-- +============+==============+==============+==============+
242-- | 'Serial' | Serial | Serial | None |
243-- +------------+--------------+--------------+--------------+
244-- | 'Ahead' | Asynchronous | Serial | bounded |
245-- +------------+--------------+--------------+--------------+
246-- | 'Async' | Asynchronous | Asynchronous | bounded |
247-- +------------+--------------+--------------+--------------+
248-- | 'Parallel' | Asynchronous | Asynchronous | unbounded |
249-- +------------+--------------+--------------+--------------+
252-- All these types can be freely inter-converted using type conversion
253-- combinators or type annotations, without any cost, to achieve the desired
254-- composition style. To force a particular type of composition, we coerce the
255-- stream type using the corresponding type adapting combinator from
256-- 'serially', 'aheadly', 'asyncly', or 'parallely'. The default stream type
257-- is inferred as 'Serial' unless you change it by using one of the combinators
258-- or by using a type annotation.
262-- Streams can be combined using '<>' or 'mappend' to form a
263-- composite. Composite streams can be interpreted in a depth first or
264-- breadth first manner using an appropriate type conversion before
265-- consumption. Deep (e.g. 'Serial') stream type variants traverse a
266-- composite stream in a depth first manner, such that each stream is
267-- traversed fully before traversing the next stream. Wide
268-- (e.g. 'WSerial') stream types traverse it in a breadth first
269-- manner, such that one element from each stream is traversed before
270-- coming back to the first stream again.
272-- Each stream type has a wide traversal variant prefixed by 'W'. The wide
273-- variant differs only in the Semigroup\/Monoid, Applicative\/Monad
274-- compositions of the streams.
275-- The following table summarizes the basic types and the corresponding wide
279-- +------------+-----------+
281-- +============+===========+
282-- | 'Serial' | 'WSerial' |
283-- +------------+-----------+
284-- | 'Ahead' | 'WAhead' |
285-- +------------+-----------+
286-- | 'Async' | 'WAsync' |
287-- +------------+-----------+
290-- Other than these types there are also 'ZipSerial' and 'ZipAsync' types that
291-- zip streams serially or concurrently using 'Applicative' operation. These
292-- types are not monads they are only applicatives and they do not differ in
293-- 'Semigroup' composition.
298-- When writing concurrent programs it is advised to not use the concurrent
299-- style stream combinators blindly at the top level. That might create too
300-- much concurrency where it is not even required, and can even degrade
301-- performance in some cases. In some cases it can also lead to surprising
302-- behavior because of some code that is supposed to be serial becoming
303-- concurrent. Please be aware that all concurrency capable APIs that you may
304-- have used under the scope of a concurrent stream combinator will become
305-- concurrent. For example if you have a 'repeatM' somewhere in your program
306-- and you use 'parallely' on top, the 'repeatM' becomes fully parallel,
307-- resulting into an infinite parallel execution . Instead, use the
308-- /Keep It Serial and Stupid/ principle, start with the default serial
309-- composition and enable concurrent combinators only when and where necessary.
310-- When you use a concurrent combinator you can use an explicit 'serially'
311-- combinator to suppress any unnecessary concurrency under the scope of that
316-- To represent streams in an arbitrary monad use the more general monad
317-- transformer types for example the monad transformer type corresponding to
318-- the 'Serial' type is 'SerialT'. @SerialT m a@ represents a stream of values
319-- of type 'a' in some underlying monad 'm'. For example, @SerialT IO Int@ is a
320-- stream of 'Int' in 'IO' monad. In fact, the type 'Serial' is a synonym for
323-- Similarly we have monad transformer types for other stream types as well viz.
324-- 'WSerialT', 'AsyncT', 'WAsyncT' and 'ParallelT'.
326-- To lift a value from an underlying monad in a monad transformer stack into a
327-- singleton stream use 'lift' and to lift from an IO action use 'liftIO'.
330-- > 'runStream' $ liftIO $ putStrLn "Hello world!"
332-- > 'runStream' $ lift $ putStrLn "Hello world!"
339-- We will assume the following imports in this tutorial. Go ahead, fire up a
340-- GHCi session and import these lines to start playing.
343-- > import "Streamly"
344-- > import "Streamly.Prelude" ((|:))
345-- > import qualified "Streamly.Prelude" as S
348-- 'nil' represents an empty stream and 'consM' or its operator form '|:' adds
349-- a monadic action at the head of the stream.
352-- > S.'toList' S.'nil'
354-- > S.'toList' $ 'getLine' |: 'getLine' |: S.'nil'
360-- To create a singleton stream from a pure value use 'yield' or 'pure' and to
361-- create a singleton stream from a monadic action use 'yieldM'. Note that in
362-- case of Zip applicative streams "pure" repeats the value to generate an
366-- > S.'toList' $ 'pure' 1
368-- > S.'toList' $ 'yield' 1
370-- > S.'toList' $ S.'yieldM' 'getLine'
375-- To create a stream from pure values in a 'Foldable' container use
376-- 'fromFoldable' which is equivalent to a fold using 'cons' and 'nil':
379-- > S.'toList' $ S.'fromFoldable' [1..3]
381-- > S.'toList' $ 'Prelude.foldr' S.'cons' S.'nil' [1..3]
385-- To create a stream from monadic actions in a 'Foldable' container just use a
386-- right fold using 'consM' and 'nil':
389-- > 'runStream' $ 'Prelude.foldr' ('|:') S.'nil' ['putStr' "Hello ", 'putStrLn' "world!"]
393-- For more ways to construct a stream see the module "Streamly.Prelude".
395-- $generatingConcurrently
397-- Monadic construction and generation functions like 'consM', 'unfoldrM',
398-- 'replicateM', 'repeatM', 'iterateM' and 'fromFoldableM' work concurrently
399-- when used with appropriate stream type combinator. The pure versions of
400-- these APIs are not concurrent, however you can use the monadic versions even
401-- for pure computations by wrapping the pure value in a monad to get the
402-- concurrent generation capability where required.
404-- The following code finishes in 3 seconds (6 seconds when serial):
407-- > let p n = threadDelay (n * 1000000) >> return n
408-- > S.'toList' $ 'parallely' $ p 3 |: p 2 |: p 1 |: S.'nil'
410-- > S.'toList' $ 'aheadly' $ p 3 |: p 2 |: p 1 |: S.'nil'
413-- The following finishes in 10 seconds (100 seconds when serial):
416-- > 'runStream' $ 'asyncly' $ S.'replicateM' 10 $ p 10
422-- We have already seen 'runStream' and 'toList' to eliminate a stream in the
423-- examples above. 'runStream' runs a stream discarding the results i.e. only
424-- for effects. 'toList' runs the stream and collects the results in a list.
426-- For other ways to eliminate a stream see the @Folding@ section in
427-- "Streamly.Prelude" module.
431-- Transformation over a stream is the equivalent of a @for@ loop construct in
432-- imperative paradigm. We iterate over every element in the stream and perform
433-- certain transformations for each element. Transformations may involve
434-- mapping functions over the elements, filtering elements from the stream or
435-- folding all the elements in the stream into a single value. Streamly streams
436-- are exactly like lists and you can perform all the transformations in the
437-- same way as you would on lists.
439-- Here is a simple console echo program that just echoes every input line,
443-- > 'runStream' $ S.'repeatM' getLine & S.'mapM' putStrLn
446-- The following code snippet reads lines from standard input, filters blank
447-- lines, drops the first non-blank line, takes the next two, up cases them,
448-- numbers them and prints them:
452-- import qualified "Streamly.Prelude" as S
453-- import Data.Char (toUpper)
454-- import Data.Function ((&))
456-- main = 'runStream' $
457-- S.'repeatM' getLine
458-- & S.'filter' (not . null)
461-- & fmap (map toUpper)
462-- & S.'zipWith' (\\n s -> show n ++ " " ++ s) (S.'fromFoldable' [1..])
463-- & S.'mapM' putStrLn
466-- $concurrentTransformation
468-- Monadic transformation functions 'mapM' and 'sequence' work concurrently
469-- when used with appropriate stream type combinators. The pure versions do not
470-- work concurrently, however you can use the monadic versions even for pure
471-- computations to get the concurrent transformation capability where required.
473-- This would print a value every second (2 seconds when serial):
476-- > let p n = threadDelay (n * 1000000) >> return n
477-- > runStream $ aheadly $ S.'mapM' (\\x -> p 1 >> print x) (serially $ repeatM (p 1))
481-- $concurrentApplication
483-- The concurrent function application operators '|$' and '|&' apply a stream
484-- argument to a stream function concurrently to compose a concurrent pipeline
485-- of stream processing functions:
487-- Because both the stages run concurrently, we would see a delay of only 1
488-- second instead of 2 seconds in the following:
491-- > let p n = threadDelay (n * 1000000) >> return n
492-- > runStream $ S.'repeatM' (p 1) '|&' S.'mapM' (\\x -> p 1 >> print x)
497-- We can combine two streams into a single stream using semigroup composition
498-- operation '<>'. Streams can be combined in many different ways as described
499-- in the following sections, the '<>' operation behaves differently depending
500-- on the stream type in effect. The stream type and therefore the composition
501-- style can be changed at any point using one of the type combinators as
506-- In most of example snippets we do not repeat the imports. Where imports are
507-- not explicitly specified use the imports shown below.
511-- import "Streamly.Prelude" ((|:), nil)
512-- import qualified "Streamly.Prelude" as S
514-- import Control.Concurrent
515-- import Control.Monad (forever)
518-- To illustrate concurrent vs serial composition aspects, we will use the
519-- following @delay@ function to introduce a sleep or delay specified in
520-- seconds. After the delay it prints the number of seconds it slept.
523-- delay n = S.'yieldM' $ do
524-- threadDelay (n * 1000000)
526-- putStrLn (show tid ++ ": Delay " ++ show n)
531-- The 'Semigroup' operation '<>' of the 'Serial' type combines the two streams
532-- in a /serial depth first/ manner. We use the 'serially' type combinator to
533-- effect 'Serial' style of composition. We can also use an explicit 'Serial'
534-- type annotation for the stream to achieve the same effect. However, since
535-- 'Serial' is the default type unless explicitly specified by using a
536-- combinator, we can omit using an explicit combinator or type annotation for
537-- this style of composition.
539-- When two streams with multiple elements are combined in this manner, the
540-- monadic actions in the two streams are performed sequentially i.e. first all
541-- actions in the first stream are performed sequentially and then all actions
542-- in the second stream are performed sequentially. We call it
543-- /serial depth first/ as the full depth of one stream is fully traversed
544-- before we move to the next. The following example prints the sequence 1, 2,
548-- main = 'runStream' $ (print 1 |: print 2 |: nil) <> (print 3 |: print 4 |: nil)
557-- All actions in both the streams are performed serially in the same thread.
558-- In the following example we can see that all actions are performed in the
559-- same thread and take a combined total of @3 + 2 + 1 = 6@ seconds:
562-- main = 'runStream' $ delay 3 <> delay 2 <> delay 1
565-- ThreadId 36: Delay 3
566-- ThreadId 36: Delay 2
567-- ThreadId 36: Delay 1
570-- The polymorphic version of the binary operation '<>' of the 'Serial' type is
571-- 'serial'. We can use 'serial' to join streams in a sequential manner
572-- irrespective of the type of stream:
575-- main = 'runStream' $ (print 1 |: print 2 |: nil) \`serial` (print 3 |: print 4 |: nil)
580-- The 'Semigroup' operation '<>' of the 'WSerial' type combines the two
581-- streams in a /serial breadth first/ manner. We use the 'wSerially' type
582-- combinator to effect 'WSerial' style of composition. We can also use the
583-- 'WSerial' type annotation for the stream to achieve the same effect.
585-- When two streams with multiple elements are combined in this manner, we
586-- traverse all the streams in a breadth first manner i.e. one action from each
587-- stream is performed and yielded to the resulting stream before we come back
588-- to the first stream again and so on.
589-- The following example prints the sequence 1, 3, 2, 4
592-- main = 'runStream' . 'wSerially' $ (print 1 |: print 2 |: nil) <> (print 3 |: print 4 |: nil)
601-- Even though the monadic actions of the two streams are performed in an
602-- interleaved manner they are all performed serially in the same thread. In
603-- the following example we can see that all actions are performed in the same
604-- thread and take a combined total of @3 + 2 + 1 = 6@ seconds:
607-- main = 'runStream' . 'wSerially' $ delay 3 <> delay 2 <> delay 1
610-- ThreadId 36: Delay 3
611-- ThreadId 36: Delay 2
612-- ThreadId 36: Delay 1
615-- The polymorphic version of the 'WSerial' binary operation '<>' is called
616-- 'wSerial'. We can use 'wSerial' to join streams in an interleaved manner
617-- irrespective of the type, notice that we have not used the 'wSerially'
618-- combinator in the following example:
621-- main = 'runStream' $ (print 1 |: print 2 |: nil) \`wSerial` (print 3 |: print 4 |: nil)
630-- Note that this composition cannot be used to fold infinite number of streams
631-- since it requires preserving the state until a stream is finished.
635-- The 'Semigroup' operation '<>' of the 'Ahead' type combines two streams in a
636-- /serial depth first/ manner with concurrent lookahead. We use the 'aheadly'
637-- type combinator to effect 'Ahead' style of composition. We can also use an
638-- explicit 'Ahead' type annotation for the stream to achieve the same effect.
640-- When two streams are combined in this manner, the streams are traversed in
641-- depth first manner just like 'Serial', however it can execute the next
642-- stream concurrently and keep the results ready when its turn arrives.
643-- Concurrent execution of the next stream(s) is performed if the first stream
644-- blocks or if it cannot produce output at the rate that is enough to meet the
645-- consumer demand. Multiple streams can be executed concurrently to meet the
646-- demand. The following example would print the result in a second even
647-- though each action in each stream takes one second:
651-- xs \<- 'toList' . 'aheadly' $ (p 1 |: p 2 |: nil) <> (p 3 |: p 4 |: nil)
653-- where p n = threadDelay 1000000 >> return n
659-- Each stream is constructed 'aheadly' and then both the streams are merged
660-- 'aheadly', therefore, all the actions can run concurrently but the result is
661-- presented in serial order.
663-- You can also use the polymorphic combinator 'ahead' in place of '<>' to
664-- compose any type of streams in this manner.
668-- The 'Semigroup' operation '<>' of the 'Async' type combines the two
669-- streams in a depth first manner with parallel look ahead. We use the
670-- 'asyncly' type combinator to effect 'Async' style of composition. We
671-- can also use the 'Async' type annotation for the stream type to achieve
674-- When two streams with multiple elements are combined in this manner, the
675-- streams are traversed in depth first manner just like 'Serial', however it
676-- can execute the next stream concurrently and return the results from it
677-- as they arrive i.e. the results from the next stream may be yielded even
678-- before the results from the first stream. Concurrent execution of the next
679-- stream(s) is performed if the first stream blocks or if it cannot produce
680-- output at the rate that is enough to meet the consumer demand. Multiple
681-- streams can be executed concurrently to meet the demand.
682-- In the example below each element in the stream introduces a constant delay
683-- of 1 second, however, it takes just one second to produce all the results.
684-- The results are not guaranteed to be in any particular order:
688-- xs \<- 'runStream' . 'asyncly' $ (p 1 |: p 2 |: nil) <> (p 3 |: p 4 |: nil)
690-- where p n = threadDelay 1000000 >> return n
696-- The constituent streams are also composed in 'Async' manner and the
697-- composition of streams too. We can compose the constituent streams to run
698-- serially, in that case it would take 2 seconds to produce all the results.
699-- The elements in the serial streams would be in serial order in the results:
703-- xs \<- 'runStream' . 'asyncly' $ (serially $ p 1 |: p 2 |: nil) <> (serially $ p 3 |: p 4 |: nil)
705-- where p n = threadDelay 1000000 >> return n
711-- In the following example we can see that new threads are started when a
712-- computation blocks. Notice that the output from the stream with the
713-- shortest delay is printed first. The whole computation takes @maximum of
714-- (3, 2, 1) = 3@ seconds:
717-- main = 'runStream' . 'asyncly' $ delay 3 '<>' delay 2 '<>' delay 1
720-- ThreadId 42: Delay 1
721-- ThreadId 41: Delay 2
722-- ThreadId 40: Delay 3
725-- When we have a tree of computations composed using this style, the tree is
726-- traversed in DFS style just like the 'Serial' style, the only difference is
727-- that here we can move on to executing the next stream if a stream blocks.
728-- However, we will not start new threads if we have sufficient output to
729-- saturate the consumer. This is why we call it left-biased demand driven or
730-- adaptive concurrency style, the concurrency tends to stay on the left side
731-- of the composition as long as possible. More threads are started based on
732-- the pull rate of the consumer. The following example prints an output every
733-- second as all of the actions are concurrent.
736-- main = 'runStream' . 'asyncly' $ (delay 1 <> delay 2) <> (delay 3 <> delay 4)
745-- All the computations may even run in a single thread when more threads are
746-- not needed. As you can see, in the following example the computations are
747-- run in a single thread one after another, because none of them blocks.
748-- However, if the thread consuming the stream were faster than the producer
749-- then it would have started parallel threads for each computation to keep up
750-- even if none of them blocks:
753-- main = 'runStream' . 'asyncly' $ traced (sqrt 9) '<>' traced (sqrt 16) '<>' traced (sqrt 25)
754-- where traced m = S.'yieldM' (myThreadId >>= print) >> return m
762-- Note that the order of printing in the above examples may change due to
763-- variations in scheduling latencies for concurrent threads.
765-- The polymorphic version of the 'Async' binary operation '<>' is called
766-- 'async'. We can use 'async' to join streams in a left biased
767-- adaptively concurrent manner irrespective of the type, notice that we have
768-- not used the 'asyncly' combinator in the following example:
771-- main = 'runStream' $ delay 3 \`async` delay 2 \`async` delay 1
774-- ThreadId 42: Delay 1
775-- ThreadId 41: Delay 2
776-- ThreadId 40: Delay 3
779-- Since the concurrency provided by this operator is demand driven it cannot
780-- be used when the composed computations start timers that are relative to
781-- each other because all computations may not be started at the same time and
782-- therefore timers in all of them may not start at the same time. When
783-- relative timing among all computations is important or when we need to start
784-- all computations at once for any reason 'Parallel' style must be used
787-- 'Async' style should be preferred over 'Parallel' or 'WAsync' unless you
788-- really need those. It utilizes the resources optimally. It should be used
789-- when we know that the computations can run in parallel but we do not care if
790-- they actually run in parallel or not, that decision can be left to the
791-- scheduler based on demand. Also, note that this operator can be used to fold
792-- infinite number of streams in contrast to the 'Parallel' or 'WAsync' styles,
793-- because it does not require us to run all of them at the same time in a fair
798-- The 'Semigroup' operation '<>' of the 'WAsync' type combines two streams in
799-- a concurrent manner using /breadth first traversal/. We use the 'wAsyncly'
800-- type combinator to effect 'WAsync' style of composition. We can also use the
801-- 'WAsync' type annotation for the stream to achieve the same effect.
803-- When streams with multiple elements are combined in this manner, we traverse
804-- all the streams concurrently in a breadth first manner i.e. one action from
805-- each stream is performed and yielded to the resulting stream before we come
806-- back to the first stream again and so on. Even though we execute the actions
807-- in a breadth first order the outputs are consumed on a first come first
810-- In the following example we can see that outputs are produced in the breadth
811-- first traversal order but this is not guaranteed.
814-- main = 'runStream' . 'wAsyncly' $ (serially $ print 1 |: print 2 |: nil) <> (serially $ print 3 |: print 4 |: nil)
823-- The polymorphic version of the binary operation '<>' of the 'WAsync' type is
824-- 'wAsync'. We can use 'wAsync' to join streams using a breadth first
825-- concurrent traversal irrespective of the type, notice that we have not used
826-- the 'wAsyncly' combinator in the following example:
829-- main = 'runStream' $ delay 3 \`wAsync` delay 2 \`wAsync` delay 1
832-- ThreadId 42: Delay 1
833-- ThreadId 41: Delay 2
834-- ThreadId 40: Delay 3
837-- Since the concurrency provided by this style is demand driven it may not
838-- be used when the composed computations start timers that are relative to
839-- each other because all computations may not be started at the same time and
840-- therefore timers in all of them may not start at the same time. When
841-- relative timing among all computations is important or when we need to start
842-- all computations at once for any reason 'Parallel' style must be used
848-- The 'Semigroup' operation '<>' of the 'Parallel' type combines the two
849-- streams in a fairly concurrent manner with round robin scheduling. We use
850-- the 'parallely' type combinator to effect 'Parallel' style of composition.
851-- We can also use the 'Parallel' type annotation for the stream type to
852-- achieve the same effect.
854-- When two streams with multiple elements are combined in this manner, the
855-- monadic actions in both the streams are performed concurrently with a fair
856-- round robin scheduling. The outputs are yielded in the order in which the
857-- actions complete. This is pretty similar to the 'WAsync' type, the
858-- difference is that 'WAsync' is adaptive to the consumer demand and may or
859-- may not execute all actions in parallel depending on the demand, whereas
860-- 'Parallel' runs all the streams in parallel irrespective of the demand.
862-- The following example sends a query to all the three search engines in
863-- parallel and prints the name of the search engines in the order in which the
868-- import qualified Streamly.Prelude as S
869-- import Network.HTTP.Simple
871-- main = 'runStream' . 'parallely' $ google \<> bing \<> duckduckgo
873-- google = get "https://www.google.com/search?q=haskell"
874-- bing = get "https://www.bing.com/search?q=haskell"
875-- duckduckgo = get "https://www.duckduckgo.com/?q=haskell"
876-- get s = S.'yieldM' (httpNoBody (parseRequest_ s) >> putStrLn (show s))
879-- The polymorphic version of the binary operation '<>' of the 'Parallel' type
880-- is 'parallel'. We can use 'parallel' to join streams in a fairly concurrent
881-- manner irrespective of the type, notice that we have not used the
882-- 'parallely' combinator in the following example:
885-- main = 'runStream' $ delay 3 \`parallel` delay 2 \`wAsync` delay 1
888-- ThreadId 42: Delay 1
889-- ThreadId 41: Delay 2
890-- ThreadId 40: Delay 3
893-- Note that this style of composition cannot be used to combine infinite
894-- number of streams, as it will lead to an infinite sized scheduling queue.
899-- The 'mkAsync' API can be used to create references to asynchronously running
900-- stream computations. We can then use 'uncons' to explore the streams
901-- arbitrarily and then recompose individual elements to create a new stream.
902-- This way we can dynamically decide which stream to explore at any given
903-- time. Take an example of a merge sort of two sorted streams. We need to
904-- keep consuming items from the stream which has the lowest item in the sort
905-- order. This can be achieved using async references to streams. See
906-- "MergeSort.hs" in the examples directory.
910-- We can use 'Monoid' instances to fold a container of streams in the desired
911-- style using 'fold' or 'foldMap'. We have also provided some fold utilities
912-- to fold streams using the polymorphic combine operations:
914-- * 'foldWith' is like 'fold', it folds a 'Foldable' container of streams
915-- using the given composition operator.
916-- * 'foldMapWith' is like 'foldMap', it folds like @foldWith@ but also maps a
917-- function before folding.
918-- * 'forEachWith' is like @foldMapwith@ but the container argument comes before
919-- the function argument.
921-- All of the following are equivalent and start ten concurrent tasks each with
922-- a delay from 1 to 10 seconds, resulting in the printing of each number every
927-- import qualified "Streamly.Prelude" as S
928-- import Control.Concurrent
931-- 'runStream' $ 'asyncly' $ foldMap delay [1..10]
932-- 'runStream' $ 'foldWith' 'async' (map delay [1..10])
933-- 'runStream' $ 'foldMapWith' 'async' delay [1..10]
934-- 'runStream' $ 'forEachWith' 'async' [1..10] delay
935-- where delay n = S.'yieldM' $ threadDelay (n * 1000000) >> print n
940-- Till now we discussed ways to apply transformations on a stream or to merge
941-- streams together to create another stream. We mentioned earlier that
942-- transforming a stream is similar to a @for@ loop in the imperative paradigm.
943-- We will now discuss the concept of a nested composition of streams which is
944-- analogous to nested @for@ loops in the imperative paradigm. Functional
945-- programmers call this style of composition a list transformer or @ListT@.
946-- Logic programmers call it a logic monad or non-deterministic composition,
947-- but for ordinary imperative minded people like me it is easier to think in
948-- terms of good old nested @for@ loops.
952-- In functional programmer's parlance the 'Monad' instances of different
953-- 'IsStream' types implement non-determinism, exploring all possible
954-- combination of choices from both the streams. From an imperative
955-- programmer's point of view it behaves like nested loops i.e. for each
956-- element in the first stream and for each element in the second stream
957-- execute the body of the loop.
959-- The 'Monad' instances of 'Serial', 'WSerial', 'Async' and 'WAsync'
960-- stream types support different flavors of nested looping. In other words,
961-- they are all variants of list transformer. The nesting behavior of these
962-- types correspond exactly to the way they merge streams as we discussed in
963-- the previous section.
968-- The 'Monad' composition of the 'Serial' type behaves like a standard list
969-- transformer. This is the default when we do not use an explicit type
970-- combinator. However, the 'serially' type combinator can be used to switch to
971-- this style of composition. We will see how this style of composition works
972-- in the following examples.
974-- Let's start with an example with a simple @for@ loop without any nesting.
975-- For simplicity of illustration we are using streams of pure values in all
976-- the examples. However, the streams could also be made of monadic actions
981-- import qualified "Streamly.Prelude" as S
983-- main = 'runStream' $ do
984-- x <- S.'fromFoldable' [3,2,1]
988-- ThreadId 30: Delay 3
989-- ThreadId 30: Delay 2
990-- ThreadId 30: Delay 1
993-- As we can see, the code after the @fromFoldable@ statement is run three
994-- times, once for each value of @x@ drawn from the stream. All the three
995-- iterations are serial and run in the same thread one after another. In
996-- imperative terms this is equivalent to a @for@ loop with three iterations.
998-- A console echo loop copying standard input to standard output can simply be
1003-- import qualified "Streamly.Prelude" as S
1005-- main = 'runStream' $ forever $ S.yieldM getLine >>= S.yieldM . putStrLn
1008-- When multiple streams are composed using this style they nest in a DFS
1009-- manner i.e. nested iterations of a loop are executed before we proceed to
1010-- the next iteration of the parent loop. This behaves just like nested @for@
1011-- loops in imperative programming.
1015-- import qualified "Streamly.Prelude" as S
1017-- main = 'runStream' $ do
1018-- x <- S.'fromFoldable' [1,2]
1019-- y <- S.'fromFoldable' [3,4]
1020-- S.'yieldM' $ putStrLn $ show (x, y)
1029-- Notice that this is analogous to merging streams of type 'Serial' or merging
1030-- streams using 'serial'.
1034-- The 'Monad' composition of 'Ahead' type behaves just like 'Serial' except
1035-- that it can speculatively perform a bounded number of next iterations of a
1036-- loop concurrently.
1038-- The 'aheadly' type combinator can be used to switch to this style of
1039-- composition. Alternatively, a type annotation can be used to specify the
1040-- type of the stream as 'Ahead'.
1044-- import "Streamly.Prelude" as S
1046-- comp = 'toList' . 'aheadly' $ do
1047-- x <- S.'fromFoldable' [3,2,1]
1048-- delay x >> return x
1050-- main = comp >> print
1053-- ThreadId 40: Delay 1
1054-- ThreadId 39: Delay 2
1055-- ThreadId 38: Delay 3
1059-- This code finishes in 3 seconds, 'Serial' would take 6 seconds. As we can
1060-- see all the three iterations are concurrent and run in different threads,
1061-- however, the results are returned in the serial order.
1063-- Concurrency is demand driven, when multiple streams are composed using this
1064-- style, the iterations are executed in a depth first manner just like
1065-- 'Serial' i.e. nested iterations are executed before we proceed to the next
1066-- outer iteration. The only difference is that we may execute multiple future
1067-- iterations concurrently and keep the results ready.
1070-- $concurrentNesting
1072-- The 'Monad' composition of 'Async' type can perform the iterations of a
1073-- loop concurrently. Concurrency is demand driven i.e. more concurrent
1074-- iterations are started only if the previous iterations are not able to
1075-- produce enough output for the consumer of the output stream. This works
1076-- exactly the same way as the merging of two streams 'asyncly' works.
1077-- This is the concurrent analogue of 'Serial' style monadic composition.
1079-- The 'asyncly' type combinator can be used to switch to this style of
1080-- composition. Alternatively, a type annotation can be used to specify the
1081-- type of the stream as 'Async'.
1085-- import "Streamly.Prelude"
1087-- main = 'runStream' . 'asyncly' $ do
1088-- x <- S.'fromFoldable' [3,2,1]
1092-- ThreadId 40: Delay 1
1093-- ThreadId 39: Delay 2
1094-- ThreadId 38: Delay 3
1097-- As we can see the code after the @fromFoldable@ statement is run three
1098-- times, once for each value of @x@. All the three iterations are concurrent
1099-- and run in different threads. The iteration with least delay finishes first.
1100-- When compared to imperative programming, this can be viewed as a @for@ loop
1101-- with three concurrent iterations.
1103-- Concurrency is demand driven just as in the case of 'async' merging.
1104-- When multiple streams are composed using this style, the iterations are
1105-- triggered in a depth first manner just like 'Serial' i.e. nested iterations are
1106-- executed before we proceed to the next iteration at higher level. However,
1107-- unlike 'Serial' more than one iterations may be started concurrently based
1108-- on the demand from the consumer of the stream.
1112-- import qualified "Streamly.Prelude" as S
1114-- main = 'runStream' . 'asyncly' $ do
1115-- x <- S.'fromFoldable' [1,2]
1116-- y <- S.'fromFoldable' [3,4]
1117-- S.'yieldM' $ putStrLn $ show (x, y)
1126-- $interleavedNesting
1128-- The 'Monad' composition of 'WSerial' type interleaves the iterations of
1129-- outer and inner loops in a nested loop composition. This works exactly the
1130-- same way as the merging of two streams in 'wSerially' fashion works. The
1131-- 'wSerially' type combinator can be used to switch to this style of
1132-- composition. Alternatively, a type annotation can be used to specify the
1133-- type of the stream as 'WSerial'.
1137-- import qualified "Streamly.Prelude" as S
1139-- main = 'runStream' . 'wSerially' $ do
1140-- x <- S.'fromFoldable' [1,2]
1141-- y <- S.'fromFoldable' [3,4]
1142-- S.yieldM $ putStrLn $ show (x, y)
1154-- Just like 'Async' the 'Monad' composition of 'WAsync' runs the iterations of
1155-- a loop concurrently. The difference is in the nested loop behavior. The
1156-- nested loops in this type are traversed and executed in a breadth first
1157-- manner rather than the depth first manner of 'Async' style.
1158-- The loop nesting works exactly the same way as the merging of streams
1159-- 'wAsyncly' works. The 'wAsyncly' type combinator can be used to switch to
1160-- this style of composition. Alternatively, a type annotation can be used to
1161-- specify the type of the stream as 'WAsync'.
1165-- import qualified "Streamly.Prelude" as S
1167-- main = 'runStream' . 'wAsyncly' $ do
1168-- x <- S.'fromFoldable' [1,2]
1169-- y <- S.'fromFoldable' [3,4]
1170-- S.'yieldM' $ putStrLn $ show (x, y)
1181-- Just like 'Async' or 'WAsync' the 'Monad' composition of 'Parallel' runs the
1182-- iterations of a loop concurrently. The difference is in the nested loop
1183-- behavior. The streams at each nest level is run fully concurrently
1184-- irrespective of the demand. The loop nesting works exactly the same way as
1185-- the merging of streams 'parallely' works. The 'parallely' type combinator
1186-- can be used to switch to this style of composition. Alternatively, a type
1187-- annotation can be used to specify the type of the stream as 'Parallel'.
1191-- import qualified "Streamly.Prelude" as S
1193-- main = 'runStream' . 'parallely' $ do
1194-- x <- S.'fromFoldable' [3,2,1]
1198-- ThreadId 40: Delay 1
1199-- ThreadId 39: Delay 2
1200-- ThreadId 38: Delay 3
1205-- Streamly code is usually written in a way that is agnostic of the
1206-- specific monadic composition type. We use a polymorphic type with a
1207-- 'IsStream' type class constraint. When running the stream we can choose the
1208-- specific mode of composition. For example take a look at the following code.
1212-- import qualified "Streamly.Prelude" as S
1214-- composed :: (IsStream t, Monad (t IO)) => t IO ()
1219-- S.'yieldM' $ putStrLn $ show (sz, cl, sh)
1223-- sizes = S.'fromFoldable' [1, 2, 3]
1224-- colors = S.'fromFoldable' ["red", "green", "blue"]
1225-- shapes = S.'fromFoldable' ["triangle", "square", "circle"]
1228-- Now we can interpret this in whatever way we want:
1231-- main = 'runStream' . 'serially' $ composed
1232-- main = 'runStream' . 'wSerially' $ composed
1233-- main = 'runStream' . 'asyncly' $ composed
1234-- main = 'runStream' . 'wAsyncly' $ composed
1235-- main = 'runStream' . 'parallely' $ composed
1238-- As an exercise try to figure out the output of this code for each mode of
1243-- 'fmap' transforms a stream by mapping a function on all elements of the
1244-- stream. 'fmap' behaves in the same way for all stream types, it is always
1249-- import qualified "Streamly.Prelude" as S
1251-- main = (S.'toList' $ fmap show $ S.'fromFoldable' [1..10]) >>= print
1254-- Also see the 'mapM' and 'sequence' functions for mapping actions, in the
1255-- "Streamly.Prelude" module.
1259-- Applicative is precisely the same as the 'ap' operation of 'Monad'. For
1260-- zipping applicatives separate types 'ZipSerial' and 'ZipAsync' are
1263-- The following example uses the 'Serial' applicative, it runs all iterations
1264-- serially and takes a total 17 seconds (1 + 3 + 4 + 2 + 3 + 4):
1268-- import qualified "Streamly.Prelude" as S
1269-- import Control.Concurrent
1273-- d n = delay n >> return n
1275-- main = (S.'toList' . 'serially' $ (,) \<$> s1 \<*> s2) >>= print
1278-- ThreadId 36: Delay 1
1279-- ThreadId 36: Delay 3
1280-- ThreadId 36: Delay 4
1281-- ThreadId 36: Delay 2
1282-- ThreadId 36: Delay 3
1283-- ThreadId 36: Delay 4
1284-- [(1,3),(1,4),(2,3),(2,4)]
1287-- Similarly 'WSerial' applicative runs the iterations in an interleaved
1288-- order but since it is serial it takes a total of 17 seconds:
1291-- main = (S.'toList' . 'wSerially' $ (,) \<$> s1 \<*> s2) >>= print
1294-- ThreadId 36: Delay 1
1295-- ThreadId 36: Delay 3
1296-- ThreadId 36: Delay 2
1297-- ThreadId 36: Delay 3
1298-- ThreadId 36: Delay 4
1299-- ThreadId 36: Delay 4
1300-- [(1,3),(2,3),(1,4),(2,4)]
1303-- 'Async' can run the iterations concurrently and therefore takes a total
1304-- of 10 seconds (1 + 2 + 3 + 4):
1307-- main = (S.'toList' . 'asyncly' $ (,) \<$> s1 \<*> s2) >>= print
1310-- ThreadId 34: Delay 1
1311-- ThreadId 36: Delay 2
1312-- ThreadId 35: Delay 3
1313-- ThreadId 36: Delay 3
1314-- ThreadId 35: Delay 4
1315-- ThreadId 36: Delay 4
1316-- [(1,3),(2,3),(1,4),(2,4)]
1319-- Similarly 'WAsync' as well can run the iterations concurrently and
1320-- therefore takes a total of 10 seconds (1 + 2 + 3 + 4):
1323-- main = (S.'toList' . 'wAsyncly' $ (,) \<$> s1 \<*> s2) >>= print
1326-- ThreadId 34: Delay 1
1327-- ThreadId 36: Delay 2
1328-- ThreadId 35: Delay 3
1329-- ThreadId 36: Delay 3
1330-- ThreadId 35: Delay 4
1331-- ThreadId 36: Delay 4
1332-- [(1,3),(2,3),(1,4),(2,4)]
1337-- Zipping is a special transformation where the corresponding elements of two
1338-- streams are combined together using a zip function producing a new stream of
1339-- outputs. Two different types are provided for serial and concurrent zipping.
1340-- These types provide an applicative instance that can be used to lift
1341-- functions to zip the argument streams.
1342-- Also see the zipping functions in the "Streamly.Prelude" module.
1346-- The applicative instance of 'ZipSerial' type zips streams serially.
1347-- 'zipSerially' type combinator can be used to switch to serial applicative
1352-- import qualified "Streamly.Prelude" as S
1353-- import Control.Concurrent
1355-- d n = delay n >> return n
1356-- s1 = 'serially' $ d 1 <> d 2
1357-- s2 = 'serially' $ d 3 <> d 4
1359-- main = (S.'toList' . 'zipSerially' $ (,) \<$> s1 \<*> s2) >>= print
1362-- This takes total 10 seconds to zip, which is (1 + 2 + 3 + 4) since
1363-- everything runs serially:
1366-- ThreadId 29: Delay 1
1367-- ThreadId 29: Delay 3
1368-- ThreadId 29: Delay 2
1369-- ThreadId 29: Delay 4
1375-- The applicative instance of 'ZipAsync' type zips streams concurrently.
1376-- 'zipAsyncly' type combinator can be used to switch to parallel applicative
1382-- import qualified "Streamly.Prelude" as S
1383-- import Control.Concurrent
1384-- import System.IO (stdout, hSetBuffering, BufferMode(LineBuffering))
1386-- d n = delay n >> return n
1387-- s1 = 'serially' $ d 1 <> d 2
1388-- s2 = 'serially' $ d 3 <> d 4
1391-- hSetBuffering stdout LineBuffering
1392-- (S.'toList' . 'zipAsyncly' $ (,) \<$> s1 \<*> s2) >>= print
1395-- This takes 7 seconds to zip, which is max (1,3) + max (2,4) because 1 and 3
1396-- are produced concurrently, and 2 and 4 are produced concurrently:
1399-- ThreadId 32: Delay 1
1400-- ThreadId 32: Delay 2
1401-- ThreadId 33: Delay 3
1402-- ThreadId 33: Delay 4
1408-- When writing concurrent programs there are two distinct places where the
1409-- programmer can control the concurrency. First, when /composing/ a stream by
1410-- merging multiple streams we can choose an appropriate sum style operators to
1411-- combine them concurrently or serially. Second, when /processing/ a stream in
1412-- a monadic composition we can choose one of the monad composition types to
1413-- choose the desired type of concurrency.
1415-- In the following example the squares of @x@ and @y@ are computed
1416-- concurrently using the 'async' operation and the square roots of their
1417-- sum are computed serially because of the 'streamly' combinator. We can
1418-- choose different combinators for the monadic processing and the stream
1419-- generation, to control the concurrency. We can also use the 'asyncly'
1420-- combinator instead of explicitly folding with 'async'.
1424-- import qualified "Streamly.Prelude" as S
1425-- import Data.List (sum)
1429-- $ 'serially' -- Serial monadic processing (sqrt below)
1431-- x2 \<- 'forEachWith' 'async' [1..100] $ -- Concurrent @"for"@ loop
1432-- \\x -> return $ x * x -- body of the loop
1433-- y2 \<- 'forEachWith' 'async' [1..100] $
1434-- \\y -> return $ y * y
1435-- return $ sqrt (x2 + y2)
1439-- We can see how this directly maps to the imperative style
1440-- <https://en.wikipedia.org/wiki/OpenMP OpenMP> model, we use combinators
1441-- and operators instead of the ugly pragmas.
1443-- For more concurrent programming examples see,
1444-- "ListDir.hs", "MergeSort.hs" and "SearchQuery.hs" in the examples directory.
1448-- Reactive programming is nothing but concurrent streaming which is what
1449-- streamly is all about. With streamly we can generate streams of events,
1450-- merge streams that are generated concurrently and process events
1451-- concurrently. We can do all this without any knowledge about the specifics
1452-- of the implementation of concurrency. In the following example you will see
1453-- that the code is just regular Haskell code without much streamly APIs used
1454-- (active hyperlinks are the streamly APIs) and yet it is a reactive
1457-- This application has two independent and concurrent sources of event
1458-- streams, @acidRain@ and @userAction@. @acidRain@ continuously generates
1459-- events that deteriorate the health of the character in the game.
1460-- @userAction@ can be "potion" or "quit". When the user types "potion" the
1461-- health improves and the game continues.
1464-- {-\# LANGUAGE FlexibleContexts #-}
1467-- import Streamly.Prelude as S
1468-- import Control.Monad (when)
1469-- import Control.Monad.IO.Class (MonadIO(..))
1470-- import Control.Monad.State (MonadState, get, modify, runStateT)
1472-- data Event = Harm Int | Heal Int | Quit deriving (Show)
1474-- userAction :: MonadAsync m => 'SerialT' m Event
1475-- userAction = S.repeatM $ liftIO askUser
1478-- command <- getLine
1480-- "potion" -> return (Heal 10)
1481-- "quit" -> return Quit
1482-- _ -> putStrLn "What?" >> askUser
1484-- acidRain :: MonadAsync m => SerialT m Event
1485-- acidRain = asyncly $ constRate 1 $ S.repeatM $ liftIO $ return $ Harm 1
1487-- game :: ('MonadAsync' m, MonadState Int m) => 'SerialT' m ()
1489-- event \<- userAction \`parallel` acidRain
1491-- Harm n -> modify $ \\h -> h - n
1492-- Heal n -> modify $ \\h -> h + n
1493-- Quit -> fail "quit"
1496-- when (h <= 0) $ fail "You die!"
1497-- liftIO $ putStrLn $ "Health = " ++ show h
1500-- putStrLn "Your health is deteriorating due to acid rain,\\
1501-- \\ type \\"potion\\" or \\"quit\\""
1502-- _ <- runStateT ('runStream' game) 60
1506-- You can also find the source of this example in the examples directory as
1507-- "AcidRain.hs". It has been adapted from Gabriel's
1508-- <https://hackage.haskell.org/package/pipes-concurrency-2.0.8/docs/Pipes-Concurrent-Tutorial.html pipes-concurrency>
1510-- This is much simpler compared to the pipes version because of the builtin
1511-- concurrency in streamly. You can also find a SDL based reactive programming
1512-- example adapted from Yampa in "Streamly.Examples.CirclingSquare".
1516-- Streamly is highly optimized for performance, it is designed for serious
1517-- high performing, concurrent and scalable applications. We have created the
1518-- <https://hackage.haskell.org/package/streaming-benchmarks streaming-benchmarks>
1519-- package which is specifically and carefully designed to measure the
1520-- performance of Haskell streaming libraries fairly and squarely in the right
1521-- way. Streamly performs at par or even better than most streaming libraries
1522-- for serial operations even though it needs to deal with the concurrency
1527-- We can use @unfoldr@ and @uncons@ to convert one streaming type to another.
1529-- Interop with @vector@:
1533-- import qualified Streamly.Prelude as S
1534-- import qualified Data.Vector.Fusion.Stream.Monadic as V
1536-- -- | vector to streamly
1537-- fromVector :: (IsStream t, Monad m) => V.Stream m a -> t m a
1538-- fromVector = S.unfoldrM unconsV
1543-- then return Nothing
1546-- return $ Just (h, V.tail v)
1548-- -- | streamly to vector
1549-- toVector :: Monad m => SerialT m a -> V.Stream m a
1550-- toVector = V.unfoldrM (S.uncons . adapt)
1553-- S.toList (fromVector (V.fromList [1..3])) >>= print
1554-- V.toList (toVector (S.fromFoldable [1..3])) >>= print
1557-- Interop with @pipes@:
1561-- import qualified "Streamly.Prelude" as S
1562-- import qualified Pipes as P
1563-- import qualified Pipes.Prelude as P
1565-- -- | pipes to streamly
1566-- fromPipes :: (IsStream t, Monad m) => P.Producer a m r -> t m a
1567-- fromPipes = S.'unfoldrM' unconsP
1569-- -- Adapt P.next to return a Maybe instead of Either
1570-- unconsP p = P.next p >>= either (\\_ -> return Nothing) (return . Just)
1572-- -- | streamly to pipes
1573-- toPipes :: Monad m => SerialT m a -> P.Producer a m ()
1574-- toPipes = P.unfoldr unconsS
1576-- -- Adapt S.uncons to return an Either instead of Maybe
1577-- unconsS s = S.'uncons' s >>= maybe (return $ Left ()) (return . Right)
1580-- S.'toList' (fromPipes (P.each [1..3])) >>= print
1581-- P.toListM (toPipes (S.'fromFoldable' [1..3])) >>= print
1584-- Interop with @streaming@:
1588-- import qualified "Streamly.Prelude" as S
1589-- import qualified Streaming as SG
1590-- import qualified Streaming.Prelude as SG
1592-- -- | streaming to streamly
1593-- fromStreaming :: (IsStream t, Monad m) => SG.Stream (SG.Of a) m r -> t m a
1594-- fromStreaming = S.unfoldrM SG.uncons
1596-- -- | streamly to streaming
1597-- toStreaming :: Monad m => SerialT m a -> SG.Stream (SG.Of a) m ()
1598-- toStreaming = SG.unfoldr unconsS
1600-- -- Adapt S.uncons to return an Either instead of Maybe
1601-- unconsS s = S.'uncons' s >>= maybe (return $ Left ()) (return . Right)
1604-- S.toList (fromStreaming (SG.each [1..3])) >>= print
1605-- SG.toList (toStreaming (S.fromFoldable [1..3])) >>= print
1608-- Interop with @conduit@:
1612-- import qualified "Streamly.Prelude" as S
1613-- import qualified Data.Conduit as C
1614-- import qualified Data.Conduit.List as C
1615-- import qualified Data.Conduit.Combinators as C
1617-- -- It seems there is no way out of a conduit as it does not provide an
1618-- -- uncons or a tail function. We can convert streamly to conduit though.
1620-- -- | streamly to conduit
1621-- toConduit :: Monad m => SerialT m a -> C.ConduitT i a m ()
1622-- toConduit s = C.unfoldM S.'uncons' s
1625-- C.runConduit (toConduit (S.'fromFoldable' [1..3]) C..| C.sinkList) >>= print
1630-- List transformers and logic programming monads also provide a product style
1631-- composition similar to streamly, however streamly generalizes it with the
1632-- time dimension; allowing streams to be composed in an asynchronous and
1633-- concurrent fashion in many different ways. It also provides multiple
1634-- alternative ways of composing streams e.g. serial, interleaved or
1637-- This seemingly simple addition of asynchronicity and concurrency to product
1638-- style streaming composition unifies a number of disparate abstractions into
1639-- one powerful, concise and elegant abstraction. A wide variety of
1640-- programming problems can be solved elegantly with this abstraction. In
1641-- particular, it unifies three major programming domains namely
1642-- non-deterministic (logic) programming, concurrent programming and functional
1643-- reactive programming. In other words, you can do everything with this one
1644-- abstraction that you could do with the popular libraries listed under these
1645-- categories in the list below.
1648-- +-----------------+----------------+
1649-- | Non-determinism | <https://hackage.haskell.org/package/pipes pipes> |
1650-- | +----------------+
1651-- | | <https://hackage.haskell.org/package/list-t list-t> |
1652-- | +----------------+
1653-- | | <https://hackage.haskell.org/package/logict logict> |
1654-- +-----------------+----------------+
1655-- | Streaming | <https://hackage.haskell.org/package/vector vector> |
1656-- | +----------------+
1657-- | | <https://hackage.haskell.org/package/streaming streaming> |
1658-- | +----------------+
1659-- | | <https://hackage.haskell.org/package/pipes pipes> |
1660-- | +----------------+
1661-- | | <https://hackage.haskell.org/package/conduit conduit> |
1662-- +-----------------+----------------+
1663-- | Concurrency | <https://hackage.haskell.org/package/async async> |
1664-- | +----------------+
1665-- | | <https://hackage.haskell.org/package/transient transient> |
1666-- +-----------------+----------------+
1667-- | FRP | <https://hackage.haskell.org/package/Yampa Yampa> |
1668-- | +----------------+
1669-- | | <https://hackage.haskell.org/package/dunai dunai> |
1670-- | +----------------+
1671-- | | <https://hackage.haskell.org/package/reflex reflex> |
1672-- +-----------------+----------------+
1675-- Streamly is a list-transformer. It provides all the functionality provided
1676-- by any of the list transformer and logic programming packages listed above.
1677-- In addition, Streamly naturally integrates the concurrency dimension to the
1678-- basic list transformer functionality.
1680-- When it comes to streaming, in terms of the streaming API streamly is almost
1681-- identical to the vector package. Streamly, vector and streaming packages all
1682-- represent a stream as data and are therefore similar in the fundamental
1683-- approach to streaming. The fundamental difference is that streamly adds
1684-- concurrency support and the monad instance provides concurrent looping.
1685-- Other streaming libraries like pipes, conduit and machines represent and
1686-- compose stream processors rather than the stream data and therefore fall in
1687-- another class of streaming libraries and have comparatively more complicated
1690-- When it comes to concurrency, streamly can do everything that the @async@
1691-- package can do and more. async provides applicative concurrency whereas
1692-- streamly provides both applicative and monadic concurrency. The
1693-- 'ZipAsync' type behaves like the applicative instance of async. In
1694-- comparison to transient streamly has a first class streaming interface and
1695-- is a monad transformer that can be used universally in any Haskell monad
1696-- transformer stack. Streamly was in fact originally inspired by the
1697-- concurrency implementation in @transient@ though it has no resemblance with
1698-- that and takes a lazy pull approach versus transient's strict push approach.
1700-- The non-determinism, concurrency and streaming combination make streamly a
1701-- strong FRP capable library as well. FRP is fundamentally stream of events
1702-- that can be processed concurrently. The example in this tutorial as well as
1703-- the "Streamly.Examples.CirclingSquare" example from Yampa demonstrate the
1704-- basic FRP capability of streamly. In core concepts streamly is strikingly
1705-- similar to @dunai@. dunai was designed from a FRP perspective and streamly
1706-- was originally designed from a concurrency perspective. However, both have
1707-- similarity at the core.
1711-- * Read the documentation of "Streamly" module
1712-- * Read the documentation of "Streamly.Prelude" module
1713-- * See the examples in the "examples" directory of the package
1714-- * See the tests in the "test" directory of the package
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list