streamly

Beautiful Streaming, Concurrent and Reactive Composition

https://github.com/composewell/streamly

Version on this page:0.7.1
LTS Haskell 22.39:0.10.1@rev:3
Stackage Nightly 2024-10-31:0.10.1@rev:4
Latest on Hackage:0.10.1@rev:4

See all snapshots streamly appears in

BSD-3-Clause licensed by Harendra Kumar
Maintained by [email protected]
This version can be pinned in stack with:streamly-0.7.1@sha256:a607999630c605cf4fd0e24354eb7b324c8edf6de4f14873106ffadb7bb5daf7,37484

Module documentation for 0.7.1

Streamly

Hackage Gitter chat Travis Appveyor CircleCI Coverage Status

Learning Materials

Streaming Concurrently

Haskell lists express pure computations using composable stream operations like :, unfold, map, filter, zip and fold. Streamly is exactly like lists except that it can express sequences of pure as well as monadic computations aka streams. More importantly, it can express monadic sequences with concurrent execution semantics without introducing any additional APIs.

Streamly expresses concurrency using standard, well known abstractions. Concurrency semantics are defined for list operations, semigroup, applicative and monadic compositions. Programmer does not need to know any low level notions of concurrency like threads, locking or synchronization. Concurrent and non-concurrent programs are fundamentally the same. A chosen segment of the program can be made concurrent by annotating it with an appropriate combinator. We can choose a combinator for lookahead style or asynchronous concurrency. Concurrency is automatically scaled up or down based on the demand from the consumer application, we can finally say goodbye to managing thread pools and associated sizing issues. The result is truly fearless and declarative monadic concurrency.

Where to use streamly?

Streamly is a general purpose programming framework. It can be used equally efficiently from a simple Hello World! program to a massively concurrent application. The answer to the question, “where to use streamly?” - would be similar to the answer to - “Where to use Haskell lists or the IO monad?”.

Streamly simplifies streaming and makes it as intuitive as plain lists. Unlike other streaming libraries, no fancy types are required. Streamly is simply a generalization of Haskell lists to monadic streaming optionally with concurrent composition. The basic stream type in streamly SerialT m a can be considered as a list type [a] parameterized by the monad m. For example, SerialT IO a is a moral equivalent of [a] in the IO monad. SerialT Identity a, is equivalent to pure lists. Streams are constructed very much like lists, except that they use nil and cons instead of [] and :. Unlike lists, streams can be constructed from monadic effects, not just pure elements. Streams are processed just like lists, with list like combinators, except that they are monadic and work in a streaming fashion. In other words streamly just completes what lists lack, you do not need to learn anything new. Please see streamly vs lists for a detailed comparison.

Not surprisingly, the monad instance of streamly is a list transformer, with concurrency capability.

Why data flow programming?

If you need some convincing for using streaming or data flow programming paradigm itself then try to answer this question - why do we use lists in Haskell? It boils down to why we use functional programming in the first place. Haskell is successful in enforcing the functional data flow paradigm for pure computations using lists, but not for monadic computations. In the absence of a standard and easy to use data flow programming paradigm for monadic computations, and the IO monad providing an escape hatch to an imperative model, we just love to fall into the imperative trap, and start asking the same fundamental question again - why do we have to use the streaming data model?

Comparative Performance

High performance and simplicity are the two primary goals of streamly. Streamly employs two different stream representations (CPS and direct style) and interconverts between the two to get the best of both worlds on different operations. It uses both foldr/build (for CPS style) and stream fusion (for direct style) techniques to fuse operations. In terms of performance, Streamly’s goal is to compete with equivalent C programs. Streamly redefines “blazing fast” for streaming libraries, it competes with lists and vector. Other streaming libraries like “streaming”, “pipes” and “conduit” are orders of magnitude slower on most microbenchmarks. See streaming benchmarks for detailed comparison.

The following chart shows a comparison of those streamly and list operations where performance of the two differs by more than 10%. Positive y-axis displays how many times worse is a list operation compared to the same streamly operation, negative y-axis shows where streamly is worse compared to lists.

