Name:               broadcast-chan
Version:            0.2.1.1
X-Revision:         2

Homepage:           https://github.com/merijn/broadcast-chan
Bug-Reports:        https://github.com/merijn/broadcast-chan/issues

Author:             Merijn Verstraaten
Maintainer:         Merijn Verstraaten <merijn@inconsistent.nl>
Copyright:          Copyright © 2014-2020 Merijn Verstraaten

License:            BSD3
License-File:       LICENSE

Category:           System
Cabal-Version:      >= 1.10
Build-Type:         Simple
Tested-With:        GHC == 8.0.2, GHC == 8.2.2, GHC == 8.4.4, GHC == 8.6.5,
                    GHC == 8.8.4, GHC == 8.10.2

Extra-Source-Files: README.md
                  , CHANGELOG.md

Synopsis:           Closable, fair, single-wakeup channel type that avoids 0
                    reader space leaks.

Description:
    __WARNING:__ While the code in this library should be fairly stable and
    production, the API is something I'm still working on. API changes will
    follow the PVP, but __expect__ breaking API changes in future versions!
    .
    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.

Flag sync
  Description:        Benchmarks synchronisation primitives used in main
                      benchmark.
  Default:            False
  Manual:             True

Flag threaded
  Description:        Run benchmarks with threaded backend.
  Default:            True
  Manual:             True

Library
  Default-Language:     Haskell2010
  GHC-Options:          -Wall -O2 -fno-warn-unused-do-bind

  Exposed-Modules:      BroadcastChan
                        BroadcastChan.Extra
                        BroadcastChan.Prelude
                        BroadcastChan.Throw
  Other-Modules:        BroadcastChan.Internal

  Other-Extensions:     DataKinds
                        DeriveDataTypeable
                        KindSignatures
                        NamedFieldPuns
                        Safe
                        ScopedTypeVariables
                        Trustworthy
                        TupleSections

  Build-Depends:        base >= 4.8 && < 4.15
               ,        transformers >= 0.2 && < 0.6
               ,        unliftio-core >= 0.1.1 && < 0.3

Benchmark sync
  Default-Language:     Haskell2010
  Type:                 exitcode-stdio-1.0
  Main-Is:              Sync.hs
  GHC-Options:          -Wall -O2 -fno-warn-orphans -rtsopts
  if flag(threaded)
    GHC-Options:        -threaded
  Hs-Source-Dirs:       benchmarks

  Other-Extensions:     BangPatterns

  if flag(sync)
    Buildable:          True
  else
    Buildable:          False

  Build-Depends:        base
               ,        async >= 2.0 && < 2.3
               ,        atomic-primops == 0.8.*
               ,        criterion >= 1.2 && < 1.6
               ,        deepseq >= 1.1 && < 1.5
               ,        stm >= 2.4 && < 2.6

Benchmark channels
  Default-Language:     Haskell2010
  Type:                 exitcode-stdio-1.0
  Main-Is:              Channels.hs
  GHC-Options:          -Wall -O2 -fno-warn-orphans -fno-warn-unused-do-bind
                        -fno-warn-type-defaults -rtsopts
  if flag(threaded)
    GHC-Options:        -threaded

  Hs-Source-Dirs:       benchmarks

  Other-Extensions:     BangPatterns
                        DeriveGeneric
                        RecordWildCards

  Build-Depends:        base
               ,        broadcast-chan
               ,        async >= 2.0 && < 2.3
               ,        criterion >= 1.2 && < 1.6
               ,        deepseq >= 1.1 && < 1.5
               ,        stm >= 2.4 && < 2.6

Benchmark utilities
  Default-Language:     Haskell2010
  Type:                 exitcode-stdio-1.0
  Main-Is:              Utils.hs
  GHC-Options:          -Wall -O2 -fno-warn-orphans -fno-warn-unused-do-bind
                        -rtsopts
  if flag(threaded)
    GHC-Options:        -threaded
  Hs-Source-Dirs:       benchmarks

  Build-Depends:        base
               ,        broadcast-chan

Source-Repository head
  Type:     git
  Location: ssh://github.com:merijn/broadcast-chan.git