@@ -11,6 +11,16 @@
1111-- Stability : experimental
1212-- Portability : GHC
1313--
14+-- To run examples in this module:
15+--
16+-- >>> import qualified Streamly.Prelude as Stream
17+-- >>> import Control.Concurrent (threadDelay)
18+-- >>> :{
19+-- delay n = do
20+-- threadDelay (n * 1000000) -- sleep for n seconds
21+-- putStrLn (show n ++ " sec") -- print "n sec"
22+-- return n -- IO Int
23+-- :}
1424--
1525module Streamly.Internal.Data.Stream.Async
1626 (
@@ -61,6 +71,15 @@ import qualified Streamly.Internal.Data.Stream.StreamD.Type as D
6171
6272#include "Instances.hs"
6373
74+-- $setup
75+-- >>> import Control.Concurrent (threadDelay)
76+-- >>> :{
77+-- delay n = do
78+-- threadDelay (n * 1000000) -- sleep for n seconds
79+-- putStrLn (show n ++ " sec") -- print "n sec"
80+-- return n -- IO Int
81+-- :}
82+
6483-------------------------------------------------------------------------------
6584-- Async
6685-------------------------------------------------------------------------------
@@ -637,27 +656,33 @@ infixr 6 `async`
637656-- | Merges two streams, both the streams may be evaluated concurrently,
638657-- outputs from both are used as they arrive:
639658--
659+-- >>> import Streamly.Prelude (async)
640660-- >>> stream1 = Stream.yieldM (delay 4)
641661-- >>> stream2 = Stream.yieldM (delay 2)
642662-- >>> Stream.toList $ stream1 `async` stream2
643−-- [4,2]
663+-- 2 sec
664+-- 4 sec
665+-- [2,4]
644666--
645667-- Multiple streams can be combined. With enough threads, all of them can be
646668-- scheduled simultaneously:
647669--
648670-- >>> stream3 = Stream.yieldM (delay 1)
649671-- >>> Stream.toList $ stream1 `async` stream2 `async` stream3
672+-- ...
650673-- [1,2,4]
651674--
652675-- With 2 threads, only two can be scheduled at a time, when one of those
653676-- finishes, the third one gets scheduled:
654677--
655678-- >>> Stream.toList $ Stream.maxThreads 2 $ stream1 `async` stream2 `async` stream3
679+-- ...
656680-- [2,1,4]
657681--
658682-- With a single thread, it becomes serial:
659683--
660684-- >>> Stream.toList $ Stream.maxThreads 1 $ stream1 `async` stream2 `async` stream3
685+-- ...
661686-- [4,2,1]
662687--
663688-- Only streams are scheduled for async evaluation, how actions within a
@@ -667,16 +692,18 @@ infixr 6 `async`
667692-- In the following example, both the streams are scheduled for concurrent
668693-- evaluation but each individual stream is evaluated serially:
669694--
670−-- >>> stream1 = Stream.fromListM $ map delay [3,3] -- SerialT IO Int
671−-- >>> stream2 = Stream.fromListM $ map delay [1,1] -- SerialT IO Int
695+-- >>> stream1 = Stream.fromListM $ Prelude.map delay [3,3] -- SerialT IO Int
696+-- >>> stream2 = Stream.fromListM $ Prelude.map delay [1,1] -- SerialT IO Int
672697-- >>> Stream.toList $ stream1 `async` stream2 -- IO [Int]
698+-- ...
673699-- [1,1,3,3]
674700--
675701-- If total threads are 2, the third stream is scheduled only after one of the
676702-- first two has finished:
677703--
678−-- >>> stream3 = Stream.fromListM $ map delay [2,2] -- SerialT IO Int
704+-- >>> stream3 = Stream.fromListM $ Prelude.map delay [2,2] -- SerialT IO Int
679705-- >>> Stream.toList $ Stream.maxThreads 2 $ stream1 `async` stream2 `async` stream3 -- IO [Int]
706+-- ...
680707-- [1,1,3,2,3,2]
681708--
682709-- Thus 'async' goes deep in first few streams rather than going wide in all
@@ -867,6 +894,7 @@ infixr 6 `wAsync`
867894-- With a single thread, 'async' starts behaving like 'serial' while 'wAsync'
868895-- starts behaving like 'wSerial'.
869896--
897+-- >>> import Streamly.Prelude (wAsync)
870898-- >>> stream1 = Stream.fromList [1,2,3]
871899-- >>> stream2 = Stream.fromList [4,5,6]
872900-- >>> Stream.toList $ Stream.asyncly $ Stream.maxThreads 1 $ stream1 `async` stream2