Streamly vs Lists (time) comparison

Streamly uses lock-free synchronization for concurrent operations. It employs auto-scaling of the degree of concurrency based on demand. For CPU bound tasks it tries to keep the threads close to the number of CPUs available whereas for IO bound tasks more threads can be utilized. Parallelism can be utilized with little overhead even if the task size is very small. See concurrency benchmarks for detailed performance results and a comparison with the async package.

Installing and using

Please see INSTALL.md for instructions on how to use streamly with your Haskell build tool or package manager. You may want to go through it before jumping to run the examples below.

The module Streamly provides just the core stream types, type casting and concurrency control combinators. Stream construction, transformation, folding, merging, zipping combinators are found in Streamly.Prelude.

Streaming Pipelines

The following snippet provides a simple stream composition example that reads numbers from stdin, prints the squares of even numbers and exits if an even number more than 9 is entered.

import Streamly
import qualified Streamly.Prelude as S
import Data.Function ((&))

main = S.drain $
       S.repeatM getLine
     & fmap read
     & S.filter even
     & S.takeWhile (<= 9)
     & fmap (\x -> x * x)
     & S.mapM print

Unlike pipes or conduit and like vector and streaming, streamly composes stream data instead of stream processors (functions). A stream is just like a list and is explicitly passed around to functions that process the stream. Therefore, no special operator is needed to join stages in a streaming pipeline, just the standard function application ($) or reverse function application (&) operator is enough.

Concurrent Stream Generation

consM or its operator form |: can be used to construct a stream from monadic actions. A stream constructed with consM can run the monadic actions in the stream concurrently when used with appropriate stream type combinator (e.g. asyncly, aheadly or parallely).

The following code finishes in 3 seconds (6 seconds when serial), note the order of elements in the resulting output, the outputs are consumed as soon as each action is finished (asyncly):

> let p n = threadDelay (n * 1000000) >> return n
> S.toList $ asyncly $ p 3 |: p 2 |: p 1 |: S.nil
[1,2,3]

Use aheadly if you want speculative concurrency i.e. execute the actions in the stream concurrently but consume the results in the specified order:

> S.toList $ aheadly $ p 3 |: p 2 |: p 1 |: S.nil
[3,2,1]

Monadic stream generation functions e.g. unfoldrM, replicateM, repeatM, iterateM and fromFoldableM etc. can work concurrently.

The following finishes in 10 seconds (100 seconds when serial):

S.drain $ asyncly $ S.replicateM 10 $ p 10

Concurrency Auto Scaling

Concurrency is auto-scaled i.e. more actions are executed concurrently if the consumer is consuming the stream at a higher speed. How many tasks are executed concurrently can be controlled by maxThreads and how many results are buffered ahead of consumption can be controlled by maxBuffer. See the documentation in the Streamly module.

Concurrent Streaming Pipelines

Use |& or |$ to apply stream processing functions concurrently. The following example prints a “hello” every second; if you use & instead of |& you will see that the delay doubles to 2 seconds instead because of serial application.

main = S.drain $
      S.repeatM (threadDelay 1000000 >> return "hello")
   |& S.mapM (\x -> threadDelay 1000000 >> putStrLn x)

Mapping Concurrently

We can use mapM or sequence functions concurrently on a stream.

> let p n = threadDelay (n * 1000000) >> return n
> S.drain $ aheadly $ S.mapM (\x -> p 1 >> print x) (serially $ repeatM (p 1))

Serial and Concurrent Merging

Semigroup and Monoid instances can be used to fold streams serially or concurrently. In the following example we compose ten actions in the stream, each with a delay of 1 to 10 seconds, respectively. Since all the actions are concurrent we see one output printed every second:

import Streamly
import qualified Streamly.Prelude as S
import Control.Concurrent (threadDelay)

main = S.toList $ parallely $ foldMap delay [1..10]
 where delay n = S.yieldM $ threadDelay (n * 1000000) >> print n

Streams can be combined together in many ways. We provide some examples below, see the tutorial for more ways. We use the following delay function in the examples to demonstrate the concurrency aspects:

