proposal: testing/synctest: experimental package for testing concurrent code

[neild]

Proposal Details

This is an offshoot of #67434. See that proposal for prior discussion and more details.

I propose adding a new testing/synctest package to aid in testing concurrent code. This package will be initially guarded by a GOEXPERIMENT flag: It will be present only in toolchains built with GOEXPERIMENT=synctest. After we've gained some experience with the experimental package, we will make the decision to drop the flag requirement and fully release it, abandon the experiment and remove it, or amend it.

The package API is as follows:

// Package synctest provides support for testing concurrent code.
package synctest

// Run executes f in a new goroutine.
//
// The new goroutine and any goroutines transitively started by it form
// an isolated "bubble".
// Run waits for all goroutines in the bubble to exit before returning.
//
// Goroutines in the bubble use a fake time implementation.
// The initial time is midnight UTC 2000-01-01.
//
// A goroutine in the bubble is idle if it is blocked on:
//   - a send or receive on a channel created within the bubble
//   - a select statement where every case is a channel within the bubble
//   - sync.Cond.Wait
//   - time.Sleep
//
// The above cases are the only times a goroutine is idle.
// In particular, a goroutine is NOT idle when blocked on:
//   - system calls
//   - cgo calls
//   - I/O, such as reading from a network connection with no data
//   - sync.Mutex.Lock or sync.Mutex.RLock
//
// Time advances when every goroutine in the bubble is idle.
// For example, a call to time.Sleep will block until all goroutines
// are idle, and return after the bubble's clock has advanced
// by the sleep duration.
//
// If every goroutine is idle and there are no timers scheduled,
// Run panics.
//
// Channels, time.Timers, and time.Tickers created within the bubble
// are associated with it. Operating on a bubbled channel, timer, or ticker
// from outside the bubble panics.
func Run(f func())

// Wait blocks until every goroutine within the current bubble,
// other than the current goroutine, is idle.
func Wait()

[gabyhelp]

Related Issues and Documentation

• proposal: testing/synctest: new package for testing concurrent code #67434
• proposal: runtime: add WaitIdle function #65336 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}