Safe Haskell	Safe-Inferred
Language	Haskell2010

Ouroboros.Consensus.Util.LeakyBucket

Description

This module implements a “leaky bucket”. One defines a bucket with a capacity and a leaking rate; a race (in the sense of Async) starts against the bucket which leaks at the given rate. The user is provided with a function to refill the bucket by a certain amount. If the bucket ever goes empty, both threads are cancelled.

This can be used for instance to enforce a minimal rate of a peer: they race against the bucket and refill the bucket by a certain amount whenever they do a “good” action.

NOTE: Even though the imagery is the same, this is different from what is usually called a “token bucket” or “leaky bucket” in the litterature where it is mostly used for rate limiting.

REVIEW: Could be used as leaky bucket used for rate limiting algorithms. All the infrastructure is here (put onEmpty to pure () and you're good to go) but it has not been tested with that purpose in mind.

Synopsis

data Config m = Config {
- capacity ∷ !Rational
- rate ∷ !Rational
- fillOnOverflow ∷ !Bool
- onEmpty ∷ !(m ())
}
data Handlers m = Handlers {
- fill ∷ !(Rational → m FillResult)
- setPaused ∷ !(Bool → m ())
- updateConfig ∷ !((Config m → Config m) → m ())
}
data State cfg = State {
- level ∷ !Rational
- time ∷ !Time
- paused ∷ !Bool
- config ∷ !cfg
}
diffTimeToSecondsRational ∷ DiffTime → Rational
dummyConfig ∷ Applicative m ⇒ Config m
evalAgainstBucket ∷ (MonadDelay m, MonadAsync m, MonadFork m, MonadMask m, NoThunks (m ())) ⇒ Config m → (Handlers m → m a) → m (State (Config m))
execAgainstBucket ∷ (MonadDelay m, MonadAsync m, MonadFork m, MonadMask m, NoThunks (m ())) ⇒ Config m → (Handlers m → m a) → m a
runAgainstBucket ∷ ∀ m a. (MonadDelay m, MonadAsync m, MonadFork m, MonadMask m, NoThunks (m ())) ⇒ Config m → (Handlers m → m a) → m (State (Config m), a)
secondsRationalToDiffTime ∷ Rational → DiffTime

Documentation

data Config m Source #

Configuration of a leaky bucket.

Constructors

Config
Fields capacity ∷ !Rational Initial and maximal capacity of the bucket, in number of tokens. rate ∷ !Rational Tokens per second leaking off the bucket. fillOnOverflow ∷ !Bool Whether to fill to capacity on overflow or to do nothing. onEmpty ∷ !(m ()) A monadic action to trigger when the bucket is empty.

Instances

Instances details

Generic (Config m) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket Associated Types type Rep (Config m) ∷ Type → Type # Methods from ∷ Config m → Rep (Config m) x # to ∷ Rep (Config m) x → Config m #
NoThunks (m ()) ⇒ NoThunks (Config m) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket Methods noThunks ∷ Context → Config m → IO (Maybe ThunkInfo) Source # wNoThunks ∷ Context → Config m → IO (Maybe ThunkInfo) Source # showTypeOf ∷ Proxy (Config m) → String Source #
type Rep (Config m) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket type Rep (Config m) = D1 ('MetaData "Config" "Ouroboros.Consensus.Util.LeakyBucket" "ouroboros-consensus-0.18.0.0-inplace" 'False) (C1 ('MetaCons "Config" 'PrefixI 'True) ((S1 ('MetaSel ('Just "capacity") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Rational) :: S1 ('MetaSel ('Just "rate") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Rational)) :: (S1 ('MetaSel ('Just "fillOnOverflow") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool) :*: S1 ('MetaSel ('Just "onEmpty") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (m ())))))

data Handlers m Source #

The handlers to a bucket: contains the API to interact with a running bucket.

Constructors

Handlers

Fields

fill ∷ !(Rational → m FillResult)
Refill the bucket by the given amount and returns whether the bucket overflew. The bucket may silently get filled to full capacity or not get filled depending on fillOnOverflow.
setPaused ∷ !(Bool → m ())
Pause or resume the bucket. Pausing stops the bucket from leaking until it is resumed. It is still possible to fill it during that time. setPaused True and setPaused False are idempotent.
updateConfig ∷ !((Config m → Config m) → m ())
Dynamically update the configuration of the bucket.

data State cfg Source #

State of a leaky bucket, giving the level and the associated time.

Constructors

State
Fields level ∷ !Rational time ∷ !Time paused ∷ !Bool config ∷ !cfg

Instances

Instances details

Generic (State cfg) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket Associated Types type Rep (State cfg) ∷ Type → Type # Methods from ∷ State cfg → Rep (State cfg) x # to ∷ Rep (State cfg) x → State cfg #
Show cfg ⇒ Show (State cfg) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket Methods showsPrec ∷ Int → State cfg → ShowS # show ∷ State cfg → String # showList ∷ [State cfg] → ShowS #
Eq cfg ⇒ Eq (State cfg) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket Methods (==) ∷ State cfg → State cfg → Bool # (/=) ∷ State cfg → State cfg → Bool #
NoThunks cfg ⇒ NoThunks (State cfg) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket Methods noThunks ∷ Context → State cfg → IO (Maybe ThunkInfo) Source # wNoThunks ∷ Context → State cfg → IO (Maybe ThunkInfo) Source # showTypeOf ∷ Proxy (State cfg) → String Source #
type Rep (State cfg) Source #
Instance details Defined in Ouroboros.Consensus.Util.LeakyBucket type Rep (State cfg) = D1 ('MetaData "State" "Ouroboros.Consensus.Util.LeakyBucket" "ouroboros-consensus-0.18.0.0-inplace" 'False) (C1 ('MetaCons "State" 'PrefixI 'True) ((S1 ('MetaSel ('Just "level") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Rational) :: S1 ('MetaSel ('Just "time") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Time)) :: (S1 ('MetaSel ('Just "paused") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool) :*: S1 ('MetaSel ('Just "config") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 cfg))))

diffTimeToSecondsRational ∷ DiffTime → Rational Source #

Convert a DiffTime to a Rational number of seconds. This is similar to diffTimeToSeconds but with picoseconds precision.

dummyConfig ∷ Applicative m ⇒ Config m Source #

A configuration for a bucket that does nothing.

evalAgainstBucket ∷ (MonadDelay m, MonadAsync m, MonadFork m, MonadMask m, NoThunks (m ())) ⇒ Config m → (Handlers m → m a) → m (State (Config m)) Source #

Same as execAgainstBucket but returns the State of the bucket when the action terminates. Exposed for testing purposes.

execAgainstBucket ∷ (MonadDelay m, MonadAsync m, MonadFork m, MonadMask m, NoThunks (m ())) ⇒ Config m → (Handlers m → m a) → m a Source #

Create a bucket with the given configuration, then run the action against that bucket. Returns when the action terminates or the bucket empties. In the first case, return the value returned by the action. In the second case, return Nothing.

runAgainstBucket ∷ ∀ m a. (MonadDelay m, MonadAsync m, MonadFork m, MonadMask m, NoThunks (m ())) ⇒ Config m → (Handlers m → m a) → m (State (Config m), a) Source #

Same as execAgainstBucket but also returns the State of the bucket when the action terminates. Exposed for testing purposes.

secondsRationalToDiffTime ∷ Rational → DiffTime Source #

Alias of realToFrac to make code more readable and typing more explicit.