BSD-3-Clause licensed by Composewell Technologies
This version can be pinned in stack with:streamly-0.8.0@sha256:9784c80ee1ada51477520cabc4e92a0c76a6bb265f968a188f2fce818e7398e0,19654

Module documentation for 0.8.0

Streamly: Idiomatic Haskell with the Performance of C

Gitter chat Hackage

Streamly is a Haskell library that provides the building blocks to build safe, scalable, modular and high performance software. Streamly offers:

  • The type safety of Haskell.
  • The performance of C programs.
  • Powerful abstractions for structuring your code.
  • Idiomatic functional programming.
  • Declarative concurrency for the seamless use of multiprocessing hardware.

About This Document

This guide introduces programming with Streamly using a few practical examples:

The guide then looks at how Streamly achieves its performance. It concludes with a brief discussion about Streamly’s design philosophy, and with suggestions for further reading.

Getting Started

Installing Streamly

If you wish to follow along with this guide, you will need to have Streamly installed.

Please see the Getting Started With The Streamly Package guide for instructions on how to install Streamly.

If you wish to run benchmarks, please be sure to build your application using the instructions in the Build Guide.

An overview of the types used in these examples

As an expository device, we have indicated the types at the intermediate stages of stream computations as comments in the examples below. The meaning of these types are:

  • A SerialT IO a is a serial stream of values of type a in the IO Monad.
  • An AsyncT IO a is a concurrent (asynchronous) stream of values of type a in the IO Monad.
  • An Unfold IO a b is a representation of a function that converts a seed value of type a into a stream of values of type b in the IO Monad.
  • A Fold IO a b is a representation of a function that converts a stream of type a to a final accumulator of type b in the IO Monad.

A Note on Module Naming

Some of the examples below use modules from the Internal Streamly package hierarchy. These are not really internal to the library. We classify Streamly modules into two categories:

  • Released modules and APIs: These modules and APIs are stable. Significant changes to these modules and APIs will cause Streamly’s version number to change according to the package versioning policy.
  • Pre-release modules and APIs: These modules and APIs have not been formally released yet. They may change in the near future, and such changes will not necessarily be reflected in Streamly’s package version number. As yet unreleased modules and APIs reside in the Internal namespace.

The Examples

Modular Word Counting

A Fold in Streamly is a composable stream consumer. For our first example, we will use Folds to count the number of bytes, words and lines present in a file. We will then compose individual Folds together to count words, bytes and lines at the same time.

Please see the file WordCountModular.hs for the complete example program, including the imports that we have omitted here.

Count Bytes (wc -c)

We start with a code fragment that counts the number of bytes in a file:

import qualified Streamly.Data.Fold as Fold
import qualified Streamly.Internal.FileSystem.File as File
import qualified Streamly.Prelude as Stream

wcb :: String -> IO Int
wcb file =
    File.toBytes file        -- SerialT IO Word8
  & Stream.fold Fold.length  -- IO Int

Count Lines (wc -l)

The next code fragment shows how to count the number of lines in a file:

-- ASCII character 10 is a newline.
countl :: Int -> Word8 -> Int
countl n ch = if ch == 10 then n + 1 else n

-- The fold accepts a stream of `Word8` and returns a line count (`Int`).
nlines :: Monad m => Fold m Word8 Int
nlines = Fold.foldl' countl 0

wcl :: String -> IO Int
wcl file =
    File.toBytes file  -- SerialT IO Word8
  & Stream.fold nlines -- IO Int

Count Words (wc -w)

Our final code fragment counts the number of whitespace-separated words in a stream:

countw :: (Int, Bool) -> Word8 -> (Int, Bool)
countw (n, wasSpace) ch =
    if isSpace $ chr $ fromIntegral ch
    then (n, True)
    else (if wasSpace then n + 1 else n, False)

-- The fold accepts a stream of `Word8` and returns a word count (`Int`).
nwords :: Monad m => Fold m Word8 Int
nwords = fst <$> Fold.foldl' countw (0, True)

wcw :: String -> IO Int
wcw file =
    File.toBytes file   -- SerialT IO Word8
  & Stream.fold nwords  -- IO Int

Counting Bytes, Words and Lines Together

By using the Tee combinator we can compose the three folds that count bytes, lines and words individually into a single fold that counts all three at once. The applicative instance of Tee distributes its input to all the supplied folds (Fold.length, nlines, and nwords) and then combines the outputs from the folds using the supplied combiner function ((,,)).

import qualified Streamly.Internal.Data.Fold.Tee as Tee

