unagi-chan

Fast concurrent queues with a Chan-like API, and more

LTS Haskell 22.37:0.4.1.4
Stackage Nightly 2024-10-09:0.4.1.4
Latest on Hackage:0.4.1.4

See all snapshots unagi-chan appears in

BSD-3-Clause licensed by Brandon Simmons
Maintained by [email protected]
This version can be pinned in stack with:unagi-chan-0.4.1.4@sha256:e9a282689a65fc66260557222789d14dcb7d299be0ab2d4e8e414b0d9f2ef459,8813
Used by 1 package in lts-20.24(full list with versions):

This library provides implementations of concurrent FIFO queues (for both general boxed and primitive unboxed values) that are fast, perform well under contention, and offer a Chan-like interface. The library may be of limited usefulness outside of x86 architectures where the fetch-and-add instruction is not available.

We export several variations of our design; some support additional functionality while others try for lower latency by removing features or making them more restrictive (e.g. in the Unboxed variants).

  • Unagi: a general-purpose near drop-in replacement for Chan.

  • Unagi.Unboxed: like Unagi but specialized for primitive types; this may perform better if a queue grows very large.

  • Unagi.Bounded: a bounded variant with blocking and non-blocking writes, and other functionality where a notion of the queue's capacity is required.

  • Unagi.NoBlocking: lowest latency implementations for when blocking reads aren't required.

  • Unagi.NoBlocking.Unboxed: like Unagi.NoBlocking but for primitive types.

Some of these may be deprecated in the future if they are found to provide little performance benefit, or no unique features; you should benchmark and experiment with them for your use cases, and please submit pull requests for additions to the benchmark suite that reflect what you find.

Here is an example benchmark measuring the time taken to concurrently write and read 100,000 messages, with work divided amongst increasing number of readers and writers, comparing against the top-performing queues in the standard libraries. The inset graph shows a zoomed-in view on the implementations here.

Changes

0.1.1.0

  • support new criterion and GHC 7.8.3
  • small performance improvement to boxed unagi

0.2.0.0

  • implement a bounded variant (See issue #1)
  • address issue with stale tickets when running in GHCi

0.2.0.1

  • conditionally use tryReadMVar (as before) when GHC >= 7.8.3
  • set proper CPP flags when running tests

0.3.0.0

  • fixed build on GHC 7.6 (thanks @Noeda)
  • Unagi.Unboxed is now polymorphic in a new UnagiPrim class, which permits an optimization; defined instances are the same
  • add new NoBlocking variants with reads that don’t block, omiting some overhead
    • these have a new Stream interface for reads with even lower overhead
  • revisited memory barriers in light of https://github.com/rrnewton/haskell-lockfree/issues/39, and document them better
  • Added tryReadChan functions to all variants
  • get rid of upper bounds on atomic-primops

0.3.0.1

  • fix upper bounds on atomic-primops again (made as revision to cabal metadata for 0.3.0.0
  • fix some docs

0.3.0.2

  • re-bump atomic-primops version; should now support 7.10
  • fix missing other-modules for test suite
  • fix getChanContents for GHC 7.10 (see GHC Trac #9965)

0.4.0.0

  • tryReadChan now returns an (Element a, IO a) tuple, where the snd is a blocking read action
  • depend atomic-primops >= 0.8

0.4.1.0

  • add non-atomic estimatedLength, thanks to danclien