Retracted: These v1 versions were published incorrectly. Retracting to prevent go mod
from automatically selecting them.
README
¶
Functions which run a given function as a memoryless Poisson process.
This is very useful if your function generates a gauge measurement or it exerts load on the system in some way. By distributing the measurement or load across time, we help ensure that our systems' data is minimally affected.
Documentation
¶
Overview ¶
Package memoryless helps repeated calls to a function be distributed across time in a memoryless fashion.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run calls the given function repeatedly, waiting a c.Expected amount of time between calls on average. The wait time is actually random and will generate a memoryless (Poisson) distribution of f() calls in time, ensuring that f() has the PASTA property (Poisson Arrivals See Time Averages). This statistical guarantee is subject to two caveats.
Caveat 1 is that, in a nod to the realities of systems needing to have guarantees, we allow the random wait time to be clamped both above and below. This means that calls to f() should be at least c.Min and at most c.Max apart in time. This clamping causes bias in the timing. For use of this function to be statistically sensible, the clamping should not be too extreme. The exact mathematical meaning of "too extreme" depends on your situation, but a nice rule of thumb is c.Min should be at most 10% of expected and c.Max should be at least 250% of expected. These values mean that less than 10% of time you will be waiting c.Min and less than 10% of the time you will be waiting c.Max.
Caveat 2 is that this assumes that the function f() takes negligible time to run when compared to the expected wait time. Technically memoryless events have the property that the times between successive event starts has the exponential distribution, and this code will not start a new call to f() before the old one has completed, which provides a lower bound on wait times.
Types ¶
type Config ¶
type Config struct {
// Expected records the expected/mean/average amount of time between runs.
Expected time.Duration
// Min provides clamping of the randomly produced value. All timers will wait
// at least Min time.
Min time.Duration
// Max provides clamping of the randomly produced value. All timers will take
// at most Max time.
Max time.Duration
// Once is provided as a helper, because frequently for unit testing and
// integration testing, you only want the "Forever" loop to run once.
//
// The zero value of this struct has Once set to false, which means the value
// only needs to be set explicitly in codepaths where it might be true.
Once bool
}
Config represents the time we should wait between runs of the function.
A valid config will have:
0 <= Min <= Expected <= Max (or 0 <= Min <= Expected and Max is 0)
Source Files