import Streamly
import qualified Streamly.Prelude as S
import Control.Concurrent

delay n = S.yieldM $ do
    threadDelay (n * 1000000)
    tid <- myThreadId
    putStrLn (show tid ++ ": Delay " ++ show n)

Serial

main = S.drain $ delay 3 <> delay 2 <> delay 1
ThreadId 36: Delay 3
ThreadId 36: Delay 2
ThreadId 36: Delay 1

Parallel

main = S.drain . parallely $ delay 3 <> delay 2 <> delay 1
ThreadId 42: Delay 1
ThreadId 41: Delay 2
ThreadId 40: Delay 3

Nested Loops (aka List Transformer)

The monad instance composes like a list monad.

import Streamly
import qualified Streamly.Prelude as S

loops = do
    x <- S.fromFoldable [1,2]
    y <- S.fromFoldable [3,4]
    S.yieldM $ putStrLn $ show (x, y)

main = S.drain loops
(1,3)
(1,4)
(2,3)
(2,4)

Concurrent Nested Loops

To run the above code with speculative concurrency i.e. each iteration in the loop can run concurrently but the results are presented to the consumer of the output in the same order as serial execution:

main = S.drain $ aheadly $ loops

Different stream types execute the loop iterations in different ways. For example, wSerially interleaves the loop iterations. There are several concurrent stream styles to execute the loop iterations concurrently in different ways, see the Streamly.Tutorial module for a detailed treatment.

Magical Concurrency

Streams can perform semigroup (<>) and monadic bind (>>=) operations concurrently using combinators like asyncly, parallelly. For example, to concurrently generate squares of a stream of numbers and then concurrently sum the square roots of all combinations of two streams:

import Streamly
import qualified Streamly.Prelude as S

main = do
    s <- S.sum $ asyncly $ do
        -- Each square is performed concurrently, (<>) is concurrent
        x2 <- foldMap (\x -> return $ x * x) [1..100]
        y2 <- foldMap (\y -> return $ y * y) [1..100]
        -- Each addition is performed concurrently, monadic bind is concurrent
        return $ sqrt (x2 + y2)
    print s

The concurrency facilities provided by streamly can be compared with OpenMP and Cilk but with a more declarative expression.

Example: Listing Directories Recursively/Concurrently

The following code snippet lists a directory tree recursively, reading multiple directories concurrently:

import Control.Monad.IO.Class (liftIO)
import Path.IO (listDir, getCurrentDir) -- from path-io package
import Streamly (AsyncT, adapt)
import qualified Streamly.Prelude as S

listDirRecursive :: AsyncT IO ()
listDirRecursive = getCurrentDir >>= readdir >>= liftIO . mapM_ putStrLn
  where
    readdir dir = do
      (dirs, files) <- listDir dir
      S.yield (map show dirs ++ map show files) <> foldMap readdir dirs

main :: IO ()
main = S.drain $ adapt $ listDirRecursive

AsyncT is a stream monad transformer. If you are familiar with a list transformer, it is nothing but ListT with concurrency semantics. For example, the semigroup operation <> is concurrent. This makes foldMap concurrent too. You can replace AsyncT with SerialT and the above code will become serial, exactly equivalent to a ListT.

Rate Limiting

For bounded concurrent streams, stream yield rate can be specified. For example, to print hello once every second you can simply write this:

import Streamly
import Streamly.Prelude as S

main = S.drain $ asyncly $ avgRate 1 $ S.repeatM $ putStrLn "hello"

For some practical uses of rate control, see AcidRain.hs and CirclingSquare.hs . Concurrency of the stream is automatically controlled to match the specified rate. Rate control works precisely even at throughputs as high as millions of yields per second. For more sophisticated rate control see the haddock documentation.

Arrays

The Streamly.Memory.Array module provides immutable arrays. Arrays are the computing duals of streams. Streams are good at sequential access and immutable transformations of in-transit data whereas arrays are good at random access and in-place transformations of buffered data. Unlike streams which are potentially infinite, arrays are necessarily finite. Arrays can be used as an efficient interface between streams and external storage systems like memory, files and network. Streams and arrays complete each other to provide a general purpose computing system. The design of streamly as a general purpose computing framework is centered around these two fundamental aspects of computing and storage.

