util

Documentation

Index

• Variables
• func AddHandler[T any, R any](logPrefix string, mux *http.ServeMux, endpoint string, method string, ...)
• func AtomicMax[A AtomicInt[I], I constraints.Integer](a A, i I) I
• func Max[T constraints.Ordered](x, y T) T
• func Min[T constraints.Ordered](x, y T) T
• func NewCondChannelPair() (CondChannelSender, CondChannelReceiver)
• func NewSingleSignalPair() (SignalSender, SignalReceiver)
• func PatchPathEscape(path string) string
• func PodReady(pod *corev1.Pod) bool
• func PodStartedBefore(p, q *corev1.Pod) bool
• func SaturatingSub[T constraints.Unsigned](x, y T) T
• type AtomicInt
• type BuildInfo
  • func GetBuildInfo() BuildInfo
• type ChanMutex
  • func NewChanMutex() ChanMutex
  • func (m *ChanMutex) Lock()
  • func (m *ChanMutex) TryLock(ctx context.Context) error
  • func (m *ChanMutex) Unlock()
  • func (m *ChanMutex) WaitLock() <-chan struct{}
• type CondChannelReceiver
  • func (c *CondChannelReceiver) Consume()
  • func (c *CondChannelReceiver) Recv() <-chan struct{}
• type CondChannelSender
  • func (c *CondChannelSender) Send()
  • func (c *CondChannelSender) Unsend() bool
• type InitWatchMode
• type JSONPatch
• type JSONPatchOp
• type SignalReceiver
  • func (s SignalReceiver) Close()
  • func (s SignalReceiver) Recv() chan struct{}
• type SignalSender
  • func (s SignalSender) Send()
• type TimeRange
  • func NewTimeRange(units time.Duration, min, max int) *TimeRange
  • func (r TimeRange) Random() time.Duration
• type WatchAccessors
• type WatchClient
• type WatchConfig
• type WatchHandlerFuncs
• type WatchObject
• type WatchStore
  • func Watch[C WatchClient[L], L metav1.ListMetaAccessor, T any, P WatchObject[T]](ctx context.Context, client C, config WatchConfig, ...) (*WatchStore[T], error)
  • func (w *WatchStore[T]) Items() []*T
  • func (w *WatchStore[T]) Stop()

Variables

var BuildGitInfo string

BuildGitInfo stores some pretty-formatted information about the repository and working tree at build time. It's set by the GIT_INFO argument in the Dockerfiles and generated with the git_info function in 'scripts-common.sh'.

While public, this value is not expected to be used externally. You should use GetBuildInfo instead.

Functions

func AddHandler

func AddHandler[T any, R any](
	logPrefix string,
	mux *http.ServeMux,
	endpoint string,
	method string,
	reqTypeName string,
	handle func(*T) (_ *R, statusCode int, _ error),
)

AddHandler is a helper function to wrap the handle function with JSON [de]serialization and check that the HTTP method is correct

The provided logPrefix is prepended to every log line emitted by the wrapped handler function, to offer distinction where that's useful.

func AtomicMax

func AtomicMax[A AtomicInt[I], I constraints.Integer](a A, i I) I

AtomicMax atomically sets a to the maximum of *a and i, returning the old value at a.

On ISAs without atomic maximum/minimum instructions, a fallback is typically implemented as the Load + CompareAndSwap loop that this function uses. At time of writing (Go 1.20), the Go standard library does not include atomic maximum/minimum functions.

This function is lock-free but not wait-free.

func Max

func Max[T constraints.Ordered](x, y T) T

Max returns the maximum of the two values

func Min

func Min[T constraints.Ordered](x, y T) T

Max returns the minimum of the two values

func NewCondChannelPair

func NewCondChannelPair() (CondChannelSender, CondChannelReceiver)

NewCondChannelPair creates a sender/receiver pair for a sync.Cond-like interface

The differences from sync.Cond are that receiving is exposed through a channel (so it can be select-ed) and there is no equivalent to (*Cond).Broadcast()

func NewSingleSignalPair

func NewSingleSignalPair() (SignalSender, SignalReceiver)

func PatchPathEscape

func PatchPathEscape(path string) string

func PodReady

func PodReady(pod *corev1.Pod) bool

