lossy-chan: Fast, bounded, and lossy broadcast channels backed by a ring buffer

[ bsd3, concurrency, library ] [ Propose Tags ] [ Report a vulnerability ]

Fast, bounded, and lossy broadcast channels backed by a ring buffer.


[Skip to Readme]

Modules

[Index] [Quick Jump]

Flags

Manual Flags

NameDescriptionDefault
small-loop-counter

Use Word8 instead of Word32 for the loop counter, for the purposes of testing loop counter overflows.

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.1.0, 0.2.0.0
Change log CHANGELOG.md
Dependencies base (>=4.16 && <5) [details]
Tested with ghc ==9.4.8 || ==9.6.7 || ==9.8.4 || ==9.10.3 || ==9.12.4 || ==9.14.1
License BSD-3-Clause
Copyright (c) 2026 Well-Typed
Author Wen Kokke
Maintainer wen@well-typed.com
Uploaded by wenkokke at 2026-11-19T16:43:38Z
Category Concurrency
Source repo head: git clone https://github.com/well-typed/lossy-chan.git
Distributions
Reverse Dependencies 1 direct, 2 indirect [details]
Downloads 12 total (12 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2026-11-19 [all 1 reports]

Readme for lossy-chan-0.2.0.0

[back to package description]

lossy-chan

This package provides fast, bounded, and lossy broadcast channels backed by a ring buffer.

As long as receivers keep up with senders, a lossy-chan acts as a regular channel. For example:

(i, o) <- LC.new 64       -- buffer size
for_ [0..1000] $ \m -> do
    LC.send i m
    m' <- LC.receive o
    assertM (m' == m)

If a receiver lags behind, it loses access to the oldest messages first. For example:

(i, o) <- LC.new 64
for_ [0..64] (LC.send i)  -- sends 65 messages
m' <- LC.receive o
assertM (m' == 1)         -- 0 was dropped

A lossy-chan channel is split into an input and an output channel, both of which are thread-safe. If you use a single output channel in two threads, the messages are split between the two. If you want two output channels that both receive every message, you can duplicate the output channel. The new output channel receives messages starting where the duplicated channel left off. For example:

(i, o1) <- LC.new 64
for_ [1,2] (LC.send i)

m1 <- LC.receive o1
assertM (m1 == 1)         -- receive the 1 on o1

o2 <- LC.dup o1           -- duplicate o1
m2 <- LC.receive o2       -- receive the 2 on o2
assertM (m2 == 2)

m2' <- LC.receive o1      -- receive the 2 on o1
assertM (m2' == 2)

Alternatively, you can create a new output channel from the input channel. In this case, the new output channel receives messages starting from the oldest live message. This is non-determinstic, as it depends on garbage collection. For example:

(i, _o) <- LC.new 64

-- if GC runs here, there won't be any live output
-- channels when send runs and the 1 is discarded.

LC.send i 1

-- if GC runs here, _o's finalizer removes the 1.

o <- LC.out i

-- if GC runs from here onwards, the 1 is kept.

LC.send i 2

m <- LC.receive o
assertM (m `elem` [1,2])

The lossy-chan buffer uses access counts to ensure that messages can be garbage collected as soon as they've been received by every output channel. This relies on finalizers and is not guaranteed to be prompt. For example:

(i, o) <- LC.new 64
LC.send i bigThing
void (LC.receive o)       -- bigThing can now be garbage collected

If the input channel is garbage collected, output channels can continue to receive values until they reach the end of the buffer, at which point receive will throw a NoInChanError. Alternatively, the GHC RTS may also throw a BlockedIndefinitelyOnSTM exception. For example:

(i, o) <- LC.new 64
LC.send i 1

m1 <- LC.receive o
assertM (m1 == 1)         -- receive the 1

m2 <- LC.receive o        -- throws NoInChanError or BlockedIndefinitelyOnSTM

Benchmarks

This section shows the results of time and space benchmarks that compare lossy-chan with various other channels implementations:

  • The base benchmark uses Control.Concurrent.Chan.
  • The stm benchmark uses Control.Concurrent.STM.TChan.
  • The unagi-chan benchmark uses Control.Concurrent.Chan.Unagi.
  • The lossy-chan-N benchmarks use Control.Concurrent.LossyChan with buffer size N.

The benchmark itself was adapted from the unagi-chan's benchmark, and consists of some number of sender threads, each of which sends 10,000 messages, and some number of receiver threads, each of which tries to receive 10,000 messages. Since lossy-chan channels may lose some messages, receiver threads terminate when they catch a NoInChanError or BlockedIndefinitelyOnSTM exception.

This isn't a fair comparison, since none of the other channel implementations is lossy. However, it should give you some idea of the performance and memory usage characteristics of lossy-chan.

Time

The time benchmark, created using criterion, shows that a lossy-chan channel is roughly as fast as an unagi-chan channel, and both are significantly faster than the base and stm channels. Moreover, the buffer size doesn't appear to significanly affect the performance of a lossy-chan channel.

Benchmark that compares run-time for lossy-chan with base, stm, and unagi-chan.

Space

The space benchmark, created using weigh, shows that a lossy-chan channel has much lower maximum residency when compared to the other channel implementations – so much so, that it had to be rendered in a separate plot. Moreover, lossy-chan's maximum residency scales up with the buffer size, as expected from the use of a ring buffer.

Benchmark that compares heap usage for lossy-chan with base, stm, and unagi-chan.