Streamly.Memory.Array uses pinned memory outside GC and therefore avoid any GC overhead for the storage in arrays. Streamly allows efficient transformations over arrays using streams. It uses arrays to transfer data to and from the operating system and to store data in memory.

Folds

Folds are consumers of streams. Streamly.Data.Fold module provides a Fold type that represents a foldl'. Such folds can be efficiently composed allowing the compiler to perform stream fusion and therefore implement high performance combinators for consuming streams. A stream can be distributed to multiple folds, or it can be partitioned across multiple folds, or demultiplexed over multiple folds, or unzipped to two folds. We can also use folds to fold segments of stream generating a stream of the folded results.

If you are familiar with the foldl library, these are the same composable left folds but simpler and better integrated with streamly, and with many more powerful ways of composing and applying them.

Unfolds

Unfolds are duals of folds. Folds help us compose consumers of streams efficiently and unfolds help us compose producers of streams efficiently. Streamly.Data.Unfold provides an Unfold type that represents an unfoldr or a stream generator. Such generators can be combined together efficiently allowing the compiler to perform stream fusion and implement high performance stream merging combinators.

File IO

The following code snippets implement some common Unix command line utilities using streamly. You can compile these with ghc -O2 -fspec-constr-recursive=16 -fmax-worker-args=16 and compare the performance with regular GNU coreutils available on your system. Though many of these are not most optimal solutions to keep them short and elegant. Source file HandleIO.hs in the examples directory includes these examples.

module Main where

import qualified Streamly.Prelude as S
import qualified Streamly.Data.Fold as FL
import qualified Streamly.Memory.Array as A
import qualified Streamly.FileSystem.Handle as FH
import qualified System.IO as FH

import Data.Char (ord)
import System.Environment (getArgs)
import System.IO (openFile, IOMode(..), stdout)

withArg f = do
    (name : _) <- getArgs
    src <- openFile name ReadMode
    f src

withArg2 f = do
    (sname : dname : _) <- getArgs
    src <- openFile sname ReadMode
    dst <- openFile dname WriteMode
    f src dst

cat

cat = S.fold (FH.writeChunks stdout) . S.unfold FH.readChunks
main = withArg cat

cp

cp src dst = S.fold (FH.writeChunks dst) $ S.unfold FH.readChunks src
main = withArg2 cp

wc -l

wcl = S.length . S.splitOn (== 10) FL.drain . S.unfold FH.read
main = withArg wcl >>= print

Average Line Length

avgll =
      S.fold avg
    . S.splitOn (== 10) FL.length
    . S.unfold FH.read

    where avg      = (/) <$> toDouble FL.sum <*> toDouble FL.length
          toDouble = fmap (fromIntegral :: Int -> Double)

main = withArg avgll >>= print

Line Length Histogram

classify is not released yet, and is available in Streamly.Internal.Data.Fold

llhisto =
      S.fold (FL.classify FL.length)
    . S.map bucket
    . S.splitOn (== 10) FL.length
    . S.unfold FH.read

    where
    bucket n = let i = n `mod` 10 in if i > 9 then (9,n) else (i,n)

main = withArg llhisto >>= print

Socket IO

Its easy to build concurrent client and server programs using streamly. Streamly.Network.* modules provide easy combinators to build network servers and client programs using streamly. See FromFileClient.hs, EchoServer.hs, FileSinkServer.hs in the examples directory.

Exceptions

Exceptions can be thrown at any point using the MonadThrow instance. Standard exception handling combinators like bracket, finally, handle, onException are provided in Streamly.Prelude module.

In presence of concurrency, synchronous exceptions work just the way they are supposed to work in non-concurrent code. When concurrent streams are combined together, exceptions from the constituent streams are propagated to the consumer stream. When an exception occurs in any of the constituent streams other concurrent streams are promptly terminated.

There is no notion of explicit threads in streamly, therefore, no asynchronous exceptions to deal with. You can just ignore the zillions of blogs, talks, caveats about async exceptions. Async exceptions just don’t exist. Please don’t use things like myThreadId and throwTo just for fun!

