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 ¶
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 ¶
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.
type ObservedContext ¶
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.