watch

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 4 Imported by: 0

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

View Source
const (
	MinInterval    = 100 * time.Millisecond
	DefaultTimeout = 30 * time.Second
	DefaultBuffer  = 16
	MaxBuffer      = 1024
)

Limits of a Settings.

Variables

View Source
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.

View Source
var ErrStopped = errors.New("watch stopped")

ErrStopped is the cancellation cause of Stream.Stop. Stop reports it as a nil cause.

Functions

func Fatal

func Fatal(err error) error

Fatal marks a Read error that a later read cannot undo, such as an identity change or a terminated cluster. The watch ends with err.

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 Meta

type Meta struct {
	Sequence          uint64
	Kind              Kind
	Started, Finished time.Time
}

Meta is the target-independent part of one event.

type Settings

type Settings struct {
	Interval, Timeout time.Duration
	Buffer            int
}

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

func Start[S, E any](ctx context.Context, spec Spec[S, E]) (*Stream[E], error)

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.

func (*Stream[E]) Started

func (s *Stream[E]) Started() bool

Started reports whether s came from Start.

func (*Stream[E]) Stop

func (s *Stream[E]) Stop() error

Stop cancels the watch, waits for the producer and returns the cause that ended the watch: nil for Stop or a final sample, otherwise the context's cause, an ErrOverflow error or the Fatal read error. Every call returns the same cause. The caller checks Started first.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL