sync

sync.Once, sync.Mutex, and sync.WaitGroup on Go 1.24, including the rule not to copy them after first use. WaitGroup.Go is not in this version.

模块页正文目前为英文。

The sync package provides basic synchronization. Official documentation states that a Mutex, a Once, and a WaitGroup must not be copied after first use. Store them in the same struct you share, and pass a pointer. Do not put one of these types in a value you pass, return, or assign after it has been used.

These APIs were checked with Go 1.24.0. WaitGroup.Go is not in this version of the standard library, so this page does not call it. On 1.24, start work with Add, a go statement, and Done. The WaitGroup example below was also run with go run -race on this host; that race run passed.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
sync.Once, sync.Mutex, sync.WaitGroupRun an initializer once, and wait for a fixed number of goroutines while a Mutex protects a shared counter. This is the Go 1.24 WaitGroup API: Add, Done, and Wait, not WaitGroup.Go.
WaitGroup.Done, WaitGroup.AddDone on a zero WaitGroup panics because the counter would become negative. This example uses no other goroutine.

Once, Mutex, and WaitGroup

sync.Once.Do runs the function only on the first call for that Once; a later Do with the same or a different function does not run it. WaitGroup.Add must happen before the corresponding goroutine is started. Each goroutine calls Done when it finishes, usually with defer, and Wait blocks until the counter is back at zero. The shared sum is updated under Mutex so the increment is not a data race. Add panics if the counter would go negative; that case is in the next section.

sync.Once, sync.Mutex, sync.WaitGroup

func (o *Once) Do(f func())
func (m *Mutex) Lock()
func (m *Mutex) Unlock()
func (wg *WaitGroup) Add(delta int)
func (wg *WaitGroup) Done()
func (wg *WaitGroup) Wait()

Run an initializer once, and wait for a fixed number of goroutines while a Mutex protects a shared counter. This is the Go 1.24 WaitGroup API: Add, Done, and Wait, not WaitGroup.Go.

ParameterDescription
fThe function Once.Do may run. Only the first Do call on that Once invokes it.
deltaA change to the WaitGroup counter. A positive Add that starts from zero must happen before Wait.

Returns: These methods do not return a value. Wait returns after Done has brought the counter back to zero.

  • The three goroutines only communicate through the Mutex-protected sum and the WaitGroup. The printed sum is 3 and does not depend on scheduling order.
  • This example was run with go run -race on Go 1.24.0 darwin/arm64, and that race run passed.
go
package main

import (
	"fmt"
	"sync"
)

func main() {
	var once sync.Once
	n := 0
	inc := func() { n++ }
	once.Do(inc)
	once.Do(inc)
	fmt.Println(n)

	var wg sync.WaitGroup
	var mu sync.Mutex
	sum := 0
	for i := 0; i < 3; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			mu.Lock()
			sum++
			mu.Unlock()
		}()
	}
	wg.Wait()
	fmt.Println(sum)
}

Expected output

1
3

Official documentation →

Copying and a negative counter

Copying a WaitGroup, Mutex, or Once after first use is a bug. go vet reports copies of these types. The usual mistake is a value receiver or an accidental assignment of the struct that contains the lock. Official documentation for Add says the counter must not go negative; Done is equivalent to Add(-1). Calling Done when the counter is already zero panics. The panic text below was measured on Go 1.24.0.

WaitGroup.Done, WaitGroup.Add

func (wg *WaitGroup) Done()
func (wg *WaitGroup) Add(delta int)

Done on a zero WaitGroup panics because the counter would become negative. This example uses no other goroutine.

ParameterDescription
deltaAdd accepts a negative delta. If the counter goes below zero, Add panics.

Errors

  • panic — Official documentation: if the counter goes negative, Add panics. The measured message on Go 1.24.0 is "sync: negative WaitGroup counter".
  • This page does not show a copied Mutex. Treat that as a static rule: after first use, share a pointer, do not copy the value.
go
package main

import (
	"fmt"
	"sync"
)

func main() {
	defer func() { fmt.Println(recover()) }()
	var wg sync.WaitGroup
	wg.Done()
}

Expected output

sync: negative WaitGroup counter

Official documentation →