Documentation
¶
Overview ¶
Package callbackcontract provides concurrency-safe guards for extension callbacks whose invocation count is part of a framework correctness contract.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClosedInvocation = errors.New("callback was invoked after its boundary returned")
ErrClosedInvocation is returned when a callback is invoked after its owner has returned from the extension boundary.
var ErrRepeatedInvocation = errors.New("callback was invoked more than once")
ErrRepeatedInvocation is returned to a caller that attempts to invoke a guarded callback more than once. The first invocation remains authoritative.
Functions ¶
This section is empty.
Types ¶
type ExactlyOnce ¶
type ExactlyOnce struct {
// contains filtered or unexported fields
}
ExactlyOnce admits at most one callback invocation and records whether an extension honored its synchronous exactly-once contract. Its zero value is ready for use. Call CloseAndWait and inspect Snapshot.Outcome before trusting the extension's result.
func (*ExactlyOnce) CloseAndWait ¶
func (guard *ExactlyOnce) CloseAndWait() Snapshot
CloseAndWait closes the invocation window and returns its final state. An invocation that already escaped the extension boundary is allowed to finish before this method returns, so callback work can never outlive the framework call. Later invocations are rejected without running operation.
func (*ExactlyOnce) Invoke ¶
func (guard *ExactlyOnce) Invoke(operation func() error) (result error)
Invoke runs operation only for the first call. A panic is not recovered or retained, but the snapshot records that the callback completed without returning so an outer boundary can detect a swallowed panic.
func (*ExactlyOnce) Snapshot ¶
func (guard *ExactlyOnce) Snapshot() Snapshot
Snapshot returns a race-safe copy of the current invocation state.
type Outcome ¶
type Outcome uint8
Outcome classifies the callback state after its invocation window closes.
const ( // OutcomeContractViolation means the callback was repeated, escaped its // extension boundary, or otherwise ended in an invalid state. OutcomeContractViolation Outcome = iota // OutcomeNotInvoked means no callback began before the boundary closed. OutcomeNotInvoked // OutcomeReturned means one callback returned synchronously. OutcomeReturned // OutcomePanicked means one callback unwound synchronously without returning. OutcomePanicked )
type Snapshot ¶
type Snapshot struct {
Calls int
InFlight bool
Completed bool
Returned bool
Repeated bool
Late bool
Closed bool
Escaped bool
Result error
}
Snapshot is an immutable observation of one ExactlyOnce guard.
func (Snapshot) NotInvoked ¶
NotInvoked reports that no callback began before the boundary closed. This can be valid when an extension returns a non-nil setup error first.
func (Snapshot) Outcome ¶
Outcome returns the callback's centralized state classification. Callers separately decide whether OutcomeNotInvoked is valid for a non-nil setup error and whether an OutcomePanicked boundary faithfully propagated panic.
func (Snapshot) SynchronouslyPanickedOnce ¶
SynchronouslyPanickedOnce reports that one invocation unwound without returning while the extension boundary was still active. The boundary must independently prove that it propagated the panic rather than swallowing it.
func (Snapshot) SynchronouslyReturnedOnce ¶
SynchronouslyReturnedOnce reports the only valid state after an extension has invoked its callback.
Source Files