-- The fold accepts a stream of `Word8` and returns the three counts.
countAll :: Fold IO Word8 (Int, Int, Int)
countAll = Tee.toFold $ (,,) <$> Tee Fold.length <*> Tee nlines <*> Tee nwords

wc :: String -> IO (Int, Int, Int)
wc file =
    File.toBytes file    -- SerialT IO Word8
  & Stream.fold countAll -- IO (Int, Int, Int)

This example demonstrates the excellent modularity offered by Streamly’s simple and concise API. Experienced Haskellers will notice that we have not used bytestrings—we instead used a stream of Word8 values, simplifying our program.

The Performance of Word Counting

We compare two equivalent implementations: one using Streamly, and the other using C.

The performance of the Streamly word counting implementation is:

$ time WordCount-hs gutenberg-500MB.txt
11242220 97050938 574714449 gutenberg-500MB.txt

real    0m1.825s
user    0m1.697s
sys     0m0.128s

The performance of an equivalent wc implementation in C is:

$ time WordCount-c gutenberg-500MB.txt
11242220 97050938 574714449 gutenberg-500MB.txt

real    0m2.100s
user    0m1.935s
sys     0m0.165s

Concurrent Word Counting

In our next example we show how the task of counting words, lines, and bytes could be done in parallel on multiprocessor hardware.

To count words in parallel we first divide the stream into chunks (arrays), do the counting within each chunk, and then add all the counts across chunks. We use the same code as above except that we use arrays for our input data.

Please see the file WordCountParallel.hs for the complete working code for this example, including the imports that we have omitted below.

The countArray function counts the line, word, char counts in one chunk:

import qualified Streamly.Data.Array.Foreign as Array

countArray :: Array Word8 -> IO Counts
countArray arr =
      Stream.unfold Array.read arr            -- SerialT IO Word8
    & Stream.decodeLatin1                     -- SerialT IO Char
    & Stream.foldl' count (Counts 0 0 0 True) -- IO Counts

Here the function count and the Counts data type are defined in the WordCount helper module defined in WordCount.hs.

When combining the counts in two contiguous chunks, we need to check whether the first element of the next chunk is a whitespace character in order to determine if the same word continues in the next chunk or whether the chunk starts with a new word. The partialCounts function adds a Bool flag to Counts returned by countArray to indicate whether the first character in the chunk is a space.

partialCounts :: Array Word8 -> IO (Bool, Counts)
partialCounts arr = do
    let r = Array.getIndex arr 0
    case r of
        Just x -> do
            counts <- countArray arr
            return (isSpace (chr (fromIntegral x)), counts)
        Nothing -> return (False, Counts 0 0 0 True)

addCounts then adds the counts from two consecutive chunks:

addCounts :: (Bool, Counts) -> (Bool, Counts) -> (Bool, Counts)
addCounts (sp1, Counts l1 w1 c1 ws1) (sp2, Counts l2 w2 c2 ws2) =
    let wcount =
            if not ws1 && not sp2 -- No space between two chunks.
            then w1 + w2 - 1
            else w1 + w2
     in (sp1, Counts (l1 + l2) wcount (c1 + c2) ws2)

To count in parallel we now only need to divide the stream into arrays, apply our counting function to each array, and then combine the counts from each chunk.

wc :: String -> IO (Bool, Counts)
wc file = do
      Stream.unfold File.readChunks file -- AheadT IO (Array Word8)
    & Stream.mapM partialCounts          -- AheadT IO (Bool, Counts)
    & Stream.maxThreads numCapabilities  -- AheadT IO (Bool, Counts)
    & Stream.fromAhead                   -- SerialT IO (Bool, Counts)
    & Stream.foldl' addCounts (False, Counts 0 0 0 True) -- IO (Bool, Counts)

Please note that the only difference between a concurrent and a non-concurrent program lies in the use of the Stream.fromAhead combinator. If we remove the call to Stream.fromAhead, we would still have a perfectly valid and performant serial program. Notice how succinctly and idiomatically we have expressed the concurrent word counting problem.

A benchmark with 2 CPUs:

$ time WordCount-hs-parallel gutenberg-500MB.txt
11242220 97050938 574714449 gutenberg-500MB.txt

real    0m1.284s
user    0m1.952s
sys     0m0.140s

These example programs have assumed ASCII encoded input data. For UTF-8 streams, we have a concurrent wc implementation with UTF-8 decoding. This concurrent implementation performs as well as the standard wc program in serial benchmarks. In concurrent mode Streamly’s implementation can utilise multiple processing cores if these are present, and can thereby run much faster than the standard binary.

