proposal: sync/v2: new package

[ianlancetaylor]

Proposal Details

The math/rand/v2 package has been successful. Let's consider another v2 package: sync/v2.

This is an update of #47657.

Background

The current sync package provides Map and Pool types. These types were designed before Go supported generics. They work with values of type any.

Using any is not compile-time-type-safe. Nothing prevents using a key or value of any arbitrary type with a sync.Map. Nothing prevents storing a value of any arbitrary type into a sync.Pool. Go is in general a type-safe language. For all the reasons why Go map and slice types define the their key and element types, sync.Map and sync.Pool should as well.

Also, using any is inefficient. Converting a non-pointer value to any requires a memory allocation. This means that building a sync.Map with a key type of string requires an extra allocation for every value stored in the map. Storing a slice type in a sync.Pool requires an extra allocation.

These issues are easily avoided by changing sync.Map and sync.Pool to be generic types.

While we can't change Map and Pool to be generic in the current sync package because of compatibility concerns (see the discussion at #48287), we could consider adding new generic types to the existing sync package, as proposed at #47657. However, that will leave us with a confusing wart in the sync package that we can never remove. Having both sync.Pool and (say) sync.PoolOf is confusing. Deprecating sync.Pool still leaves us with a strange name for the replacement type.

Introducing a sync/v2 package will permit us to easily transition from the current package to a new package. It's true that future users will have to know to import "sync/v2" rather than "sync". However, few people write their own imports these days, and this transition is easily handled by goimports and similar tools.

Proposal

In the sync/v2 package, the following types and functions will be the same as in the current sync package:

func OnceFunc(f func()) func()
func OnceValue[T any](f func() T) func() T
func OnceValues[T1, T2 any](f func() (T1, T2)) func() (T1, T2)
type Cond struct{ ... }
    func NewCond(l Locker) *Cond
type Locker interface{ ... }
type Mutex struct{ ... }
type Once struct{ ... }
type RWMutex struct{ ... }
type WaitGroup struct{ ... }

The existing Map type will be replaced by a new type that takes two type parameters. Note that the original Range method is replaced with an All method that returns an iterator.

// Map is like a Go map[K]V but is safe for concurrent use
// by multiple goroutines without additional locking or coordination.
// ...and so forth
type Map[K comparable, V any] struct { ... }

// Load returns the value stored in the map for a key, or the zero value if no
// value is present.
// The ok result indicates whether value was found in the map.
func (m *Map[K, V]) Load(key K) (value V, ok bool)

// Store sets the value for a key.
func (m *Map[K, V]) Store(key K, value V)

