5b1da6b · streamly · git.iko.soy

git.iko.soy/streamly

Update docs.

commit5b1da6b36af7f0b515fcce6cfcac7e04227f94a2 authorPranay Sashank <pranaysashank@gmail.com> dateThu 2 Jan 2020, 11:36 (7 years ago) parente3a11ad

7 files changed+20−23

compare with master

unifiedsplit

README.md+2−2 src/Streamly/Data/Unfold.hs+8−8 src/Streamly/Data/Unicode/Stream.hs+3−2 src/Streamly/Internal/Data/Fold.hs+2−2 src/Streamly/Internal/Data/Sink/Types.hs+3−3 src/Streamly/Internal/Prelude.hs+1−1 streamly.cabal+1−5

README.md+2−2

@@ -95,7 +95,7 @@ performance results and a comparison with the `async` package.

9595

9696## Installing and using

9797

98−Please see [INSTALL.md](INSTALL.md) for instructions on how to use streamly

98+Please see [INSTALL.md](./INSTALL.md) for instructions on how to use streamly

9999with your Haskell build tool or package manager. You may want to go through it

100100before jumping to run the examples below.

101101

@@ -508,7 +508,7 @@ In presence of concurrency, synchronous exceptions work just the way they are

508508supposed to work in non-concurrent code. When concurrent streams

509509are combined together, exceptions from the constituent streams are propagated

510510to the consumer stream. When an exception occurs in any of the constituent

511−streams other concurrent streams are promptly terminated.

511+streams other concurrent streams are promptly terminated.

512512

513513There is no notion of explicit threads in streamly, therefore, no

514514asynchronous exceptions to deal with. You can just ignore the zillions of

src/Streamly/Data/Unfold.hs+8−8

@@ -22,8 +22,8 @@

2222-- values from a single starting value often called a seed value. Values can be

2323-- generated and /pulled/ from the 'Unfold' one at a time. It can also be

2424-- called a producer or a source of stream. It is a data representation of the

25−-- standard 'S.unfoldr' function. An 'Unfold' can be converted into a stream

26−-- type using 'S.unfold' by supplying the seed.

25+-- standard 'Streamly.Prelude.unfoldr' function. An 'Unfold' can be converted

26+-- into a stream type using 'Streamly.Prelude.unfold' by supplying the seed.

2727--

2828-- = Performance Notes

2929--

@@ -34,13 +34,13 @@

3434-- @Unfold m a b@ can be considered roughly equivalent to an action @a -> t m

3535-- b@ (where @t@ is a stream type). Instead of using an 'Unfold' one could just

3636-- use a function of the shape @a -> t m b@. However, working with stream types

37−-- like 'S.SerialT' does not allow the compiler to perform stream fusion

37+-- like t'Streamly.SerialT' does not allow the compiler to perform stream fusion

3838-- optimization when merging, appending or concatenating multiple streams.

3939-- Even though stream based combinator have excellent performance, they are

4040-- much less efficient when compared to combinators using 'Unfold'. For

41−-- example, the 'S.concatMap' combinator which uses @a -> t m b@ (where @t@ is

42−-- a stream type) to generate streams is much less efficient compared to

43−-- 'S.concatUnfold'.

41+-- example, the 'Streamly.Prelude.concatMap' combinator which uses @a -> t m b@

42+-- (where @t@ is a stream type) to generate streams is much less efficient

43+-- compared to 'Streamly.Prelude.concatUnfold'.

4444--

4545-- On the other hand, transformation operations on stream types are as

4646-- efficient as transformations on 'Unfold'.

@@ -58,8 +58,8 @@

5858-- More, not yet exposed, unfold combinators can be found in

5959-- "Streamly.Internal.Data.Unfold".

6060

61−-- The stream types (e.g. 'S.SerialT') can be considered as a special case of

62−-- 'Unfold' with no starting seed.

61+-- The stream types (e.g. t'Streamly.SerialT') can be considered as a special

62+-- case of 'Unfold' with no starting seed.

6363--