Reactive Programming (FRP)

Streamly is a foundation for first class reactive programming as well by virtue of integrating concurrency and streaming. See AcidRain.hs for a console based FRP game example and CirclingSquare.hs for an SDL based animation example.

Conclusion

Streamly, short for streaming concurrently, provides monadic streams, with a simple API, almost identical to standard lists, and an in-built support for concurrency. By using stream-style combinators on stream composition, streams can be generated, merged, chained, mapped, zipped, and consumed concurrently – providing a generalized high level programming framework unifying streaming and concurrency. Controlled concurrency allows even infinite streams to be evaluated concurrently. Concurrency is auto scaled based on feedback from the stream consumer. The programmer does not have to be aware of threads, locking or synchronization to write scalable concurrent programs.

Streamly is a programmer first library, designed to be useful and friendly to programmers for solving practical problems in a simple and concise manner. Some key points in favor of streamly are:

  • Simplicity: Simple list like streaming API, if you know how to use lists then you know how to use streamly. This library is built with simplicity and ease of use as a design goal.
  • Concurrency: Simple, powerful, and scalable concurrency. Concurrency is built-in, and not intrusive, concurrent programs are written exactly the same way as non-concurrent ones.
  • Generality: Unifies functionality provided by several disparate packages (streaming, concurrency, list transformer, logic programming, reactive programming) in a concise API.
  • Performance: Streamly is designed for high performance. It employs stream fusion optimizations for best possible performance. Serial peformance is equivalent to the venerable vector library in most cases and even better in some cases. Concurrent performance is unbeatable. See streaming-benchmarks for a comparison of popular streaming libraries on micro-benchmarks.

The basic streaming functionality of streamly is equivalent to that provided by streaming libraries like vector, streaming, pipes, and conduit. In addition to providing streaming functionality, streamly subsumes the functionality of list transformer libraries like pipes or list-t, and also the logic programming library logict. On the concurrency side, it subsumes the functionality of the async package, and provides even higher level concurrent composition. Because it supports streaming with concurrency we can write FRP applications similar in concept to Yampa or reflex.

See the Comparison with existing packages section at the end of the tutorial.

Support

Please feel free to ask questions on the streamly gitter channel. If you require professional support, consulting, training or timely enhancements to the library please contact [email protected].

Credits

The following authors/libraries have influenced or inspired this library in a significant way:

  • Roman Leshchinskiy (vector)
  • Gabriel Gonzalez (foldl)
  • Alberto G. Corona (transient)

See the credits directory for full list of contributors, credits and licenses.

Contributing

The code is available under BSD-3 license on github. Join the gitter chat channel for discussions. Please ask any questions on the gitter channel or contact the maintainer directly. All contributions are welcome!

Changes

0.7.1

Bug Fixes

  • Fix a bug that caused findIndices to return wrong indices in some cases.
  • Fix a bug in tap, chunksOf that caused memory consumption to increase in some cases.
  • Fix a space leak in concurrent streams (async, wAsync, and ahead) that caused memory consumption to increase with the number of elements in the stream, especially when built with -threaded and used with -N RTS option. The issue occurs only in cases when a worker thread happens to be used continuously for a long time.
  • Fix scheduling of WAsyncT stream style to be in round-robin fashion.
  • Now builds with containers package version < 0.5.8.
  • Now builds with network package version >= 3.0.0.0 && < 3.1.0.0.

Behavior change

  • Combinators in Streamly.Network.Inet.TCP no longer use TCP NoDelay and ReuseAddr socket options by default. These options can now be specified using appropriate combinators.

Performance

  • Now uses fusion-plugin package for predictable stream fusion optimizations
  • Significant improvement in performance of concurrent stream operations.
  • Improved space and time performance of Foldable instance.

0.7.0

Breaking changes

  • Change the signature of foldrM to ensure that it is lazy
  • Change the signature of iterateM to ensure that it is lazy.
  • scanx would now require an additional Monad m constraint.

