Control.Concurrent.TokenLimiter.Concurrent

Create

type Count = Word64

An amount of tokens

data TokenLimitConfig

A configuration for TokenLimiter

Constructors

TokenLimitConfig

Fields

• tokenLimitConfigInitialTokens :: !Count

  How many tokens should be in the bucket when it's created

• tokenLimitConfigMaxTokens :: !Count

  Maximum number of tokens the bucket can hold at any one time

• tokenLimitConfigTokensPerSecond :: !Count

  How many tokens are added to the bucket per second

Instances

Generic TokenLimitConfig

Defined in Control.Concurrent.TokenLimiter.Concurrent

Associated Types

type Rep TokenLimitConfig :: Type -> Type

Methods

from :: TokenLimitConfig -> Rep TokenLimitConfig x

to :: Rep TokenLimitConfig x -> TokenLimitConfig

Show TokenLimitConfig

Defined in Control.Concurrent.TokenLimiter.Concurrent

Methods

showsPrec :: Int -> TokenLimitConfig -> ShowS

show :: TokenLimitConfig -> String

showList :: [TokenLimitConfig] -> ShowS

Eq TokenLimitConfig

Defined in Control.Concurrent.TokenLimiter.Concurrent

Methods

(==) :: TokenLimitConfig -> TokenLimitConfig -> Bool

(/=) :: TokenLimitConfig -> TokenLimitConfig -> Bool

type Rep TokenLimitConfig

Defined in Control.Concurrent.TokenLimiter.Concurrent

