Move examples from Streamly module to examples dir

.travis.yml

@@ -121,7 +121,7 @@ matrix:
 
   # Note COVERALLS (hpc-coveralls) works only with cabal build.
   # For this to succeed you have to add your project to coveralls.io first
-  - env: BUILD=cabal CABALVER=2.0 GHCVER=8.2.2 COVERALLS_OPTIONS="--coverage-mode=StrictlyFullLines --exclude-dir=test test properties"
+  - env: BUILD=cabal CABALVER=2.0 GHCVER=8.2.2 COVERALLS_OPTIONS="--coverage-mode=StrictlyFullLines --exclude-dir=test test properties loops nested-loops parallel-loops"
     addons: {apt: {packages: [cabal-install-2.0,ghc-8.2.2], sources: [hvr-ghc]}}
 
   # --------------------------------------------------------------------------

examples/AcidRain.hs

@@ -3,8 +3,6 @@
 -- This example is adapted from Gabriel Gonzalez's pipes-concurrency package.
 -- https://hackage.haskell.org/package/pipes-concurrency-2.0.8/docs/Pipes-Concurrent-Tutorial.html
 
-module Streamly.Examples.AcidRainGame where
-
 import Streamly
 import Control.Concurrent (threadDelay)
 import Control.Monad (when)
@@ -38,8 +36,8 @@ game = do
     when (h <= 0) $ fail "You die!"
     liftIO $ putStrLn $ "Health = " ++ show h
 
-acidRainGame :: IO ()
-acidRainGame = do
+main :: IO ()
+main = do
     putStrLn "Your health is deteriorating due to acid rain,\
              \ type \"potion\" or \"quit\""
     _ <- runStateT (runStream game) 60

examples/CirclingSquare.hs

@@ -1,11 +1,10 @@
 -- Adapted from the Yampa package.
--- Displays a square moving in a circle. To move the position drag the mouse.
+-- Displays a square moving in a circle. To move the position drag it with the
+-- mouse.
 --
 -- Requires the SDL package, assuming streamly has already been built, you can
 -- compile it like this:
--- stack ghc --package SDL circle-mouse.hs
-
-module Streamly.Examples.CirclingSquare where
+-- stack ghc --package SDL CirclingSquare.hs
 
 import Data.IORef
 import Graphics.UI.SDL as SDL
@@ -84,8 +83,8 @@ updateDisplay cref = withClock clock refreshRate displaySquare
         let t = (fromIntegral time) * speed / 1000000
          in display (x + cos t * radius, y + sin t * radius)
 
-circlingSquare :: IO ()
-circlingSquare = do
+main :: IO ()
+main = do
   sdlInit
   cref <- newIORef (0,0)
   runStream $ once (updateController cref)

examples/ListDir.hs

@@ -1,15 +1,15 @@
-module Streamly.Examples.ListDirRecursive where
-
 import Path.IO (listDir, getCurrentDir)
 import System.IO (stdout, hSetBuffering, BufferMode(LineBuffering))
 import Streamly (runStream, coparallely)
 import Streamly.Prelude (once)
 
--- | This example demonstrates that there is little difference between regular
+-- | List the current directory recursively using concurrent processing
+--
+-- This example demonstrates that there is little difference between regular
 -- IO code and concurrent streamly code. You can just remove
 -- 'runStream . coparallely' and this becomes your regular IO code.
-listDirRecursive :: IO ()
-listDirRecursive = do
+main :: IO ()
+main = do
     hSetBuffering stdout LineBuffering
     runStream . coparallely $ getCurrentDir >>= readdir
     where readdir d = do

examples/MergeSort.hs