PodReady returns true iff the pod is marked as ready (as determined by the pod's Status.Conditions)

func PodStartedBefore

func PodStartedBefore(p, q *corev1.Pod) bool

PodStartedBefore returns true iff Pod p started before Pod q

func SaturatingSub

func SaturatingSub[T constraints.Unsigned](x, y T) T

SaturatingSub returns x - y if x >= y, otherwise zero

Types

type AtomicInt

type AtomicInt[I any] interface {
	Add(delta I) (new I)                      //nolint:predeclared // same var names as methods
	CompareAndSwap(old, new I) (swapped bool) //nolint:predeclared // same var names as methods
	Load() I
	Store(val I)
	Swap(new I) (old I) //nolint:predeclared // same var names as methods
}

AtomicInt represents the shared interface provided by various atomic.<NAME> integers

This interface type is primarily used by AtomicMax.

type BuildInfo

type BuildInfo struct {
	GitInfo   string
	NeonVM    string
	GoVersion string
}

BuildInfo stores a little bit of information about the build of the current binary

All strings are guaranteed to be non-empty.

func GetBuildInfo

func GetBuildInfo() BuildInfo

GetBuildInfo makes a best-effort attempt to return some information about how the currently running binary was built

type ChanMutex

type ChanMutex struct {
	// contains filtered or unexported fields
}

ChanMutex is a select-able mutex

It is fair if and only if receiving on a channel is fair. As of Go 1.19/2022-01-17, receiving on a channel appears to be fair. However: this is a runtime implementation detail, and so it may change without notice in the future.

Unlike sync.Mutex, ChanMutex requires initialization before use because it's basically just a channel.

Also unlike sync.Mutex, a ChanMutex may be copied without issue (again, because it's just a channel).

func NewChanMutex

func NewChanMutex() ChanMutex

NewChanMutex creates a new ChanMutex

func (*ChanMutex) Lock

func (m *ChanMutex) Lock()

Lock locks m

This method is semantically equivalent to sync.Mutex.Lock

func (*ChanMutex) TryLock

func (m *ChanMutex) TryLock(ctx context.Context) error

TryLock blocks until locking m succeeds or the context is cancelled

If the context is cancelled while waiting to lock m, the lock will be left unchanged and ctx.Err() will be returned.

func (*ChanMutex) Unlock

func (m *ChanMutex) Unlock()

Unlock unlocks m

This method is semantically equivalent to sync.Mutex.Unlock

func (*ChanMutex) WaitLock

func (m *ChanMutex) WaitLock() <-chan struct{}

WaitLock is like Lock, but instead returns a channel

If receiving on the channel succeeds, the caller "holds" the lock and must now be responsible for Unlock-ing it.

type CondChannelReceiver

type CondChannelReceiver struct {
	// contains filtered or unexported fields
}

CondChannelReceiver is the receiving half of a sync.Cond-like interface

func (*CondChannelReceiver) Consume

func (c *CondChannelReceiver) Consume()

Consume removes any existing signal created by Send, requiring an additional Send to be made before the receiving on Recv will unblock

This method is non-blocking.

func (*CondChannelReceiver) Recv

func (c *CondChannelReceiver) Recv() <-chan struct{}

Recv returns a channel for which receiving will complete either (a) immediately, if Send has been called without Consume or another receive since; or (b) as soon as Send is next called

This method is non-blocking but receiving on the returned channel may block.

type CondChannelSender

type CondChannelSender struct {
	// contains filtered or unexported fields
}

CondChannelSender is the sending half of a sync.Cond-like interface

func (*CondChannelSender) Send

func (c *CondChannelSender) Send()

Send performs a non-blocking notify of the associated CondChannelReceiver

If there is currently a receiver waiting via Recv, then this will immediately wake them. Otherwise, the next receive on the channel returned by Recv will complete immediately.

func (*CondChannelSender) Unsend

func (c *CondChannelSender) Unsend() bool

Unsend cancels an existing signal that has been sent but not yet received.

It returns whether there was a signal to be cancelled.

type InitWatchMode

type InitWatchMode string

InitWatchMode dictates the behavior of Watch with respect to any initial calls to handlers.AddFunc before returning

If set to InitWatchModeSync, then AddFunc will be called while processing the initial listing, meaning that the returned WatchStore is guaranteed contain the state of the cluster (although it may update before any access).

Otherwise, if set to InitWatchModeDefer, then AddFunc will not be called until after Watch returns. Correspondingly, the WatchStore will not update until then either.

const (
	InitWatchModeSync  InitWatchMode = "sync"
	InitWatchModeDefer InitWatchMode = "defer"
)

type JSONPatch

type JSONPatch struct {
	Op    JSONPatchOp `json:"op"`
	From  string      `json:"from,omitempty"`
	Path  string      `json:"path"`
	Value any         `json:"value,omitempty"`
}

type JSONPatchOp

type JSONPatchOp string

const (
	PatchAdd     JSONPatchOp = "add"
	PatchRemove  JSONPatchOp = "remove"
	PatchReplace JSONPatchOp = "replace"
	PatchMove    JSONPatchOp = "move"
	PatchCopy    JSONPatchOp = "copy"
	PatchTest    JSONPatchOp = "test"
)

type SignalReceiver

type SignalReceiver struct {
	// contains filtered or unexported fields
}

func (SignalReceiver) Close

func (s SignalReceiver) Close()

func (SignalReceiver) Recv

func (s SignalReceiver) Recv() chan struct{}

type SignalSender

type SignalSender struct {
	// contains filtered or unexported fields
}

func (SignalSender) Send

func (s SignalSender) Send()

type TimeRange

type TimeRange struct {
	// contains filtered or unexported fields
}

func NewTimeRange

func NewTimeRange(units time.Duration, min, max int) *TimeRange

func (TimeRange) Random

func (r TimeRange) Random() time.Duration

Random returns a random time.Duration within the range

type WatchAccessors

type WatchAccessors[L any, T any] struct {
	Items func(L) []T
}

WatchAccessors provides the "glue" functions for Watch to go from a list L (returned by the client's List) to the underlying slice of items []T

type WatchClient

type WatchClient[L any] interface {
	List(context.Context, metav1.ListOptions) (L, error)
	Watch(context.Context, metav1.ListOptions) (watch.Interface, error)
}

WatchClient is implemented by the specific interfaces of kubernetes clients, like `Clientset.CoreV1().Pods(namespace)` or `..Nodes()`

This interface should be *already implemented* by whatever the correct client is.

type WatchConfig

type WatchConfig struct {
	// LogName is the name of the watcher for use in logs
	LogName string

	// RetryRelistAfter gives a retry interval when a re-list fails. If left nil, then Watch will
	// not retry.
	RetryRelistAfter *TimeRange
	// RetryWatchAfter gives a retry interval when a non-initial watch fails. If left nil, then
	// Watch will not retry.
	RetryWatchAfter *TimeRange
}

WatchConfig is the miscellaneous configuration used by Watch

type WatchHandlerFuncs

type WatchHandlerFuncs[P any] struct {
	AddFunc    func(obj P, preexisting bool)
	UpdateFunc func(oldObj P, newObj P)
	DeleteFunc func(obj P, mayBeStale bool)
}

WatchHandlerFuncs provides the set of callbacks to use for events from Watch

type WatchObject

type WatchObject[T any] interface {
	~*T
	runtime.Object
	metav1.ObjectMetaAccessor
}

WatchObject is implemented by pointers to T, where T is typically the resource that we're actually watching.

Example implementors: *corev1.Pod, *corev1.Node

type WatchStore

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

WatchStore provides an interface for getting information about a list of Ts using the event listener from a previous call to Watch

func Watch

func Watch[C WatchClient[L], L metav1.ListMetaAccessor, T any, P WatchObject[T]](
	ctx context.Context,
	client C,
	config WatchConfig,
	accessors WatchAccessors[L, T],
	mode InitWatchMode,
	opts metav1.ListOptions,
	handlers WatchHandlerFuncs[P],
) (*WatchStore[T], error)

Watch starts a goroutine for watching events, using the provided WatchHandlerFuncs as the callbacks for each type of event.

The type C is the kubernetes client we use to get the objects, L representing a list of these, T representing the object type, and P as a pointer to T.

func (*WatchStore[T]) Items

func (w *WatchStore[T]) Items() []*T

func (*WatchStore[T]) Stop

func (w *WatchStore[T]) Stop()