Control.Concurrent.TokenLimiter

Fast rate-limiting via token bucket algorithm. Uses lock-free compare-and-swap operations on the fast path when debiting tokens.

Documentation

type Count = Int

data LimitConfig

Constructors

LimitConfig

Fields

• maxBucketTokens :: !Count

  maximum number of tokens the bucket can hold at any one time.

• initialBucketTokens :: !Count

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

• bucketRefillTokensPerSecond :: !Count

  how many tokens should replenish the bucket per second.

• clockAction :: IO TimeSpec

  clock action, defaultLimitConfig uses the coarse monotonic system clock. Mostly provided for mocking in the testsuite.

• delayAction :: TimeSpec -> IO ()

  action to delay for the given time interval. defaultLimitConfig forwards to threadDelay. Provided for mocking.

Instances

Generic LimitConfig

Defined in Control.Concurrent.TokenLimiter

Associated Types

type Rep LimitConfig :: Type -> Type

Methods

from :: LimitConfig -> Rep LimitConfig x

to :: Rep LimitConfig x -> LimitConfig

type Rep LimitConfig

Defined in Control.Concurrent.TokenLimiter

type Rep LimitConfig = D1 (MetaData "LimitConfig" "Control.Concurrent.TokenLimiter" "token-limiter-0.2.0.0-F9Jxvy0ZYWPK1TDfbudvBY" False) (C1 (MetaCons "LimitConfig" PrefixI True) ((S1 (MetaSel (Just "maxBucketTokens") SourceUnpack SourceStrict DecidedStrict) (Rec0 Count) :*: S1 (MetaSel (Just "initialBucketTokens") SourceUnpack SourceStrict DecidedStrict) (Rec0 Count)) :*: (S1 (MetaSel (Just "bucketRefillTokensPerSecond") SourceUnpack SourceStrict DecidedStrict) (Rec0 Count) :*: (S1 (MetaSel (Just "clockAction") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (IO TimeSpec)) :*: S1 (MetaSel (Just "delayAction") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (TimeSpec -> IO ()))))))

data RateLimiter

newRateLimiter :: LimitConfig -> IO RateLimiter

tryDebit :: LimitConfig -> RateLimiter -> Count -> IO Bool

Attempt to pull the given number of tokens from the bucket. Returns True if the tokens were successfully debited.

penalize :: RateLimiter -> Count -> IO Count

Unconditionally debit this amount of tokens from the rate limiter, driving it negative if necessary. Returns the new bucket balance.

Since: 0.2

waitDebit :: LimitConfig -> RateLimiter -> Count -> IO ()

Attempt to pull k tokens from the bucket, sleeping in a loop until they become available. Will not partially fulfill token requests (i.e. it loops until the entire allotment is available in one swoop), and makes no attempt at fairness or queueing (i.e. you will probably get "thundering herd" on wakeup if a number of threads are contending for fresh tokens).

defaultLimitConfig :: LimitConfig