Behavior change

  • Earlier ParallelT was unaffected by maxBuffer directive, now maxBuffer can limit the buffer of a ParallelT stream as well. When the buffer becomes full, the producer threads block.
  • ParallelT streams no longer have an unlimited buffer by default. Now the buffer for parallel streams is limited to 1500 by default, the same as other concurrent stream types.

Deprecations

  • In Streamly.Prelude:

    • runStream has been replaced by drain
    • runN has been replaced by drainN
    • runWhile has been replaced by drainWhile
    • fromHandle has been deprecated. Please use Streamly.FileSystem.Handle.read, Streamly.Data.Unicode.Stream.decodeUtf8 and splitOnSuffix with Streamly.Data.Fold.toList to split the stream to a stream of String separated by a newline.
    • toHandle has been deprecated. Please use intersperse and concatUnfold to add newlines to a stream, Streamly.Data.Unicode.Stream.encodeUtf8 for encoding and Streamly.FileSystem.Handle.write for writing to a file handle.
    • Deprecate scanx, foldx, foldxM, foldr1
    • Remove deprecated APIs foldl, foldlM
    • Replace deprecated API scan with a new signature, to scan using Fold.
  • In Streamly module:

    • runStream has been deprecated, please use Streamly.Prelude.drain
  • Remove deprecated module Streamly.Time (moved to Streamly.Internal.Data.Time)

  • Remove module Streamly.Internal (functionality moved to the Internal hierarchy)

Bug Fixes

  • Fix a bug that caused uniq function to yield the same element twice.
  • Fix a bug that caused “thread blocked indefinitely in an MVar operation” exception in a parallel stream.
  • Fix unbounded memory usage (leak) in parallel combinator. The bug manifests when large streams are combined using parallel.

Major Enhancements

This release contains a lot of new features and major enhancements. For more details on the new features described below please see the haddock docs of the modules on hackage.

Exception Handling

See Streamly.Prelude for new exception handling combinators like before, after, bracket, onException, finally, handle etc.

Composable Folds

Streamly.Data.Fold module provides composable folds (stream consumers). Folds allow splitting, grouping, partitioning, unzipping and nesting a stream onto multiple folds without breaking the stream. Combinators are provided for temporal and spatial window based fold operations, for example, to support folding and aggregating data for timeout or inactivity based sessions.

Composable Unfolds

Streamly.Data.Unfold module provides composable stream generators. Unfolds allow high performance merging/flattening/combining of stream generators.

Streaming File IO

Streamly.FileSystem.Handle provides handle based streaming file IO operations.

Streaming Network IO

  • Streamly.Network.Socket provides socket based streaming network IO operations.

  • Streamly.Network.Inet.TCP provides combinators to build Inet/TCP clients and servers.

Concurrent concatMap

The new concatMapWith in Streamly.Prelude combinator performs a concatMap using a supplied merge/concat strategy. This is a very powerful combinator as you can, for example, concat streams concurrently using this.

Other Enhancements

  • Add the following new features/modules:

    • Unicode Strings: Streamly.Data.Unicode.Stream module provides encoding/decoding of character streams and other character stream operations.
    • Arrays: Streamly.Memory.Array module provides arrays for efficient in-memory buffering and efficient interfacing with IO.
  • Add the following to Streamly.Prelude:

    • unfold, fold, scan and postscan
    • concatUnfold to concat a stream after unfolding each element
    • intervalsOf and chunksOf
    • splitOn, splitOnSuffix, splitWithSuffix, and wordsBy
    • groups, groupsBy and groupsByRolling
    • postscanl' and postscanlM'
    • intersperse intersperse an element in between consecutive elements in stream
    • trace combinator maps a monadic function on a stream just for side effects
    • tap redirects a copy of the stream to a Fold

0.6.1

Bug Fixes

  • Fix a bug that caused maxThreads directive to be ignored when rate control was not used.

Enhancements

  • Add GHCJS support
  • Remove dependency on “clock” package

0.6.0

Breaking changes

  • Monad constraint may be needed on some of the existing APIs (findIndices and elemIndices).