6464module Streamly.Data.Unfold

6565 (

src/Streamly/Data/Unicode/Stream.hs+3−2

@@ -58,8 +58,9 @@

5858--

5959-- = Experimental APIs

6060--

61−-- Some experimental APIs to conveniently process text using the @Array Char@

62−-- represenation directly can be found in "Streamly.Internal.Unicode.Array".

61+-- Some experimental APIs to conveniently process text using the

62+-- @Array Char@ represenation directly can be found in

63+-- "Streamly.Internal.Memory.Unicode.Array".

6364

6465-- XXX an unpinned array representation can be useful to store short and short

6566-- lived strings in memory.

src/Streamly/Internal/Data/Fold.hs+2−2

@@ -623,7 +623,7 @@ foldMapM act = Fold step begin done

623623-- | Folds the input stream to a list.

624624--

625625-- /Warning!/ working on large lists accumulated as buffers in memory could be

626−-- very inefficient, consider using "Streamly.Array" instead.

626+-- very inefficient, consider using "Streamly.Memory.Array" instead.

627627--

628628-- @since 0.7.0

629629

@@ -641,7 +641,7 @@ toList = Fold (\f x -> return $ f . (x :))

641641-- | A fold that drains the first n elements of its input, running the effects

642642-- and discarding the results.

643643{-# INLINABLE drainN #-}

644−drainN :: Monad m => Int -> Fold m a ()

644+drainN :: Monad m => Int -> Fold m a ()

645645drainN n = ltake n drain

646646

647647-- | A fold that drains elements of its input as long as the predicate succeeds,

src/Streamly/Internal/Data/Sink/Types.hs+3−3

@@ -16,9 +16,9 @@ where

1616-- Sink

1717------------------------------------------------------------------------------

1818

19−-- | A 'Sink' is a special type of 'Foldl' that does not accumulate any value,

19+-- | A 'Sink' is a special type of 'Fold' that does not accumulate any value,

2020-- but runs only effects. A 'Sink' has no state to maintain therefore can be a

21−-- bit more efficient than a 'Foldl' with '()' as the state, especially when

21+-- bit more efficient than a 'Fold' with '()' as the state, especially when

2222-- 'Sink's are composed with other operations. A Sink can be upgraded to a

23−-- 'Foldl', but a 'Foldl' cannot be converted into a Sink.

23+-- 'Fold', but a 'Fold' cannot be converted into a Sink.

2424data Sink m a = Sink (a -> m ())

src/Streamly/Internal/Prelude.hs+1−1

@@ -598,7 +598,7 @@ unfoldrMZipSerial = Serial.unfoldrM

598598

599599-- | Convert an 'Unfold' into a stream by supplying it an input seed.

600600--

601−-- >>> unfold UF.replicateM 10 (putStrLn "hello")

601+-- >>> unfold (UF.replicateM 10) (putStrLn "hello")

602602--

603603-- /Since: 0.7.0/

604604{-# INLINE unfold #-}

streamly.cabal+1−5

@@ -62,7 +62,7 @@ description:

6262 .

6363 Where to find more information:

6464 .

65− * /Quick Overview/: <src/README.md README file> in the package

65+ * /Quick Overview/: <#readme README file> in the package

6666 * /Building/: <src/docs/Build.md Build guide> for optimal performance

6767 * /Detailed Tutorial/: "Streamly.Tutorial" module in the haddock documentation

6868 * /Interoperation/: "Streamly.Tutorial" module for interop with other

@@ -75,10 +75,6 @@ description:

7575 * <https://github.com/composewell/streaming-benchmarks Streaming Benchmarks>

7676 * <https://github.com/composewell/concurrency-benchmarks Concurrency Benchmarks>

7777 .

78− For additional unreleased/experimental APIs, build the haddock docs using:

79− .

80− > $ cabal haddock --haddock-option="--show-all"

81− > $ stack haddock --haddock-arguments "--show-all" --no-haddock-deps

8278

8379

8480homepage: https://github.com/composewell/streamly