type Rep TokenLimitConfig = D1 ('MetaData "TokenLimitConfig" "Control.Concurrent.TokenLimiter.Concurrent" "token-limiter-concurrent-0.1.0.0-DcHrU4XMkb37dFhrj1OAuv" 'False) (C1 ('MetaCons "TokenLimitConfig" 'PrefixI 'True) (S1 ('MetaSel ('Just "tokenLimitConfigInitialTokens") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Count) :*: (S1 ('MetaSel ('Just "tokenLimitConfigMaxTokens") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Count) :*: S1 ('MetaSel ('Just "tokenLimitConfigTokensPerSecond") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Count))))

type MonotonicTime = Word64

A type synonym for a number of "monotonic time" nanoseconds.

This only exists because it is also a Word64 and would be too easy to confuse with a Count.

data TokenLimiter

A token bucket-based rate limiter

This token limiter is thread-safe and guarantees that:

• There will be no thundering herd problem
• Fairness: Waiting processes will be serviced in a first-come first-service order.

Constructors

TokenLimiter

Fields

• tokenLimiterConfig :: !TokenLimitConfig
• tokenLimiterLastServiced :: !(MVar (MonotonicTime, Count))

  The last time the limiter was used, and what the token count was at that time.

  Not that this library assumes that you never put anything into this mvar yourself and only use the functions in this library to interact with it.

Instances

Generic TokenLimiter

Defined in Control.Concurrent.TokenLimiter.Concurrent

Associated Types

type Rep TokenLimiter :: Type -> Type

Methods

from :: TokenLimiter -> Rep TokenLimiter x

to :: Rep TokenLimiter x -> TokenLimiter

Eq TokenLimiter

Defined in Control.Concurrent.TokenLimiter.Concurrent

Methods

(==) :: TokenLimiter -> TokenLimiter -> Bool

(/=) :: TokenLimiter -> TokenLimiter -> Bool

type Rep TokenLimiter

Defined in Control.Concurrent.TokenLimiter.Concurrent

type Rep TokenLimiter = D1 ('MetaData "TokenLimiter" "Control.Concurrent.TokenLimiter.Concurrent" "token-limiter-concurrent-0.1.0.0-DcHrU4XMkb37dFhrj1OAuv" 'False) (C1 ('MetaCons "TokenLimiter" 'PrefixI 'True) (S1 ('MetaSel ('Just "tokenLimiterConfig") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TokenLimitConfig) :*: S1 ('MetaSel ('Just "tokenLimiterLastServiced") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (MVar (MonotonicTime, Count)))))

makeTokenLimiter :: TokenLimitConfig -> IO TokenLimiter

Make a token limiter

The initial number of tokens will be the minimum of the tokenLimitConfigInitialTokens and the tokenLimitConfigMaxTokens,

Use

tryDebit :: TokenLimiter -> Word64 -> IO Bool

Check if we can debit a number of tokens, and do it if possible.

The returned boolean represents whether the tokens were debited.

Note that there is a small race-condition in which tryDebit sometimes returns False eventhough it could (maybe) have debited because another thread was currently waitDebit-ing without actually waiting (because it didn't need to wait).

waitDebit :: TokenLimiter -> Word64 -> IO (Maybe MonotonicDiffNanos)

Wait until the given number of tokens can be debited.

Returns the time waited, for stats recording purposes.

Note: only reports the time waited due to rate-limiting this specific action, not the wall-clock time waited (that might include waiting for previous actions limited by this rate limiter to finish).

Note: debitor threads are serviced in FIFO order, so a request for a small (and currently satisfiable) number of tokens can still be delayed by a debit request for a larger amount of tokens.

Note: the wait time reported can be inflated due to scheduling inaccuracy. See https://gitlab.haskell.org/ghc/ghc/-/issues/16601.

newtype MonotonicDiffNanos

Constructors

MonotonicDiffNanos

Fields

• unMonotonicDiffNanos :: Word64

Instances

Generic MonotonicDiffNanos

Defined in Control.Concurrent.TokenLimiter.Concurrent

Associated Types

type Rep MonotonicDiffNanos :: Type -> Type

Methods

from :: MonotonicDiffNanos -> Rep MonotonicDiffNanos x

to :: Rep MonotonicDiffNanos x -> MonotonicDiffNanos

Show MonotonicDiffNanos

Defined in Control.Concurrent.TokenLimiter.Concurrent

Methods

showsPrec :: Int -> MonotonicDiffNanos -> ShowS

show :: MonotonicDiffNanos -> String

showList :: [MonotonicDiffNanos] -> ShowS

Eq MonotonicDiffNanos

Defined in Control.Concurrent.TokenLimiter.Concurrent

Methods

(==) :: MonotonicDiffNanos -> MonotonicDiffNanos -> Bool

(/=) :: MonotonicDiffNanos -> MonotonicDiffNanos -> Bool

Ord MonotonicDiffNanos

Defined in Control.Concurrent.TokenLimiter.Concurrent

Methods

compare :: MonotonicDiffNanos -> MonotonicDiffNanos -> Ordering

(<) :: MonotonicDiffNanos -> MonotonicDiffNanos -> Bool

(<=) :: MonotonicDiffNanos -> MonotonicDiffNanos -> Bool

(>) :: MonotonicDiffNanos -> MonotonicDiffNanos -> Bool

(>=) :: MonotonicDiffNanos -> MonotonicDiffNanos -> Bool

max :: MonotonicDiffNanos -> MonotonicDiffNanos -> MonotonicDiffNanos

min :: MonotonicDiffNanos -> MonotonicDiffNanos -> MonotonicDiffNanos

type Rep MonotonicDiffNanos

Defined in Control.Concurrent.TokenLimiter.Concurrent

type Rep MonotonicDiffNanos = D1 ('MetaData "MonotonicDiffNanos" "Control.Concurrent.TokenLimiter.Concurrent" "token-limiter-concurrent-0.1.0.0-DcHrU4XMkb37dFhrj1OAuv" 'True) (C1 ('MetaCons "MonotonicDiffNanos" 'PrefixI 'True) (S1 ('MetaSel ('Just "unMonotonicDiffNanos") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word64)))

Helper functions

computeCurrentCount :: TokenLimitConfig -> MonotonicTime -> Count -> MonotonicTime -> Count

Compute the current number of tokens in a bucket purely.

You should not need this function.