// LoadOrStore returns the existing value for the key if present.
// Otherwise, it stores and returns the given value.
// The loaded result is true if the value was loaded, false if stored.
func (m *Map[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)

// LoadAndDelete deletes the value for a key, returning the previous value if any.
// The loaded result reports whether the key was present.
func (m *Map[K, V]) LoadAndDelete(key K) (value V, loaded bool)

// Delete deletes the value for a key.
func (m *Map[K, V]) Delete(key K)

// Swap swaps the value for a key and returns the previous value if any.
// The loaded result reports whether the key was present.
func (m *Map[K, V]) Swap(key K, value V) (previous V, loaded bool)

// CompareAndDelete deletes the entry for key if its value is equal to old.
// This panics if V is not a comparable type.
//
// If there is no current value for key in the map, CompareAndDelete
// returns false.
func (m *Map[K, V]) CompareAndDelete(key K, old V) (deleted bool)

// CompareAndSwap swaps the old and new values for key
// if the value stored in the map is equal to old.
// This panics if V is not a comparable type.
func (m *Map[K, V]) CompareAndSwap(key K, old, new V) (swapped bool)

// Clear deletes all the entries, resulting in an empty Map.
func (m *Map[K, V]) Clear()

// All returns an iterator over the keys and values in the map.
// ... and so forth
func (m *Map[K, V]) All() iter.Seq2[K, V]

// TODO: Consider Keys and Values methods that return iterators, like maps.Keys and maps.Values.

The existing Pool type will be replaced by a new type that takes a type parameter.

2025-01-04: The new version of Pool does not have an exported New field; instead, use NewPool to create a Pool that calls a function to return new values.

Note that the original Get method is replaced by one that returns two results, with the second being a bool indicating whether a value was returned. This is only useful if the New field is optional: we could also change this to require the New field to be set, or to provide a default implementation that returns the zero value of T.

// A Pool is a set of temporary objects of type T that may be individually saved and retrieved.
// ...and so forth
type Pool[T any] struct {
    ...
}

// NewPool returns a new pool. If the newf argument is not nil, then when the pool is empty,
// newf is called to fetch a new value. This is useful when the values in the pool should be initialized.
func NewPool[T any] (newf func() T) *Pool[T]

// Put adds x to the pool.
func (p *Pool[T]) Put(x T)

// Get selects an arbitrary item from the Pool, removes it from the
// Pool, and returns it to the caller.
// ...and so forth
//
// If Get does not have a value to return, and p was created with a call to [NewPool] with a non-nil argument,
// Get returns the result of calling the function passed to [NewPool].
func (p *Pool[T]) Get() T

[gabyhelp]

Related Issues

• proposal: sync, sync/atomic: add PoolOf, MapOf, ValueOf #47657
• proposal: sync: Add sync.MutexMap generic type #70066 (closed)

Related Documentation

• Package sync > type Map ¶ 1.9
• Package sync > type Pool ¶ 1.3

Related Discussions

• proposal: container/set: new package to provide a generic set type (discussion)

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

[mateusz834]

There is one issue I’ve encountered with the current sync.Pool is that the New func() field is exported. This makes it easy to accidentally call New directly instead of using the Get method. Maybe we want to hide it somehow?

How the Pool is going to behave with non-pointers? Will Put() cause allocation for let's say []byte, instead of *[]byte

[Jorropo]

Part of me wants to change to:

type CondLocker[T any] interface {
	Locker
	*T
}

type Cond[T any, L CondLocker[T]] struct {
	L T
}

// Random example pseudo code to prove this is exploitable
func (c *Cond[T, L]) Test() {
	var p L = &c.L
	p.Lock()
	p.Unlock()
}
// ...

this makes the zero value of a cond valid if the locker's zero value is valid (like Mutex),
it also allows to remove 2 pointers from Cond,
and makes it easier for the compiler to remove a virtual dispatch inside Cond.

Other part of me thinks this is too much #darkarts,
is not easily retro compatible with the old Locker interface approach,
and looks a lot like the painful parts of rust.

[Merovius]

I'm wondering if there's even a need to make Cond polymorphic. Are there any sync.Locker implementations out there that are not just *Mutex or *RWMutex? That is, would it perhaps be better to just make it Cond struct{ L Mutex }, or have two types, or make it Cond[Locker Mutex|RWMutex] struct{ L Locker }?

I'm not familiar with the use cases for Cond (I have literally never used it). But part of that is the necessity of providing a Locker explicitly, which confused me as to how it was intended to be used.

[thepudds]

I don't fully understand this piece:

type Map[K comparable, V any] struct { ... }

[...]

// CompareAndDelete deletes the entry for key if its value is equal to old.
// This panics if V is not a comparable type.
//
// If there is no current value for key in the map, CompareAndDelete
// returns false.
func (m *Map[K, V]) CompareAndDelete(key K, old V) (deleted bool)```

For panicking if V is not a comparable type and doing the equality check if V is a comparable type —
is that implementable in ordinary Go code in the current version of the compiler without resorting to reflect?

Is the intent of this proposal to use reflect, or some stdlib-only compiler or runtime magic, or would this be contingent on #45380 or some other generics enhancement?

In #47657 (comment), Ian had written:

One possibility is to permit generic types to have methods that use different, tighter, constraints. Those methods would only be available if the type argument(s) satisfied those constraints. I don't know whether that would be a good idea or not.

Separately, @Merovius pointed out in #47657 (comment):

I'll note that if we adopted #65394, you could have the constraints on Map be [K comparable, V any] and the constraints on CompareAndSwap be [K, V comparable] - that is, you would get those methods if and only if the value type is comparable as well. Having type-safety and flexibility.

... but I'm not sure what solution this proposal is relying upon (or maybe I misunderstood the issue 😅).

[Merovius]

is that implementable in ordinary Go code in the current version of the compiler without resorting to reflect?

Just realized: A trivial way to get those semantics is any(v1) == any(v2). But still, I'd strongly prefer a type-safe solution.

[jub0bs]

This is exciting!

Should Cond even be retained, though? @bcmills cogently lobbies for its deprecation. I'd rather see the inclusion of something like https://github.com/neild/gate.

[ianlancetaylor]

@mateusz834

There is one issue I’ve encountered with the current sync.Pool is that the New func() field is exported. This makes it easy to accidentally call New directly instead of using the Get method. Maybe we want to hide it somehow?

I think the goals here include

• zero value of sync.Pool should be useful
• some sort of "new" function is desirable for pooled types that requires initialization
• it should be easy to use sync.Pool as a package-scope variable

When those goals are put together, it seems hard to avoid having sync.Pool be a struct with an exported New field.

I am definitely open to suggestions.

How the Pool is going to behave with non-pointers? Will Put() cause allocation for let's say []byte, instead of *[]byte

I'm not specifying an implementation, but looking at the current implementation it seems straightforward for the v2 sync.Pool to use values of type T rather than type any, so I don't see why a Pool[[]byte] would allocate on Put. The main change is that we'll need to store an additional array of bool values in the deque to indicate whether a slot holds a valid value—the current code can use nil for an invalid value.

[ianlancetaylor]

I think we could in principle drop Cond from sync/v2 if we made it available in some other package, perhaps in x/sync. I don't know whether that would be a good idea or not. I note that the current implementation of sync.Cond relies on runtime package support.

I think that in practical use a Cond should not incorporate a Locker, it should only refer to one. Condition variables are only useful in conjunction with some sort of mutex, but code will often want to use that mutex in other ways. For example, see connReader in the net/http package. It has a cond field that uses the mu field, but the code also uses the mu field in various ways that don't touch the cond field at all. Overloading the mutex into the condition variable will make this code more obscure.

If we were designing from scratch it might make sense to make the Cond simply use a Mutex, but it would not be surprising if there are Cond variables out there that use a RWMutex, and it seems unnecessary to break them.