Streamly provides concurrency facilities similar to OpenMP and Cilk but with a more declarative style of expression. With Streamly you can write concurrent programs with ease, with support for different types of concurrent scheduling.

A Concurrent Network Server

We now move to a slightly more complicated example: we simulate a dictionary lookup server which can serve word meanings to multiple clients concurrently. This example demonstrates the use of the concurrent mapM combinator.

Please see the file WordServer.hs for the complete code for this example, including the imports that we have omitted below.

import qualified Streamly.Data.Fold as Fold
import qualified Streamly.Network.Inet.TCP as TCP
import qualified Streamly.Network.Socket as Socket
import qualified Streamly.Unicode.Stream as Unicode

-- Simulate network/db query by adding a delay.
fetch :: String -> IO (String, String)
fetch w = threadDelay 1000000 >> return (w,w)

-- Read lines of whitespace separated list of words from a socket, fetch the
-- meanings of each word concurrently and return the meanings separated by
-- newlines, in same order as the words were received. Repeat until the
-- connection is closed.
lookupWords :: Socket -> IO ()
lookupWords sk =
      Stream.unfold Socket.read sk               -- SerialT IO Word8
    & Unicode.decodeLatin1                       -- SerialT IO Char
    & Stream.wordsBy isSpace Fold.toList         -- SerialT IO String
    & Stream.fromSerial                          -- AheadT  IO String
    & Stream.mapM fetch                          -- AheadT  IO (String, String)
    & Stream.fromAhead                           -- SerialT IO (String, String)
    & Stream.map show                            -- SerialT IO String
    & Stream.intersperse "\n"                    -- SerialT IO String
    & Unicode.encodeStrings Unicode.encodeLatin1 -- SerialT IO (Array Word8)
    & Stream.fold (Socket.writeChunks sk)        -- IO ()

serve :: Socket -> IO ()
serve sk = finally (lookupWords sk) (close sk)

-- | Run a server on port 8091. Accept and handle connections concurrently. The
-- connection handler is "serve" (i.e. lookupWords).  You can use "telnet" or
-- "nc" as a client to try it out.
main :: IO ()
main =
      Stream.unfold TCP.acceptOnPort 8091 -- SerialT IO Socket
    & Stream.fromSerial                   -- AsyncT IO ()
    & Stream.mapM serve                   -- AsyncT IO ()
    & Stream.fromAsync                    -- SerialT IO ()
    & Stream.drain                        -- IO ()

Merging Incoming Streams

In the next example, we show how to merge logs coming from multiple nodes in your network. These logs are merged at line boundaries and the merged logs are written to a file or to a network destination. This example uses the concatMapWith combinator to merge multiple streams concurrently.

Please see the file MergeServer.hs for the complete working code, including the imports that we have omitted below.

import qualified Streamly.Data.Unfold as Unfold
import qualified Streamly.Network.Socket as Socket

-- | Read a line stream from a socket.
-- Note: lines are buffered, and we could add a limit to the
-- buffering for safety.
readLines :: Socket -> SerialT IO (Array Char)
readLines sk =
    Stream.unfold Socket.read sk                 -- SerialT IO Word8
  & Unicode.decodeLatin1                         -- SerialT IO Char
  & Stream.splitWithSuffix (== '\n') Array.write -- SerialT IO String

recv :: Socket -> SerialT IO (Array Char)
recv sk = Stream.finally (liftIO $ close sk) (readLines sk)

-- | Starts a server at port 8091 listening for lines with space separated
-- words. Multiple clients can connect to the server and send streams of lines.
-- The server handles all the connections concurrently, merges the incoming
-- streams at line boundaries and writes the merged stream to a file.
server :: Handle -> IO ()
server file =
      Stream.unfold TCP.acceptOnPort 8090        -- SerialT IO Socket
    & Stream.concatMapWith Stream.parallel recv  -- SerialT IO (Array Char)
    & Stream.unfoldMany Array.read               -- SerialT IO Char
    & Unicode.encodeLatin1                       -- SerialT IO Word8
    & Stream.fold (Handle.write file)            -- IO ()

main :: IO ()
main = withFile "output.txt" AppendMode server

Listing Directories Recursively/Concurrently

Our next example lists a directory tree recursively, reading multiple directories concurrently.

This example uses the tree traversing combinator iterateMapLeftsWith. This combinator maps a stream generator on the Left values in its input stream (directory names in this case), feeding the resulting Left values back to the input, while it lets the Right values (file names in this case) pass through to the output. The Stream.ahead stream joining combinator then makes it iterate on the directories concurrently.

Please see the file ListDir.hs for the complete working code, including the imports that we have omitted below.