Enhancements

  • Add the following functions to Streamly.Prelude:
    • Generation: replicate, fromIndices, fromIndicesM
    • Enumeration: Enumerable type class, enumerateFrom, enumerateFromTo, enumerateFromThen, enumerateFromThenTo, enumerate, enumerateTo
    • Running: runN, runWhile
    • Folds: (!!), maximumBy, minimumBy, the
    • Scans: scanl1', `scanl1M’
    • Filters: uniq, insertBy, deleteBy, findM
    • Multi-stream: eqBy, cmpBy, mergeBy, mergeByM, mergeAsyncBy, mergeAsyncByM, isPrefixOf, isSubsequenceOf, stripPrefix, concatMap, concatMapM, indexed, indexedR
  • Following instances were added for SerialT m, WSerialT m and ZipSerialM m:
    • When m ~ Identity: IsList, Eq, Ord, Show, Read, IsString, NFData, NFData1, Traversable
    • When m is Foldable: Foldable
  • Performance improvements
  • Add benchmarks to measure composed and iterated operations

0.5.2

Bug Fixes

  • Cleanup any pending threads when an exception occurs.
  • Fixed a livelock in ahead style streams. The problem manifests sometimes when multiple streams are merged together in ahead style and one of them is a nil stream.
  • As per expected concurrency semantics each forked concurrent task must run with the monadic state captured at the fork point. This release fixes a bug, which, in some cases caused an incorrect monadic state to be used for a concurrent action, leading to unexpected behavior when concurrent streams are used in a stateful monad e.g. StateT. Particularly, this bug cannot affect ReaderT.

0.5.1

  • Performance improvements, especially space consumption, for concurrent streams

0.5.0

Bug Fixes

  • Leftover threads are now cleaned up as soon as the consumer is garbage collected.
  • Fix a bug in concurrent function application that in certain cases would unnecessarily share the concurrency state resulting in incorrect output stream.
  • Fix passing of state across parallel, async, wAsync, ahead, serial, wSerial combinators. Without this fix combinators that rely on state passing e.g. maxThreads and maxBuffer won’t work across these combinators.

Enhancements

  • Added rate limiting combinators rate, avgRate, minRate, maxRate and constRate to control the yield rate of a stream.
  • Add foldl1', foldr1, intersperseM, find, lookup, and, or, findIndices, findIndex, elemIndices, elemIndex, init to Prelude

Deprecations

  • The Streamly.Time module is now deprecated, its functionality is subsumed by the new rate limiting combinators.

0.4.1

Bug Fixes

  • foldxM was not fully strict, fixed.

0.4.0

Breaking changes

  • Signatures of zipWithM and zipAsyncWithM have changed
  • Some functions in prelude now require an additional Monad constraint on the underlying type of the stream.

Deprecations

  • once has been deprecated and renamed to yieldM

Enhancements

  • Add concurrency control primitives maxThreads and maxBuffer.
  • Concurrency of a stream with bounded concurrency when used with take is now limited by the number of elements demanded by take.
  • Significant performance improvements utilizing stream fusion optimizations.
  • Add yield to construct a singleton stream from a pure value
  • Add repeat to generate an infinite stream by repeating a pure value
  • Add fromList and fromListM to generate streams from lists, faster than fromFoldable and fromFoldableM
  • Add map as a synonym of fmap
  • Add scanlM', the monadic version of scanl’
  • Add takeWhileM and dropWhileM
  • Add filterM

0.3.0

Breaking changes

  • Some prelude functions, to whom concurrency capability has been added, will now require a MonadAsync constraint.

Bug Fixes

  • Fixed a race due to which, in a rare case, we might block indefinitely on an MVar due to a lost wakeup.
  • Fixed an issue in adaptive concurrency. The issue caused us to stop creating more worker threads in some cases due to a race. This bug would not cause any functional issue but may reduce concurrency in some cases.

