-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Rate limiter using lazy bucket algorithm
--   
--   This package provides a variant of a <a>Token Bucket</a> or <a>Leaky
--   Bucket</a> rate-limiting algorithm optimised for low overhead.
--   
--   The rate-limiting variant implemented by this package is heavily
--   inspired by the algorithm described in <a>"Rate Limiting at Webscale:
--   Lazy Leaky Buckets"</a>.
@package token-bucket
@version 0.1.0.1


-- | This module provides rate-limiting facilities built on top of the lazy
--   bucket algorithm heavily inspired by <a>"Rate Limiting at Webscale:
--   Lazy Leaky Buckets"</a>
--   
--   See also Wikipedia's <a>Token Bucket</a> article for general
--   information about token bucket algorithms and their properties.
module Control.Concurrent.TokenBucket

-- | Abstract type containing the token bucket state
data TokenBucket

-- | Create new <a>TokenBucket</a> instance
newTokenBucket :: IO TokenBucket

-- | Attempt to allocate a given amount of tokens from the
--   <a>TokenBucket</a>
--   
--   This operation either succeeds in allocating the requested amount of
--   tokens (and returns <a>True</a>), or else, if allocation fails the
--   <a>TokenBucket</a> remains in its previous allocation state.
tokenBucketTryAlloc :: TokenBucket -> Word64 -> Word64 -> Word64 -> IO Bool

-- | Try to allocate a single token from the token bucket.
--   
--   Returns 0 if successful (i.e. a token was successfully allocated from
--   the token bucket).
--   
--   On failure, i.e. if token bucket budget was exhausted, the minimum
--   non-zero amount of microseconds to wait till allocation <i>may</i>
--   succeed is returned.
--   
--   This function does not block. See <a>tokenBucketWait</a> for wrapper
--   around this function which blocks until a token could be allocated.
tokenBucketTryAlloc1 :: TokenBucket -> Word64 -> Word64 -> IO Word64

-- | Blocking wrapper around <a>tokenBucketTryAlloc1</a>. Uses
--   <a>threadDelay</a> when blocking.
--   
--   This is effectively implemented as
--   
--   <pre>
--   <a>tokenBucketWait</a> tb burst invRate = do
--     delay &lt;- <a>tokenBucketTryAlloc1</a> tb burst invRate
--     unless (delay == 0) $ do
--       threadDelay (fromIntegral delay)
--       <a>tokenBucketWait</a> tb burst invRate
--   </pre>
tokenBucketWait :: TokenBucket -> Word64 -> Word64 -> IO ()
instance GHC.Show.Show Control.Concurrent.TokenBucket.TBData
