Documentation
¶
Overview ¶
Package poller maintains a single "current value" that is refreshed by periodically calling a Getter.
It is the read-side counterpart to worker.Loop: instead of performing work on each tick, it caches the latest successfully fetched value so hot paths can read it (via Current) without blocking on the source. A failed poll leaves the cached value unchanged. Typical uses are feature flags, dynamic config, exchange rates, or any slowly-changing remote value callers want cheaply and concurrently. A Poller is a worker.Runnable, so it can be supervised in a worker.Group alongside servers and other workers.
Usage ¶
Seed an initial value, supervise the poller, and read the cached value concurrently:
p := poller.New(log, defaultRates, func(ctx context.Context) (Rates, error) {
return fetchRates(ctx)
}, poller.Config{
Name: "rates",
Interval: 30 * time.Second,
PollTimeout: 5 * time.Second,
OnError: func(err error) { metrics.PollFail.Inc() },
})
g.Add(p) // worker.Group supervises Start/Stop
rates := p.Current() // latest successful value (the initial until first poll)
Config ¶
- Name: identifies the poller in logs and panic metrics (default "poller").
- Interval: time between polls (required, > 0).
- PollTimeout: bounds each Getter call (0 = inherit the run context).
- OnError: invoked with each failed poll's error; may be nil.
- OnPanic: safetick.PanicHandler invoked when a poll panics; may be nil.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Name identifies the poller in logs and panic metrics (defaults to "poller").
Name string
// Interval between polls. Required (> 0).
Interval time.Duration
// PollTimeout bounds each Getter call (0 = inherit the run context).
PollTimeout time.Duration
// OnError is invoked with each failed poll's error; may be nil (the error is
// then only logged).
OnError func(error)
// OnPanic is invoked when a poll panics; may be nil.
OnPanic safetick.PanicHandler
}
Config configures a Poller.
type Getter ¶
Getter fetches the next value. It is called on each tick (and synchronously by Poll). A returned error leaves the current value unchanged.
type Poller ¶
type Poller[T any] struct { // contains filtered or unexported fields }
Poller caches the latest value returned by its Getter, refreshing it on a fixed interval. Reads via Current are safe for concurrent use.
func New ¶
New builds a Poller seeded with initial, which Current returns until the first successful poll. log may be nil.
func (*Poller[T]) Current ¶
func (p *Poller[T]) Current() T
Current returns the most recently fetched value (the New initial value until the first successful poll). Safe for concurrent use.
func (*Poller[T]) Poll ¶
Poll fetches once, synchronously, and updates the current value on success. On error the value is left unchanged and OnError (if set) is invoked. A panic in the Getter is recovered so a single bad poll cannot crash the supervisor.
Source Files