BSD-3-Clause licensed by Merijn Verstraaten
Maintained by Merijn Verstraaten
This version can be pinned in stack with:broadcast-chan-0.2.1.2@sha256:f252bf14a813a30db4be9a61854ed111a91a90605ee17da739363145aff61e1a,5910

Module documentation for 0.2.1.2

BroadcastChan: Closable, fair, single-wakeup, broadcast channels

BSD3 Hackage hackage-ci Stackage Build Status

A closable, fair, single-wakeup channel that avoids the 0 reader space leak that Control.Concurrent.Chan from base suffers from.

The Chan type from Control.Concurrent.Chan consists of both a read and write end combined into a single value. This means there is always at least 1 read end for a Chan, which keeps any values written to it alive. This is a problem for applications/libraries that want to have a channel that can have zero listeners.

Suppose we have an library that produces events and we want to let users register to receive events. If we use a channel and write all events to it, we would like to drop and garbage collect any events that take place when there are 0 listeners. The always present read end of Chan from base makes this impossible. We end up with a Chan that forever accumulates more and more events that will never get removed, resulting in a memory leak.

BroadcastChan splits channels into separate read and write ends. Any message written to a a channel with no existing read end is immediately dropped so it can be garbage collected. Once a read end is created, all messages written to the channel will be accessible to that read end.

Once all read ends for a channel have disappeared and been garbage collected, the channel will return to dropping messages as soon as they are written.

Why should I use BroadcastChan over Control.Concurrent.Chan?

  • BroadcastChan is closable,
  • BroadcastChan has no 0 reader space leak,
  • BroadcastChan has comparable or better performance.

Why should I use BroadcastChan over various (closable) STM channels?

  • BroadcastChan is single-wakeup,
  • BroadcastChan is fair,
  • BroadcastChan performs better under contention.

Changes

0.2.1.2 [2021.12.01]

  • Update bounds for GHC 9.0 and 9.2.
  • Hacky fix of a tricky race condition #3.

0.2.1.1 [2020.03.05]

  • Updated imports to support unliftio-core 0.2.x

0.2.1 [2019.11.17]

  • Adds ThreadBracket, runParallelWith, and runParallelWith_ to BroadcastChan.Extra to support thread related resource management. This is required to fix broadcast-chan-conduit’s use of MonadResource.

0.2.0.2 [2019.03.30]

  • GHC 8.6/MonadFail compatibility fix

0.2.0.1 [2018.09.24]

  • Loosen STM bounds for new stackage release.
  • Ditch GHC 7.6.3 support.

0.2.0 [2018.09.20]

  • Complete rework to be actually practical.
  • Switched to standalone module hierarchy.
  • Added functionality for parallel tasks.
  • Add module which uses exceptions, instead of results to signal failure.