utils

Documentation

Index

• Variables
• func CheckObjectSatisfied[T client.Object](ctx context.Context, obj T, update UpdateFunc[T], satisfiedFunc CheckFunc[T]) (bool, error)
• func DoubleCheckObjectSatisfied[T client.Object](ctx context.Context, obj T, update UpdateFunc[T], satisfiedFunc CheckFunc[T]) error
• func ReleaseEntry[T client.Object](waitHooks *sync.Map, key string, entry *WaitEntry[T])
• func WaitForObjectSatisfied[T client.Object](ctx context.Context, waitHooks *sync.Map, obj T, action WaitAction, ...) error
• func WaitHookKey[T client.Object](obj T) string
• func WaitHookKeyFromRequest[T client.Object](req ctrl.Request) string
• type CheckFunc
• type UpdateFunc
• type WaitAction
• type WaitEntry
  • func AcquireEntry[T client.Object](waitHooks *sync.Map, key string, action WaitAction, ...) (*WaitEntry[T], error)
  • func NewWaitEntry[T client.Object](ctx context.Context, action WaitAction, checker CheckFunc[T]) *WaitEntry[T]
  • func (e *WaitEntry[T]) Check(obj T) (bool, error)
  • func (e *WaitEntry[T]) Close()
  • func (e *WaitEntry[T]) Context() context.Context
  • func (e *WaitEntry[T]) Done() <-chan struct{}
• type WaitNotSatisfiedError
  • func (e *WaitNotSatisfiedError) Error() string
  • func (e *WaitNotSatisfiedError) Is(target error) bool
• type WaitTask
  • func NewAcquiredWaitTask[T client.Object](ctx context.Context, waitHooks *sync.Map, action WaitAction, object T, ...) (*WaitTask[T], error)
  • func NewWaitTask[T client.Object](ctx context.Context, waitHooks *sync.Map, action WaitAction, object T, ...) *WaitTask[T]
  • func (t *WaitTask[T]) Action() WaitAction
  • func (t *WaitTask[T]) Object() T
  • func (t *WaitTask[T]) Release()
  • func (t *WaitTask[T]) Wait(timeout time.Duration) error
• type WaitTaskConflictError
  • func (e *WaitTaskConflictError) Error() string
  • func (e *WaitTaskConflictError) Is(target error) bool

Variables

var (
	// ErrWaitNotSatisfied matches wait failures where the object did not reach
	// the requested state before the wait completed.
	ErrWaitNotSatisfied = &WaitNotSatisfiedError{}
	// ErrWaitTaskConflict matches failures caused by another wait action
	// already registered for the same object.
	ErrWaitTaskConflict = &WaitTaskConflictError{}
)

Functions

func CheckObjectSatisfied

func CheckObjectSatisfied[T client.Object](ctx context.Context, obj T, update UpdateFunc[T], satisfiedFunc CheckFunc[T]) (bool, error)

func DoubleCheckObjectSatisfied

func DoubleCheckObjectSatisfied[T client.Object](ctx context.Context, obj T, update UpdateFunc[T], satisfiedFunc CheckFunc[T]) error

func ReleaseEntry

func ReleaseEntry[T client.Object](waitHooks *sync.Map, key string, entry *WaitEntry[T])

ReleaseEntry is the counterpart of AcquireEntry. It holds entry.mu while decrementing refs and, when the last waiter exits, while deleting the same entry from the map with CompareAndDelete. A concurrent AcquireEntry that saw this entry before deletion must acquire entry.mu first, then re-check the map before incrementing refs, so it cannot resurrect or retain an orphan entry.

func WaitForObjectSatisfied

func WaitForObjectSatisfied[T client.Object](ctx context.Context, waitHooks *sync.Map, obj T, action WaitAction,
	update UpdateFunc[T], satisfiedFunc CheckFunc[T], timeout time.Duration) error

func WaitHookKey

func WaitHookKey[T client.Object](obj T) string

WaitHookKey generates a unique key for wait hooks by combining object type with namespace/name. This prevents key collisions when different resource types (e.g., Sandbox and Checkpoint) share the same namespace and name.

func WaitHookKeyFromRequest

func WaitHookKeyFromRequest[T client.Object](req ctrl.Request) string

WaitHookKeyFromRequest generates a wait hook key from a reconcile request. This is useful in controller reconcilers where only the request is available.

Types

type CheckFunc

type CheckFunc[T client.Object] func(obj T) (bool, error)

type UpdateFunc

type UpdateFunc[T client.Object] func(obj T) (T, error)

type WaitAction

type WaitAction string

const (
	WaitActionResume     WaitAction = "Resume"
	WaitActionPause      WaitAction = "Pause"
	WaitActionWaitReady  WaitAction = "WaitReady"
	WaitActionCheckpoint WaitAction = "Checkpoint"
)

type WaitEntry

type WaitEntry[T client.Object] struct {
	Action WaitAction
	// contains filtered or unexported fields
}

