probe

package
v0.1.0-alpha.3 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package probe lets a test observe an owner's joins and retained state instead of inferring them from timing or goroutine counts (openspec change setup-02-isolated-harness, capability lifecycle-suite). Adapted from the per-test shapes in SemStreams processor/graph-query/lifecycle_owner_test.go at 5457b345 (ledger row L5), which SemStreams copies 26 times (observed context) and 9 times (entered/release). Test-only: contract test T-B1 refuses any production import.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Await

func Await[T any](ctx context.Context, observe func(context.Context) (T, error), done func(T) bool) (T, error)

Await polls observe under the caller's context until done accepts an observation, and returns that observation. When the context ends first it returns the last observation and an error that wraps the context's error and that observation's own error, if it had one, and names the last value, so a failed wait says what was seen rather than only that time ran out. An error from an earlier observation is not reported once a later one returns without error. An observation error does not end the wait: the thing observed may not exist yet.

Types

type Callback

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

Callback is a callback body a test holds open to observe an owner while work is in flight: it signals entry, blocks until released, records whether its context was still live at release, and signals when it has returned.

It deliberately keeps no context: it records ctx.Err() at the moment of release instead. Context cancellation is monotonic, so a nil error at release proves the context was live for the whole time the callback was blocked.

func NewCallback

func NewCallback() *Callback

NewCallback returns a callback that has not been entered or released.

func (*Callback) Block

func (c *Callback) Block(ctx context.Context)

Block is the callback body. It closes Entered, waits for Release, records ctx.Err(), and closes Joined as it returns. It does not return early when ctx ends: a callback that ignores its context is exactly the shape an owner's drain must wait for. Later calls behave the same but record and signal nothing new.

func (*Callback) ContextErrAtRelease

func (c *Callback) ContextErrAtRelease() error

ContextErrAtRelease is ctx.Err() as the first Block saw it when released; nil means the callback's context stayed live throughout. Before the first release it is nil.

func (*Callback) Entered

func (c *Callback) Entered() <-chan struct{}

Entered is closed when Block is first called.

func (*Callback) Joined

func (c *Callback) Joined() <-chan struct{}

Joined is closed when the first Block has returned.

func (*Callback) Release

func (c *Callback) Release()

Release lets every current and future Block return. It is idempotent, so a test may both release explicitly and defer a release for its failure paths.

type ObservedContext

type ObservedContext struct {
	context.Context
	// contains filtered or unexported fields
}

ObservedContext is a context that signals the first time anyone calls Done on it, and can hold that caller until the test lets it proceed. A test passes it as an owner's Stop context and waits on Observed to know Stop has reached the point where it waits on its caller's authority, without sleeping.

It is itself a context.Context derived from its parent, so it holds the parent the way the standard library's derived contexts do; contract test T-B2 exempts this one type by name.

func Observe

func Observe(parent context.Context) *ObservedContext

Observe returns a context derived from parent whose first Done call closes Observed.

func ObserveAndHold

func ObserveAndHold(parent context.Context, proceed <-chan struct{}) *ObservedContext

ObserveAndHold is Observe, except that the first Done call also blocks until proceed is closed. A nil proceed does not hold. Like context.WithCancel, it panics on a nil parent.

func (*ObservedContext) Done

func (c *ObservedContext) Done() <-chan struct{}

Done returns the parent's Done channel, signalling (and, if asked, holding) the first caller.

func (*ObservedContext) Observed

func (c *ObservedContext) Observed() <-chan struct{}

Observed is closed by the first Done call.

Jump to

Keyboard shortcuts

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