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 // Time stops advancing when f returns. 32 // 33 // If every goroutine is blocked and either 34 // no timers are scheduled or f has returned, 35 // Run panics. 36 // 37 // Channels, time.Timers, and time.Tickers created within the bubble 38 // are associated with it. Operating on a bubbled channel, timer, or ticker 39 // from outside the bubble panics. 40 func Run(f func()) { 41 synctest.Run(f) 42 } 43 44 // Wait blocks until every goroutine within the current bubble, 45 // other than the current goroutine, is durably blocked. 46 // It panics if called from a non-bubbled goroutine, 47 // or if two goroutines in the same bubble call Wait at the same time. 48 // 49 // A goroutine is durably blocked if can only be unblocked by another 50 // goroutine in its bubble. The following operations durably block 51 // a goroutine: 52 // - a send or receive on a channel from within the bubble 53 // - a select statement where every case is a channel within the bubble 54 // - sync.Cond.Wait 55 // - time.Sleep 56 // 57 // A goroutine executing a system call or waiting for an external event 58 // such as a network operation is not durably blocked. 59 // For example, a goroutine blocked reading from an network connection 60 // is not durably blocked even if no data is currently available on the 61 // connection, because it may be unblocked by data written from outside 62 // the bubble or may be in the process of receiving data from a kernel 63 // network buffer. 64 // 65 // A goroutine is not durably blocked when blocked on a send or receive 66 // on a channel that was not created within its bubble, because it may 67 // be unblocked by a channel receive or send from outside its bubble. 68 func Wait() { 69 synctest.Wait() 70 } 71