Documentation
¶
Overview ¶
Package retry provides a small generic scheduler for re-attempting a set of keyed targets with per-key backoff, deduplication and immediate-trigger support.
It exists so that components needing the same shape of work — "keep trying this set of targets on a schedule until each one succeeds or the policy gives up" — share one tested implementation instead of each reinventing a ticker + backoff + dedup loop. Examples: retrying trusted bootstrap seeds during a cold start, or re-probing temporarily unreachable peers.
It is deliberately scoped to active periodic scheduling. It is not meant to replace in-call synchronous retries (a single request/response round trip) nor passive suppression gates (negative caches), which have different shapes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Policy ¶
type Policy struct {
// Base is the delay before the first retry and the minimum delay.
Base time.Duration
// Max caps the backoff delay. Zero means no cap (delay grows unbounded with Factor).
Max time.Duration
// Factor multiplies the delay after each failed attempt. Values <= 1 keep
// the interval constant at Base.
Factor float64
// Jitter applies a random +/- fraction (0..1) to each computed delay.
Jitter float64
// MaxElapsed abandons a key this long after it was first added. Zero means
// no time limit (rely on Run's context or Done).
MaxElapsed time.Duration
// MaxAttempts abandons a key after this many attempts. Zero means no limit.
MaxAttempts int
}
Policy controls retry timing and give-up conditions. The zero value yields a constant 1s interval that never gives up.
type Scheduler ¶
type Scheduler[K comparable] struct { // contains filtered or unexported fields }
Scheduler retries a set of keyed targets. The zero value is not usable; call New. A Scheduler is safe for concurrent use.
func New ¶
func New[K comparable](p Policy, attempt func(ctx context.Context, key K) Outcome, onGiveUp func(key K)) *Scheduler[K]
New creates a Scheduler. attempt is invoked (each in its own goroutine) for every due key and its Outcome decides removal vs reschedule. onGiveUp, if non-nil, is called when the policy abandons a key (it never fires for keys that finish with Done or are explicitly Removed).
func (*Scheduler[K]) Add ¶
func (s *Scheduler[K]) Add(key K)
Add schedules key for a first attempt after Policy.Base. If key is already scheduled it is left unchanged (dedup).
func (*Scheduler[K]) Remove ¶
func (s *Scheduler[K]) Remove(key K)
Remove drops key from the scheduler. Safe to call for unknown keys.
func (*Scheduler[K]) Run ¶
Run drives the scheduler until ctx is cancelled or no keys remain. It blocks; callers typically launch it in a goroutine. In-flight attempts are not cancelled by Run returning — they observe ctx via the value passed to attempt.
func (*Scheduler[K]) Trigger ¶
func (s *Scheduler[K]) Trigger(key K)
Trigger schedules key for an immediate attempt, adding it if absent and bringing forward an already-scheduled (not in-flight) entry. One entry per key is kept (dedup). If the key is currently in-flight the trigger is a no-op: the in-flight attempt's outcome will schedule the next round normally.
Source Files