Add wait_golden_jitter: deterministic low-discrepancy jitter strategy#642
Open
F4V3L4 wants to merge 3 commits into
Open
Add wait_golden_jitter: deterministic low-discrepancy jitter strategy#642F4V3L4 wants to merge 3 commits into
wait_golden_jitter: deterministic low-discrepancy jitter strategy#642F4V3L4 wants to merge 3 commits into
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
A002 is not enabled in the project's ruff config, so the `# noqa: A002` suppressions on `min` and `max` parameters were reported as unused by `ruff check`. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The tests for low-discrepancy and distinct-phase properties accessed `_phase` directly. Since `phase` is a meaningful observable value (the golden-ratio offset for a given seq_index), exposing it publicly is cleaner than suppressing the SLF001 lint rule. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add
wait_golden_jitter: deterministic low-discrepancy jitter strategySummary
This PR adds a new wait strategy,
wait_golden_jitter, providing adeterministic low-discrepancy alternative to the existing random jitter
strategies (
wait_random_exponential/ "Full Jitter").It keeps the same exponentially expanding backoff window as
wait_random_exponential, but selects each waiter's delay from thegolden-ratio low-discrepancy sequence (indexed by a caller-supplied
seq_index) instead of drawing it at random.Motivation
The existing jitter strategies break retry synchronization using randomness.
Random draws are statistically "clumpy": by chance, several waiters land in
the same time window, producing concurrency peaks larger than necessary. The
golden ratio is the most irrational number, so its additive recurrence
distributes points across the window as evenly as possible (Weyl
equidistribution / three-distance theorem).
This offers three properties the random strategies cannot:
waiters is controlled, not luck-dependent.
makes retry behavior testable and debuggable (random jitter is not).
(host id, shard, worker number) but a strong RNG is not (embedded/IoT).
This is complementary to the random strategies, not a replacement. Where
callers cannot provide distinct indices, the random strategies remain the
right default.
Benchmark
Thundering-herd simulation, peak concurrency (lower is better), same
exponential window for both, 300 trials:
Mean peak is similar between the two; the gain is concentrated in the
worst case and in predictability — which is what reliability
engineering sizes for.
Honest caveats
large average-case win.
seq_indexvalues across waiters; with identicalindices it degenerates to a fixed schedule (documented in the docstring).
latency would shrink the gap. Reproducibility and no-RNG remain regardless.
Changes
tenacity/wait.py: addwait_golden_jitterclass.tests/test_tenacity.py: addTestWaitGoldenJitter(6 tests).doc/source/index.rst: document the new strategy and when to prefer it.Prior art
The use of the golden ratio for even, hard-to-resonate spacing is
well-established in low-discrepancy sampling. A formal optimality result for
golden-ratio scheduling in a related setting appears in Kempe, Schulman &
Tamuz, "Quasi-regular sequences and optimal schedules for security games"
(SODA 2018). This PR applies the same principle to retry timing.