func AcquireEntry

func AcquireEntry[T client.Object](waitHooks *sync.Map, key string, action WaitAction, newEntry func() *WaitEntry[T]) (*WaitEntry[T], error)

AcquireEntry increments the entry refcount only after confirming that the map still points at that entry while holding entry.mu. Together with ReleaseEntry holding the same lock across refs-- and CompareAndDelete, this prevents a waiter from acquiring an orphan entry that was just removed.

A same-action late joiner may still acquire an entry whose done channel has already been closed but has not yet been released from the map. That is intentional for the current wait flow: Close is triggered from the same informer/cache object that later post-acquire and double-check reads use, so the late joiner should observe the satisfied state immediately and return.

func NewWaitEntry

func NewWaitEntry[T client.Object](ctx context.Context, action WaitAction, checker CheckFunc[T]) *WaitEntry[T]

func (*WaitEntry[T]) Check

func (e *WaitEntry[T]) Check(obj T) (bool, error)

func (*WaitEntry[T]) Close

func (e *WaitEntry[T]) Close()

func (*WaitEntry[T]) Context

func (e *WaitEntry[T]) Context() context.Context

func (*WaitEntry[T]) Done

func (e *WaitEntry[T]) Done() <-chan struct{}

type WaitNotSatisfiedError

type WaitNotSatisfiedError struct {
	Object            client.ObjectKey
	Action            WaitAction
	DuringDoubleCheck bool
}

WaitNotSatisfiedError reports that a wait task finished while the object was still not in the requested state.

func (*WaitNotSatisfiedError) Error

func (e *WaitNotSatisfiedError) Error() string

func (*WaitNotSatisfiedError) Is

func (e *WaitNotSatisfiedError) Is(target error) bool

type WaitTask

type WaitTask[T client.Object] struct {
	// contains filtered or unexported fields
}

WaitTask packages a WaitAction with its Update and Check funcs so that callers cannot accidentally pair the same (object, action) with different checkers. A task may be lazy, acquiring its wait hook during Wait, or pre-acquired, acquiring the wait hook during construction. Pre-acquired tasks are single-use: Wait releases the hook when it returns, and Release is safe to defer after construction as cleanup for paths that do not reach Wait. The zero value is not usable.

Immutability:

• All fields are unexported; once constructed by a factory, callers can use Wait(timeout), and pre-acquired callers may use Release to abandon an unused task before Wait.
• The caller ctx is captured at construction time because UpdateFunc[T] has no ctx parameter; passing a different ctx to Wait would leak across the Update closure.

func NewAcquiredWaitTask

func NewAcquiredWaitTask[T client.Object](
	ctx context.Context,
	waitHooks *sync.Map,
	action WaitAction,
	object T,
	update UpdateFunc[T],
	check CheckFunc[T],
) (*WaitTask[T], error)

NewAcquiredWaitTask builds a single-use WaitTask that acquires its wait hook immediately. Callers may defer Release after successful construction; Wait releases the acquired hook when it returns, and the deferred Release is idempotent cleanup for paths that do not reach Wait.

func NewWaitTask

func NewWaitTask[T client.Object](
	ctx context.Context,
	waitHooks *sync.Map,
	action WaitAction,
	object T,
	update UpdateFunc[T],
	check CheckFunc[T],
) *WaitTask[T]

NewWaitTask builds a lazy WaitTask. Exported only so that the cache package (which is a sibling package, not utils) can construct instances inside its factory methods; production code outside pkg/cache MUST NOT call this directly — use the *cache.Cache.NewXxxTask factories instead.

func (*WaitTask[T]) Action

func (t *WaitTask[T]) Action() WaitAction

Action returns the underlying wait action (read-only accessor, used by tests).

func (*WaitTask[T]) Object

func (t *WaitTask[T]) Object() T

Object returns the subject object (read-only accessor, used by tests).

func (*WaitTask[T]) Release

func (t *WaitTask[T]) Release()

Release abandons an unused pre-acquired task and releases its wait hook. Release is idempotent, is a no-op for lazy tasks, and does not release a hook while Wait is actively running.

func (*WaitTask[T]) Wait

func (t *WaitTask[T]) Wait(timeout time.Duration) error

Wait blocks until the task's Check func reports satisfied, the task's captured ctx is canceled, or timeout elapses. Lazy tasks acquire and release their hook during Wait. Pre-acquired tasks are single-use, reuse their stored hook, and release it when Wait returns.

type WaitTaskConflictError

type WaitTaskConflictError struct {
	ExistingAction WaitAction
	NewAction      WaitAction
}

WaitTaskConflictError reports that a wait task cannot be registered because another action is already waiting on the same object.

func (*WaitTaskConflictError) Error

func (e *WaitTaskConflictError) Error() string

func (*WaitTaskConflictError) Is

func (e *WaitTaskConflictError) Is(target error) bool