Documentation
¶
Overview ¶
Package watch is the polling producer behind the public Watch APIs. Each public package keeps its own config validation, event type and identity rules; this package only runs the reads, numbers the events, reports gaps and overflow, and joins the producer on Stop.
Index ¶
Constants ¶
const ( MinInterval = 100 * time.Millisecond DefaultTimeout = 30 * time.Second DefaultBuffer = 16 MaxBuffer = 1024 )
Limits of a Settings.
Variables ¶
var ErrOverflow = errors.New("watch event buffer overflow")
ErrOverflow ends a watch whose consumer left the event buffer full for one polling interval while an event waited. ceph.ErrWatchOverflow is this value.
var ErrStopped = errors.New("watch stopped")
ErrStopped is the cancellation cause of Stream.Stop. Stop reports it as a nil cause.
Functions ¶
Types ¶
type Kind ¶
type Kind string
Kind names what an event reports. The public packages convert it to ceph.WatchEventKind.
const ( // Baseline is the first event: the read that Start made before it // returned. Baseline Kind = "baseline" // Changed is a successful read that differs from the previous // successful read. Changed Kind = "changed" // Gap is one failed read; the watch keeps polling. Gap Kind = "gap" // Resumed is the first successful read after one or more gaps, whether // or not the sample changed across them. Resumed Kind = "resumed" )
The kinds of event.
type Settings ¶
Settings is a validated watch configuration.
func Validate ¶
func Validate(interval, timeout time.Duration, buffer int, defaultInterval time.Duration) (Settings, error)
Validate checks the raw configuration fields of a public WatchConfig and fills its defaults. defaultInterval is the target's own default. The error is unclassified; the caller marks it as an invalid request and names its operation.
type Spec ¶
type Spec[S, E any] struct { Name string Settings Settings Read func(context.Context) (S, error) Equal func(a, b S) bool Final func(S) bool Event func(meta Meta, sample S, err error) E }
Spec describes one watch target.
Read makes one read. Start calls it once for the baseline and then the producer calls it again, never concurrently, so Read may keep state such as identities pinned by the baseline. A Read error is a gap unless it is wrapped with Fatal, which ends the watch with the wrapped error. Every baseline error ends Start. Read must release every fixture lock before it returns.
On a gap, Event receives what Read returned together with its error, which may be partial evidence. Equal compares two successful samples; equal samples produce no event. Final, when set, reports a sample after which nothing can change: the watch delivers it and ends with a nil cause. Event builds the public event; it must copy every slice and map of the sample, because the producer keeps it.
type Stream ¶
type Stream[E any] struct { // contains filtered or unexported fields }
Stream is one running watch. Events closes after the producer goroutine has stopped using the fixture.
func Start ¶
Start makes the baseline read under ctx and the query timeout, buffers the baseline event and starts the producer. A failed baseline returns its error and starts nothing.
func (*Stream[E]) Done ¶
func (s *Stream[E]) Done() <-chan struct{}
Done closes when the producer has returned, after Events closes.
func (*Stream[E]) Events ¶
func (s *Stream[E]) Events() <-chan E
Events returns the receive-only event channel; nil on a nil Stream.