cabal-version:      3.0
-- The cabal-version field refers to the version of the .cabal specification,
-- and can be different from the cabal-install (the tool) version and the
-- Cabal (the library) version you are using. As such, the Cabal (the library)
-- version used must be equal or greater than the version stated in this field.
-- Starting from the specification version 2.2, the cabal-version field must be
-- the first thing in the cabal file.

-- Initial package description 'haskell-trottle' generated by
-- 'cabal init'. For further documentation, see:
--   http://haskell.org/cabal/users-guide/
--
-- The name of the package.
name:               haskell-throttle

-- The package version.
-- See the Haskell package versioning policy (PVP) for standards
-- guiding when and how versions should be incremented.
-- https://pvp.haskell.org
-- PVP summary:     +-+------- breaking API changes
--                  | | +----- non-breaking API additions
--                  | | | +--- code changes with no API change
version:            0.1.0.1

-- A short (one-line) description of the package.
synopsis: A simple throttling library, which drops messages from same group.

-- A longer description of the package.
description:
  A [throttle](https://en.wikipedia.org/wiki/Rate_limiting)
  implementation using
  [Control.Concurrent.STM.TChan](https://hackage.haskell.org/package/stm-2.5.3.1/docs/Control-Concurrent-STM-TChan.html).
  
  == Rationale
  
  Current Haskell throttle implementations
  (e.g. [Data.Conduit.Throttle](https://hackage.haskell.org/package/conduit-throttle-0.3.1.0/docs/Data-Conduit-Throttle.html)
  or [io-throttle](https://hackage.haskell.org/package/io-throttle))
  work by just __slowing down__ incoming messages. However, sometimes we
  don't care about delivering __all__ messages, but just want to limit
  their rate. Hence this module is born.
  
  The main function is in
  [Control.Concurrent.Throttle](./src/Control/Concurrent/Throttle.hs):
  
    throttle :: (Ord id, Eq id, Show id) => Int -> TChan.TChan (id, a) -> (a -> IO ()) -> IO ()
  
  It takes as arguments:
  
  * resolution (in milliseconds)
  * a ``TChan`` where `(id, a)` tuples are sent
  * ``action`` which, for given ``a`` calls some ``IO`` action
  
  In the above we have 2 types:
  
  * ``a`` represents the incoming message which will be called with the supplied `action`
  * ``id`` represents some identifier associated with the message. By
    using this ``id`` we can perform grouping of messages and throttle
    them accordingly.
    
  The ``throttle`` function itself should be spawned in a separate
  thread. It then awaits for incoming messages on the given `TChan`.
    
  See [test directory](./test) for a sample usage.
  
  == Design
  
  Currently, the ``throttle`` function spawns a ``mapCleaner`` thread
  which, periodically, checks the internal ``TVar`` value for values to
  clean up and values to hold before the given delay happens.
  
        
-- The license under which the package is released.
license:            AGPL-3.0-or-later

-- The file containing the license text.
license-file:       LICENSE

-- The package author(s).
author:             Przemysław Kamiński

-- An email address to which users can send suggestions, bug reports, and patches.
maintainer:         pk@intrepidus.pl

homepage: https://gitlab.iscpif.fr/gargantext/haskell-throttle
bug-reports: https://gitlab.iscpif.fr/gargantext/haskell-throttle/issues
                    
-- A copyright notice.
-- copyright:
category:           Concurrency
build-type:         Simple

-- Extra doc files to be distributed with the package, such as a CHANGELOG or a README.
extra-doc-files:    CHANGELOG.md

-- Extra source files to be distributed with the package, such as examples, or a tutorial module.
-- extra-source-files:

common warnings
    ghc-options: -Wall

library
    -- Import common warning flags.
    import:           warnings

    -- Modules exported by the library.
    exposed-modules:  Control.Concurrent.Throttle

    -- Modules included in this library but not exported.
    -- other-modules:

    -- LANGUAGE extensions used by modules in this package.
    default-extensions: ImportQualifiedPost
                      , OverloadedStrings
                      , ScopedTypeVariables

    -- Other library packages from which modules are imported.
    build-depends:    base ^>=4.17.2.0
                    , async >= 2.2 && < 2.3
                    , containers >= 0.6 && < 0.8
                    , stm >= 2.5 && < 2.6
                    , time >= 1.14 && < 2

    -- Directories containing source files.
    hs-source-dirs:   src

    -- Base language which the package is written in.
    default-language: Haskell2010

test-suite haskell-trottle-test
    -- Import common warning flags.
    import:           warnings

    -- Base language which the package is written in.
    default-language: Haskell2010

    -- Modules included in this executable, other than Main.
    -- other-modules:

    -- LANGUAGE extensions used by modules in this package.
    default-extensions: ImportQualifiedPost
                      , OverloadedStrings
                      , ScopedTypeVariables

    -- The interface type and version of the test suite.
    type:             exitcode-stdio-1.0

    -- Directories containing source files.
    hs-source-dirs:   test

    -- The entrypoint to the test suite.
    main-is:          Main.hs

    -- Test dependencies.
    build-depends:
          base ^>=4.17.2.0
        , haskell-trottle
        , async >= 2.2 && < 2.3
        , containers >= 0.6 && < 0.8
        , stm >= 2.5 && < 2.6
        , tasty >= 1.5 && < 1.6
        , tasty-hunit >= 0.10 && < 0.11
        , time >= 1.14 && < 2