@@ -1,7 +1,5 @@
 {-# LANGUAGE FlexibleContexts    #-}
 
-module Streamly.Examples.MergeSortedStreams where
-
 import Data.Word
 import System.Random (getStdGen, randoms)
 import Data.List (sort)
@@ -36,7 +34,7 @@ merge a b = do
                         then (return y) <> merge (return x <> ma) mb
                         else (return x) <> merge ma (return y <> mb)
 
-mergeSortedStreams :: IO ()
-mergeSortedStreams = do
+main :: IO ()
+main = do
     xs <- A.toList $ mergeAsync getSorted getSorted
     putStrLn $ show $ length xs

examples/README.md

@@ -1,8 +1,44 @@
-For better examples see the Streamly.Examples module.
+# Running The Examples
 
+## Running directly using stack
 You can run these examples using `stack` like this:
 
 ```
 $ stack build
-$ stack loop.hs
+$ stack AcidRain.hs
+```
+
+Note: This method may not work for `CirclingSquare.hs` SDL animation example.
+
+## Build and run
+
+Build the library with the `examples` flag on e.g.
+
+```
+stack build --flag streamly:examples
+cabal new-build --flags examples
+```
+
+Then run the executables, for example:
+
+```
+stack exec AcidRain
+```
+
+The executable name are the same as the filenames.
+
+## Running the SDL animation example
+
+To include the SDL examples as well build with `examples-sdl` flag:
+
+```
+stack build --flag streamly:examples-sdl
+cabal new-build --flags examples-sdl
+```
+
+Make sure that you have the SDL OS package installed on your system and the
+headers are visible to Haskell build tool.
+
+```
+stack exec CirclingSquare
 ```

examples/SearchQuery.hs

@@ -1,13 +1,15 @@
-module Streamly.Examples.SearchEngineQuery where
-
 import Streamly
 import Streamly.Prelude (once)
 import Network.HTTP.Simple
 
--- Runs three search engine queries in parallel.
-searchEngineQuery :: IO ()
-searchEngineQuery = do
-    putStrLn "Using parallel alternative"
+-- | Runs three search engine queries in parallel and prints the search engine
+-- names in the fastest first order.
+--
+-- Does it twice using two different ways.
+--
+main :: IO ()
+main = do
+    putStrLn "Using parallel semigroup composition"
     runStream . parallely $ google <> bing <> duckduckgo
 
     putStrLn "\nUsing parallel applicative zip"

streamly.cabal

@@ -35,6 +35,7 @@ cabal-version:       >= 1.10
 extra-source-files:
     Changelog.md
     README.md
+    bench.sh
     charts/comparative/AllOperationsataGlance.svg
     charts/comparative/ComposingPipelineStages.svg
     stack-7.10.yaml
@@ -59,6 +60,10 @@ flag examples-sdl
   manual: True
   default: False
 
+-------------------------------------------------------------------------------
+-- Library
+-------------------------------------------------------------------------------
+
 library
     hs-source-dirs:    src
     other-modules:     Streamly.Core
@@ -69,16 +74,6 @@ library
                      , Streamly.Tutorial
                      , Streamly
 
-    if flag(examples) || flag(examples-sdl)
-      exposed-modules: Streamly.Examples
-                     , Streamly.Examples.SearchEngineQuery
-                     , Streamly.Examples.ListDirRecursive
-                     , Streamly.Examples.MergeSortedStreams
-                     , Streamly.Examples.AcidRainGame
-
-    if flag(examples-sdl)
-      exposed-modules: Streamly.Examples.CirclingSquare
-
     default-language: Haskell2010
     ghc-options:      -Wall
 
@@ -95,8 +90,6 @@ library
                       -Wredundant-constraints
                       -Wnoncanonical-monad-instances
                       -Wnoncanonical-monadfail-instances
-    if flag(examples-sdl)
-      cpp-options:      -DEXAMPLES_SDL
 
     build-depends:     base              >= 4.8   &&  < 5
                      , atomic-primops    >= 0.8   && < 0.9
@@ -114,15 +107,9 @@ library
     build-depends:
         semigroups    >= 0.18   && < 0.19
 
-  if flag(examples) || flag(examples-sdl)
-    build-Depends:
-        http-conduit >= 2.2.2 && < 2.4
-      , path-io      >= 0.1.0 && < 1.4
-      , random       >= 1.0.0 && < 1.2
-
-  if flag(examples-sdl)
-    build-Depends:
-        SDL  >= 0.6.5 && < 0.7
+-------------------------------------------------------------------------------
+-- Test suites
+-------------------------------------------------------------------------------
 
 test-suite test
   type: exitcode-stdio-1.0
@@ -175,6 +162,39 @@ test-suite properties
     , hspec             >= 2.0   && < 3
   default-language: Haskell2010
 
+test-suite loops
+  type: exitcode-stdio-1.0
+  default-language: Haskell2010
+  main-is: loops.hs
+  hs-source-dirs:  test
+  build-Depends:
+      streamly
+    , base >= 4.8   && < 5
+
+test-suite nested-loops
+  type: exitcode-stdio-1.0
+  default-language: Haskell2010
+  main-is: nested-loops.hs
+  hs-source-dirs:  test
+  build-Depends:
+      streamly
+    , base   >= 4.8   && < 5
+    , random >= 1.0.0 && < 1.2
+
+test-suite parallel-loops
+  type: exitcode-stdio-1.0
+  default-language: Haskell2010
+  main-is: parallel-loops.hs
+  hs-source-dirs:  test
+  build-Depends:
+      streamly
+    , base   >= 4.8   && < 5
+    , random >= 1.0.0 && < 1.2
+
+-------------------------------------------------------------------------------
+-- Benchmarks
+-------------------------------------------------------------------------------
+
 benchmark linear
   type: exitcode-stdio-1.0
   hs-source-dirs: benchmark
@@ -229,10 +249,6 @@ benchmark nested
     , random              >= 1.0   && < 2.0
     , gauge               >= 0.2.1 && < 0.3
 
--------------------------------------------------------------------------------
--- Examples
--------------------------------------------------------------------------------
-
 executable chart-linear
   default-language: Haskell2010
   hs-source-dirs: benchmark
@@ -259,46 +275,71 @@ executable chart-nested
   else
     buildable: False
 
-executable loops
+-------------------------------------------------------------------------------
+-- Examples
+-------------------------------------------------------------------------------
+
+executable SearchQuery
   default-language: Haskell2010
-  main-is: loops.hs
+  main-is: SearchQuery.hs
   hs-source-dirs:  examples
   if flag(examples) || flag(examples-sdl)
+    buildable: True
+    build-Depends:
+        streamly
+      , base         >= 4.8   && < 5
+      , http-conduit >= 2.2.2 && < 2.4
+  else
+    buildable: False
+
+executable ListDir
+  default-language: Haskell2010
+  main-is: ListDir.hs
+  hs-source-dirs:  examples
+  if flag(examples) || flag(examples-sdl)
+    buildable: True
+    build-Depends:
+        streamly
+      , base    >= 4.8   && < 5
+      , path-io >= 0.1.0 && < 1.4
+  else
+    buildable: False
+
+executable MergeSort
+  default-language: Haskell2010
+  main-is: MergeSort.hs
+  hs-source-dirs:  examples
+  if flag(examples) || flag(examples-sdl)
+    buildable: True
+    build-Depends:
+        streamly
+      , base   >= 4.8   && < 5
+      , random >= 1.0.0 && < 1.2
+  else
+    buildable: False
+
+executable AcidRain
+  default-language: Haskell2010
+  main-is: AcidRain.hs
+  hs-source-dirs:  examples
+  if flag(examples) || flag(examples-sdl)
+    buildable: True
+    build-Depends:
+        streamly
+      , base         >= 4.8   && < 5
+      , mtl          >= 2.2   && < 3
+  else
+    buildable: False
+
+executable CirclingSquare
+  default-language: Haskell2010
+  main-is: CirclingSquare.hs
+  hs-source-dirs:  examples
+  if flag(examples-sdl)
     buildable: True
     build-Depends:
         streamly
       , base >= 4.8   && < 5
-  else
-    buildable: False
-
-executable nested-loops
-  default-language: Haskell2010
-  main-is: nested-loops.hs
-  hs-source-dirs:  examples
-  if flag(examples) || flag(examples-sdl)
-    buildable: True
-    build-Depends:
-        streamly
-      , base   >= 4.8   && < 5
-      , random >= 1.0.0 && < 1.2
-    if impl(ghc < 8.0)
-      build-depends:
-          transformers    >= 0.4   && < 0.6
-  else
-    buildable: False
-
-executable parallel-loops
-  default-language: Haskell2010
-  main-is: parallel-loops.hs
-  hs-source-dirs:  examples
-  if flag(examples) || flag(examples-sdl)
-    buildable: True
-    build-Depends:
-        streamly
-      , base   >= 4.8   && < 5
-      , random >= 1.0.0 && < 1.2
-    if impl(ghc < 8.0)
-      build-depends:
-          transformers    >= 0.4   && < 0.6
+      , SDL  >= 0.6.5 && < 0.7
   else
     buildable: False

test/loops.hs

@@ -41,10 +41,6 @@ main = do
 -- Serial (single-threaded) stream generator loops
 -------------------------------------------------------------------------------
 
-    -- In a <> composition the action on the left is executed and only after it
-    -- finished then the action on the right is executed. In other words the
-    -- actions are run serially.
-
     -- Generates a value and then loops. Can be used to generate an infinite
     -- stream. Interleaves the generator and the consumer.
     loopTail :: Int -> Stream Int
@@ -64,11 +60,6 @@ main = do
 -- Concurrent (multi-threaded) adaptive demand-based stream generator loops
 -------------------------------------------------------------------------------
 
-    -- In a <| composition the action on the left is executed first. However,
-    -- if it is not fast enough to generate results at the consumer's speed
-    -- then the action on the right is also spawned concurrently. In other
-    -- words, both actions may run concurrently based on the need.
-
     loopTailA :: Int -> Stream Int
     loopTailA x = do
         once $ putStrLn "LoopTailA..."
@@ -82,8 +73,3 @@ main = do
 -------------------------------------------------------------------------------
 -- Parallel (fairly scheduled, multi-threaded) stream generator loops
 -------------------------------------------------------------------------------
-
-    -- In a <|> composition both actions are run concurrently in a fair
-    -- manner, no one action is preferred over another. Both actions are
-    -- spawned right away in their own independent threads. In other words, the
-    -- actions will run concurrently.

test/nested-loops.hs

@@ -14,6 +14,8 @@ main = runStream $ do
 
     where
 
+    -- we can just use
+    -- parallely $ mconcat $ replicate n $ once (...)
     loop :: String -> Int -> StreamT IO String
     loop name n = do
         rnd <- once (randomIO :: IO Int)

test/parallel-loops.hs

@@ -2,19 +2,25 @@ import Control.Concurrent (myThreadId, threadDelay)
 import System.IO (stdout, hSetBuffering, BufferMode(LineBuffering))
 import System.Random (randomIO)
 import Streamly
-import Streamly.Prelude (once)
+import qualified Streamly.Prelude as S
 
-main = runStream $ do
-    once $ hSetBuffering stdout LineBuffering
-    x <- loop "A" `parallel` loop "B"
-    once $ myThreadId >>= putStr . show
-             >> putStr " "
-             >> print x
+main = do
+    hSetBuffering stdout LineBuffering
+    runStream $ do
+        x <- S.take 10 $ loop "A" `parallel` loop "B"
+        S.once $ myThreadId >>= putStr . show
+               >> putStr " got "
+               >> print x
 
     where
 
+    -- we can just use
+    -- parallely $ cycle1 $ once (...)
     loop :: String -> Stream (String, Int)
     loop name = do
-        once $ threadDelay 1000000
-        rnd <- once (randomIO :: IO Int)
+        S.once $ threadDelay 1000000
+        rnd <- S.once (randomIO :: IO Int)
+        S.once $ myThreadId >>= putStr . show
+               >> putStr " yielding "
+               >> print rnd
         return (name, rnd) `parallel` loop name