import Streamly.Internal.Data.Stream.IsStream (iterateMapLeftsWith)

import qualified Streamly.Prelude as Stream
import qualified Streamly.Internal.FileSystem.Dir as Dir (toEither)

-- Lists a directory as a stream of (Either Dir File).
listDir :: String -> SerialT IO (Either String String)
listDir dir =
      Dir.toEither dir               -- SerialT IO (Either String String)
    & Stream.map (bimap mkAbs mkAbs) -- SerialT IO (Either String String)

    where mkAbs x = dir ++ "/" ++ x

-- | List the current directory recursively using concurrent processing.
main :: IO ()
main = do
    hSetBuffering stdout LineBuffering
    let start = Stream.fromPure (Left ".")
    Stream.iterateMapLeftsWith Stream.ahead listDir start
        & Stream.mapM_ print

Rate Limiting

For bounded concurrent streams, a stream yield rate can be specified easily. For example, to print “tick” once every second you can simply write:

main :: IO ()
main =
      Stream.repeatM (pure "tick")  -- AsyncT IO String
    & Stream.timestamped            -- AsyncT IO (AbsTime, String)
    & Stream.avgRate 1              -- AsyncT IO (AbsTime, String)
    & Stream.fromAsync              -- SerialT IO (AbsTime, String)
    & Stream.mapM_ print            -- IO ()

Please see the file Rate.hs for the complete working code.

The concurrency of the stream is automatically controlled to match the specified rate. Streamly’s rate control works precisely even at throughputs as high as millions of yields per second.

For more sophisticated rate control needs please see the Streamly reference documentation.

Reactive Programming

Streamly supports reactive (time domain) programming because of its support for declarative concurrency. Please see the Streamly.Prelude module for time-specific combinators like intervalsOf, and folds like takeInterval in Streamly.Internal.Data.Fold. Please also see the pre-release sampling combinators in the Streamly.Internal.Data.Stream.IsStream.Top module for throttle and debounce like operations.

The examples AcidRain.hs and CirclingSquare.hs demonstrate reactive programming using Streamly.

More Examples

If you would like to view more examples, please visit the Streamly Examples web page.

Further Reading

Performance

As you have seen in the word count example above, Streamly offers highly modular abstractions for building programs while also offering the performance close to an equivalent (imperative) C program.

Streamly offers excellent performance even for byte-at-a-time stream operations using efficient abstractions like Unfolds and terminating Folds. Byte-at-a-time stream operations can simplify programming because the developer does not have to deal explicitly with chunking and re-combining data.

Streamly exploits GHC’s stream fusion optimizations (case-of-case and spec-constr) aggressively to achieve C-like speed, while also offering highly modular abstractions to developers.

Streamly will usually perform very well without any compiler plugins. However, we have fixed some deficiencies that we had noticed in GHC’s optimizer using a compiler plugin. We hope to fold these optimizations into GHC in the future; until then we recommend that you use this plugin for applications that are performance sensitive.

Benchmarks

We measured several Haskell streaming implementations using various micro-benchmarks. Please see the streaming benchmarks page for a detailed comparison of Streamly against other streaming libraries.

Our results show that Streamly is the fastest effectful streaming implementation on almost all the measured microbenchmarks. In many cases it runs up to 100x faster, and in some cases even 1000x faster than some of the tested alternatives. In some composite operation benchmarks Streamly turns out to be significantly faster than Haskell’s list implementation.

Note: If you can write a program in some other way or with some other language that runs significantly faster than what Streamly offers, please let us know and we will improve.

Notes

Streamly comes equipped with a very powerful set of abstractions to accomplish many kinds of programming tasks: it provides support for programming with streams and arrays, for reading and writing from the file system and from the network, for time domain programming (reactive programming), and for reacting to file system events using fsnotify.

Please view Streamly’s documentation for more information about Streamly’s features.

Concurrency

Streamly uses lock-free synchronization for achieving concurrent operation with low overheads. The number of tasks performed concurrently are determined automatically based on the rate at which a consumer is consuming the results. In other words, you do not need to manage thread pools or decide how many threads to use for a particular task. For CPU-bound tasks Streamly will try to keep the number of threads close to the number of CPUs available; for IO-bound tasks it will utilize more threads.

The parallelism available during program execution can be utilized with very little overhead even where the task size is very small, because Streamly will automatically switch between serial or batched execution of tasks on the same CPU depending on whichever is more efficient. Please see our concurrency benchmarks for more detailed performance measurements, and for a comparison with the async package.

Design Goals

Our goals for Streamly from the very beginning have been:

  1. To achieve simplicity by unifying abstractions.
  2. To offer high performance.

