Source file src/testing/synctest/synctest.go
1 // Copyright 2024 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 //go:build goexperiment.synctest 6 7 // Package synctest provides support for testing concurrent code. 8 // 9 // This package only exists when using Go compiled with GOEXPERIMENT=synctest. 10 // It is experimental, and not subject to the Go 1 compatibility promise. 11 package synctest 12 13 import ( 14 "internal/synctest" 15 ) 16 17 // Run executes f in a new goroutine. 18 // 19 // The new goroutine and any goroutines transitively started by it form 20 // an isolated "bubble". 21 // Run waits for all goroutines in the bubble to exit before returning. 22 // 23 // Goroutines in the bubble use a synthetic time implementation. 24 // The initial time is midnight UTC 2000-01-01. 25 // 26 // Time advances when every goroutine in the bubble is blocked. 27 // For example, a call to time.Sleep will block until all other 28 // goroutines are blocked and return after the bubble's clock has 29 // advanced. See [Wait] for the specific definition of blocked. 30 // 31 // If every goroutine is blocked and there are no timers scheduled, 32 // Run panics. 33 // 34 // Channels, time.Timers, and time.Tickers created within the bubble 35 // are associated with it. Operating on a bubbled channel, timer, or ticker 36 // from outside the bubble panics. 37 func Run(f func()) { 38 synctest.Run(f) 39 } 40 41 // Wait blocks until every goroutine within the current bubble, 42 // other than the current goroutine, is durably blocked. 43 // It panics if called from a non-bubbled goroutine, 44 // or if two goroutines in the same bubble call Wait at the same time. 45 // 46 // A goroutine is durably blocked if can only be unblocked by another 47 // goroutine in its bubble. The following operations durably block 48 // a goroutine: 49 // - a send or receive on a channel from within the bubble 50 // - a select statement where every case is a channel within the bubble 51 // - sync.Cond.Wait 52 // - time.Sleep 53 // 54 // A goroutine executing a system call or waiting for an external event 55 // such as a network operation is not durably blocked. 56 // For example, a goroutine blocked reading from an network connection 57 // is not durably blocked even if no data is currently available on the 58 // connection, because it may be unblocked by data written from outside 59 // the bubble or may be in the process of receiving data from a kernel 60 // network buffer. 61 // 62 // A goroutine is not durably blocked when blocked on a send or receive 63 // on a channel that was not created within its bubble, because it may 64 // be unblocked by a channel receive or send from outside its bubble. 65 func Wait() { 66 synctest.Wait() 67 } 68