streamly

Streaming, dataflow programming and declarative concurrency

https://streamly.composewell.com

Version on this page:0.9.0
LTS Haskell 23.0:0.10.1@rev:4
Stackage Nightly 2024-12-09:0.10.1@rev:4
Latest on Hackage:0.10.1@rev:4

See all snapshots streamly appears in

BSD-3-Clause licensed by Composewell Technologies
Maintained by [email protected]
This version can be pinned in stack with:streamly-0.9.0@sha256:8aedb49557487a3f642f6e4cc55830dc0832928f298e016e82e92e68da07f43f,19866

Module documentation for 0.9.0

Streamly: Idiomatic Haskell with C-Like Performance

Gitter chat Hackage

Streamly is a powerful Haskell library that provides developers with the essential building blocks to create safe, scalable, modular, and high-performance software. With Streamly, developers can enjoy the benefits of Haskell’s type safety while leveraging C-like program performance. Streamly offers a comprehensive range of features, comprising:

  • Haskell’s strong type safety.
  • C-program-like performance capabilities.
  • Flexible, modular building blocks.
  • Idiomatic functional programming.
  • Fearless, declarative concurrency for seamless parallel execution.
  • A collection of ecosystem libraries for fast and efficient development.

Check out the Streamly Setup and Usage Guide and Quick Overview for an introduction to the library. For more detailed documentation, visit the Haskell Streamly website.

Blazing Fast

Streamly delivers C-like speed in Haskell by fusing stream pipelines using the stream-fusion technique, resulting in compiled code that is equivalent to handwritten C code, eliminating intermediate allocations and function calls.

For a comprehensive comparison of Streamly to other Haskell streaming libraries, check out our streaming benchmarks page. In fact, Streamly’s fused loops can be up to 100 times faster than those of libraries without stream fusion.

Declarative Concurrency

Streamly introduces declarative concurrency to standard functional streaming abstractions. Declarative concurrency abstracts away the low-level details of concurrency management, such as locks and threads, and allows for easier and safer parallelization of code. For example, with Streamly you can do things like repeat actions concurrently to generate a stream of results, map functions concurrently on a stream, and combine multiple streams concurrently to create a single output stream.

Unified API

Streamly provides a comprehensive and unified API for basic programming needs, covering a wide range of areas including streaming, concurrency, logic programming, reactive programming, pinned and unpinned arrays, serialization, builders, parsers, unicode processing, file-io, file system events, and network-io. By unifying functionality from disparate Haskell libraries, Streamly simplifies development while delivering equivalent or improved performance. Additionally, the complexity of handling combinations of lazy, strict, bytestring, and text is eliminated by using streams for lazy evaluation, and by generalizing bytestring and text to arrays.

Check out Streamly’s documentation for more information about Streamly’s features.

Batteries Included

In addition to the fundamental programming constructs, Streamly also provides higher-level functionality through supporting packages such as streamly-process, streamly-shell, and streamly-coreutils that are essential for general programming tasks. Check out the streamly-examples repository for some program snippets.

Highly Modular

Traditionally, you must choose between modularity and performance when writing code. However, with Haskell Streamly, you can have the best of both worlds. By taking advantage of GHC’s stream fusion optimizations (such as case-of-case and spec-constr), Streamly achieves performance comparable to an equivalent C program while still allowing for highly modular code.

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 [email protected].

You can also join our community chat channel on Gitter.

Changes

Changelog

0.9.0 (Mar 2023)

Also see the following:

Package split

streamly package is split into two packages, (1) streamly-core that has only GHC boot library depdendecies, and (2) streamly that contains higher level operations (including concurrent ones) with additional dependencies. Make sure you add a dependency on streamly-core to keep old code working.

  • Moved the following modules from streamly package to the streamly-core package:
    • Streamly.Console.Stdio
    • Streamly.Data.Fold
    • Streamly.Data.Unfold
    • Streamly.FileSystem.Handle
    • Streamly.Unicode.Stream

Breaking Changes

  • Unboxed arrays now require Unbox constraint instead of Storable. The Unbox typeclass can be imported from Streamly.Data.Array. You can use generic deriving to derive Unbox instances.
  • Stream type in all modules has been changed to the new Stream type replacing the existing IsStream t or SerialT types. Use fromStream, toStream from Streamly.Prelude module to adapt the types.
  • Signatures changed in Streamly.Data.Unfold:
    • fromStream
    • replicateM

Major Changes

Streamly.Prelude module has been deprecated, equivalent functionality is covered by the Streamly.Data.Stream, Streamly.Data.Stream.Prelude, and Streamly.Data.Fold modules. The new modules use a monomorphic Stream type instead of the polymorphic IsStream t type.

Streamly.Data.Stream module and the Stream type are meant for writing high-performance fused pipelines not involving explicit recursion. For writing code that may require recursive function calls, Streamly.Data.Stream.StreamK module and the StreamK type have been added which provide a CPS based stream implementation. Stream and StreamK types can be easily interconverted.

The old code can be adapted to use the new modules with some changes. See the upgrade guide for more details on how to adapt your existing code to the new release.

Enhancements

  • Added the following new modules to the streamly package:
    • Streamly.Data.Stream.MkType
    • Streamly.Data.Stream.Prelude
  • Added the following new modules to the streamly-core package:
    • Streamly.Data.Array
    • Streamly.Data.Array.Generic
    • Streamly.Data.MutArray
    • Streamly.Data.MutArray.Generic
    • Streamly.Data.Parser
    • Streamly.Data.ParserK
    • Streamly.Data.Stream
    • Streamly.Data.StreamK
    • Streamly.FileSystem.Dir
    • Streamly.FileSystem.File
    • Streamly.Unicode.Parser
    • Streamly.Unicode.String

Deprecations

  • Remove support for GHC 8.4.*

Several modules and functions have been deprecated, equivalent modules or functions are suggested in the deprecation warning messages by the compiler.

Internal module changes

If you cannot find an internal module that you were using, it may have been moved to the streamly-core package or may have been renamed.

Following modules are moved to streamly-core package and renamed:

  • Streamly.Internal.Data.Array.Stream.Foreign -> Streamly.Internal.Data.Stream.Chunked
  • Streamly.Internal.Data.Array.Stream.Mut.Foreign -> Streamly.Internal.Data.Array.Mut.Stream

0.8.3 (September 2022)

  • Fix build with GHC 9.4

0.8.2 (Mar 2022)

  • Fix performance issues for GHC-9. These changes coupled with GHC changes expected to land in 9.2.2 will bring the performance back to the same levels as before.

0.8.1.1 (Dec 2021)

  • Disable building FileSystem.Events where FS Events isn’t supported.

0.8.1 (Nov 2021)

See ApiChangelogs/0.8.3.txt for new APIs introduced.

Bug Fixes

  • Several bug fixes in the Array module:
    • Fix writeN fold eating away one element when applied multiple times #1258.
    • Fix potentially writing beyond allocated memory when shrinking. Likely cause of #944.
    • Fix potentially writing beyond allocated memory when writing the last element. Likely cause of #944.
    • Fix missing pointer touch could potentially cause use of freed memory.
    • Fix unnecessary additional allocation due to a bug
  • Fix a bug in classifySessionsBy, see PR #1311. The bug could cause premature ejection of a session when input events with the same key are split into multiple sessions.

Notable Internal API Changes

  • tapAsync from Streamly.Internal.Data.Stream.Parallel has been moved to Streamly.Internal.Data.Stream.IsStream and renamed to tapAsyncK.
  • Fold2 has now been renamed to Refold and the corresponding Fold2 combinators have been either renamed or removed.

0.8.0 (Jun 2021)

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