These goals are hard to achieve simultaneously because they are usually inversely related. We have spent many years trying to get the abstractions right without compromising performance.

Unfold is an example of an abstraction that we have created to achieve high performance when mapping streams on streams. Unfold allows stream generation to be optimized well by the compiler through stream fusion. A Fold with termination capability is another example which modularizes stream elimination operations through stream fusion. Terminating folds can perform many simple parsing tasks that do not require backtracking. In Streamly, Parsers are a natural extension to terminating Folds; Parsers add the ability to backtrack to Folds. Unification leads to simpler abstractions and lower cognitive overheads while also not compromising performance.

Credits

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

Please see the credits directory for a full list of contributors, credits and licenses.

Licensing

Streamly is an open source project available under a liberal BSD-3-Clause license

Contributing to Streamly

As an open project we welcome contributions:

Getting Support

Professional support is available for Streamly: please contact support@composewell.com.

You can also join our community chat channel on Gitter.

Changes

Changelog

0.8.0

See API Changelog for a complete list of signature changes and new APIs introduced.

Breaking changes

  • Streamly.Prelude
    • fold: this function may now terminate early without consuming the entire stream. For example, fold Fold.head stream would now terminate immediately after consuming the head element from stream. This may result in change of behavior in existing programs if the program relies on the evaluation of the full stream.
  • Streamly.Data.Unicode.Stream
    • The following APIs no longer throw errors on invalid input, use new APIs suffixed with a prime for strict behavior:
      • decodeUtf8
      • encodeLatin1
      • encodeUtf8
  • Streamly.Data.Fold:
    • Several instances have been moved to the Streamly.Data.Fold.Tee module, please use the Tee type to adapt to the changes.

Bug Fixes

  • Concurrent Streams: The monadic state for the stream is now propagated across threads. Please refer to #369 for more info.
  • Streamly.Prelude:
    • bracket, handle, and finally now also work correctly on streams that aren’t fully drained. Also, the resource acquisition and release is atomic with respect to async exceptions.
    • iterate, iterateM now consume O(1) space instead of O(n).
    • fromFoldableM is fixed to be concurrent.
  • Streamly.Network.Inet.TCP: accept and connect APIs now close the socket if an exception is thrown.
  • Streamly.Network.Socket: accept now closes the socket if an exception is thrown.

Enhancements

  • See API Changelog for a complete list of new modules and APIs introduced.
  • The Fold type is now more powerful, the new termination behavior allows to express basic parsing of streams using folds.
  • Many new Fold and Unfold APIs are added.
  • A new module for console IO APIs is added.
  • Experimental modules for the following are added:
    • Parsing
    • Deserialization
    • File system event handling (fsnotify/inotify)
    • Folds for streams of arrays
  • Experimental use-c-malloc build flag to use the c library malloc for array allocations. This could be useful to avoid pinned memory fragmentation.

Notable Internal/Pre-release API Changes

Breaking changes:

  • The Fold type has changed to accommodate terminating folds.
  • Rename: Streamly.Internal.Prelude => Streamly.Internal.Data.Stream.IsStream
  • Several other internal modules have been renamed and re-factored.

Bug fixes:

  • A bug was fixed in the conversion of MicroSecond64 and MilliSecond64 (commit e5119626)
  • Bug fix: classifySessionsBy now flushes sessions at the end and terminates.

Miscellaneous

  • Drop support for GHC 7.10.3.
  • The examples in this package are moved to a new github repo streamly-examples

0.7.3 (February 2021)

Build Issues

  • Fix build issues with primitive package version >= 0.7.1.
  • Fix build issues on armv7.

0.7.2 (April 2020)

Bug Fixes

  • Fix a bug in the Applicative and Functor instances of the Fold data type.

Build Issues

  • Fix a bug that occasionally caused a build failure on windows when used with stack or stack ghci.
  • Now builds on 32-bit machines.
  • Now builds with primitive package version >= 0.5.4 && <= 0.6.4.0
  • Now builds with newer QuickCheck package version >= 2.14 && < 2.15.
  • Now builds with GHC 8.10.

0.7.1 (February 2020)

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 (November 2019)

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 (March 2019)

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 (December 2018)

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 (October 2018)

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 (September 2018)

  • Performance improvements, especially space consumption, for concurrent streams

0.5.0 (September 2018)

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 (July 2018)

Bug Fixes

  • foldxM was not fully strict, fixed.

0.4.0 (July 2018)

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 (June 2018)

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 (June 2018)

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 (May 2018)

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 (March 2018)

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 (March 2018)

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 (December 2017)

  • Initial release