watch

Documentation

Overview

Package watch provides an observable value: a Value that can be updated and one or more Observer handles that observe its changes.

It is the Go analog of iroh's n0_watcher (Watchable + Watcher). An Observer exposes the current value, a one-shot wait for the next change, and an iterator stream of values. The root package uses Observer for APIs such as Endpoint.WatchAddr.

The Go API is not stable before v1 and may change in any v0 release.

Index

• type Observer
• type Value
  • func NewValue[T any](v T) *Value[T]
  • func NewValueFunc[T any](v T, equal func(a, b T) bool) *Value[T]
  • func (s *Value[T]) Current() T
  • func (s *Value[T]) Set(v T)
  • func (s *Value[T]) Watch() Observer[T]

Types

type Observer

type Observer[T any] interface {
	// Current returns the current value.
	Current() T
	// Updated blocks until the value changes after the watcher's last observed
	// version, returning the new value, or ctx.Err() if the context is done.
	// The first call returns the current value immediately.
	Updated(ctx context.Context) (T, error)
	// Stream returns an iterator that yields each new value until ctx is done.
	// The current value is delivered first.
	Stream(ctx context.Context) iter.Seq[T]
}

Observer observes a Value. Multiple observers may observe the same value independently. It is the Go analog of iroh's n0_watcher::Watcher.

type Value

type Value[T any] struct {
	// contains filtered or unexported fields
}

Value is an observable container holding a T. It is safe for concurrent use. Updates are published to all Observer handles created from it.

The zero Value holds the zero T and is ready to use.

func NewValue

func NewValue[T any](v T) *Value[T]

NewValue returns a Value initialized to v.

func NewValueFunc

func NewValueFunc[T any](v T, equal func(a, b T) bool) *Value[T]

NewValueFunc returns a Value initialized to v. The equal function, if non-nil, suppresses notifications for no-op updates.

func (*Value[T]) Current

func (s *Value[T]) Current() T

Current returns the current value.

func (*Value[T]) Set

func (s *Value[T]) Set(v T)

Set updates the value and notifies all watchers if it changed.

func (*Value[T]) Watch

func (s *Value[T]) Watch() Observer[T]

Watch returns an Observer observing this value.