Enhancements

  • Added a concurrent lookahead stream type Ahead
  • Added fromFoldableM API that creates a stream from a container of monadic actions
  • Monadic stream generation functions consM, |:, unfoldrM, replicateM, repeatM, iterateM and fromFoldableM can now generate streams concurrently when used with concurrent stream types.
  • Monad transformation functions mapM and sequence can now map actions concurrently when used at appropriate stream types.
  • Added concurrent function application operators to run stages of a stream processing function application pipeline concurrently.
  • Added mapMaybe and mapMaybeM.

0.2.1

Bug Fixes

  • Fixed a bug that caused some transformation ops to return incorrect results when used with concurrent streams. The affected ops are take, filter, takeWhile, drop, dropWhile, and reverse.

0.2.0

Breaking changes

  • Changed the semantics of the Semigroup instance for InterleavedT, AsyncT and ParallelT. The new semantics are as follows:

    • For InterleavedT, <> operation interleaves two streams
    • For AsyncT, <> now concurrently merges two streams in a left biased manner using demand based concurrency.
    • For ParallelT, the <> operation now concurrently meges the two streams in a fairly parallel manner.

    To adapt to the new changes, replace <> with serial wherever it is used for stream types other than StreamT.

  • Remove the Alternative instance. To adapt to this change replace any usage of <|> with parallel and empty with nil.

  • Stream type now defaults to the SerialT type unless explicitly specified using a type combinator or a monomorphic type. This change reduces puzzling type errors for beginners. It includes the following two changes:

    • Change the type of all stream elimination functions to use SerialT instead of a polymorphic type. This makes sure that the stream type is always fixed at all exits.
    • Change the type combinators (e.g. parallely) to only fix the argument stream type and the output stream type remains polymorphic.

    Stream types may have to be changed or type combinators may have to be added or removed to adapt to this change.

  • Change the type of foldrM to make it consistent with foldrM in base.

  • async is renamed to mkAsync and async is now a new API with a different meaning.

  • ZipAsync is renamed to ZipAsyncM and ZipAsync is now ZipAsyncM specialized to the IO Monad.

  • Remove the MonadError instance as it was not working correctly for parallel compositions. Use MonadThrow instead for error propagation.

  • Remove Num/Fractional/Floating instances as they are not very useful. Use fmap and liftA2 instead.

Deprecations

  • Deprecate and rename the following symbols:
    • Streaming to IsStream
    • runStreaming to runStream
    • StreamT to SerialT
    • InterleavedT to WSerialT
    • ZipStream to ZipSerialM
    • ZipAsync to ZipAsyncM
    • interleaving to wSerially
    • zipping to zipSerially
    • zippingAsync to zipAsyncly
    • <=> to wSerial
    • <| to async
    • each to fromFoldable
    • scan to scanx
    • foldl to foldx
    • foldlM to foldxM
  • Deprecate the following symbols for future removal:
    • runStreamT
    • runInterleavedT
    • runAsyncT
    • runParallelT
    • runZipStream
    • runZipAsync

Enhancements

  • Add the following functions:
    • consM and |: operator to construct streams from monadic actions
    • once to create a singleton stream from a monadic action
    • repeatM to construct a stream by repeating a monadic action
    • scanl' strict left scan
    • foldl' strict left fold
    • foldlM' strict left fold with a monadic fold function
    • serial run two streams serially one after the other
    • async run two streams asynchronously
    • parallel run two streams in parallel (replaces <|>)
    • WAsyncT stream type for BFS version of AsyncT composition
  • Add simpler stream types that are specialized to the IO monad
  • Put a bound (1500) on the output buffer used for asynchronous tasks
  • Put a limit (1500) on the number of threads used for Async and WAsync types

0.1.2

Enhancements

  • Add iterate, iterateM stream operations

Bug Fixes

  • Fixed a bug that caused unexpected behavior when pure was used to inject values in Applicative composition of ZipStream and ZipAsync types.

0.1.1

Enhancements

  • Make cons right associative and provide an operator form .: for it
  • Add null, tail, reverse, replicateM, scan stream operations
  • Improve performance of some stream operations (foldl, dropWhile)

Bug Fixes

  • Fix the product operation. Earlier, it always returned 0 due to a bug
  • Fix the last operation, which returned Nothing for singleton streams

0.1.0

  • Initial release