README
¶
percpu
Percpu is a Go package to support best-effort CPU-local sharded values.
This package is something of an experiment. See Go issue #18802 for discussion about adding this functionality into the Go standard library.
This version is updated to use generics.
IMPORTANT CAVEATS
- This package uses
go:linknameto access unexported functions from inside the Go runtime. Those could be changed or removed in a future Go version, breaking this package. - It may be tempting to use this package to solve problems for which there are better solutions that do not break key abstractions of the runtime.
See When to use percpu for a discussion about when this package may or may not be appropriate.
Documentation
¶
Overview ¶
Package percpu provides best-effort CPU-local sharded values.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
A Counter is an int64 counter which may be efficiently incremented by many goroutines concurrently.
The counter is sharded into several CPU-local values which are written and read independently. Thus, the Load and Reset methods do not observe a consistent view of the total if they are called concurrently to Add.
For example, suppose goroutine G1 runs
counter.Add(1) counter.Add(2)
and, concurrently, G2 runs
t0 := counter.Reset() // wait for G1 to finish executing t1 := counter.Load()
The value of t0 may be any of 0, 1, 2, or 3. The value of t1 may be any of 0, 1, 2, or 3 as well. However, t0+t1 must equal 3.
func NewCounter ¶
func NewCounter() *Counter
NewCounter returns a fresh Counter initialized to zero.
type Values ¶
type Values[T any] struct { // contains filtered or unexported fields }
Values is a sharded set of values which have an affinity for a particular processor. This can be used to avoid cache contention when updating a shared value simultaneously from many goroutines.
A zero value of a Values is ready to use. Values must not be copied after first use.
func (*Values[T]) Get ¶
func (v *Values[T]) Get() *T
Get returns a pointer to one of the values in v.
The pointer tends to be the one associated with the current processor. However, goroutines can migrate at any time, and it may be the case that a different goroutine is accessing the same pointer concurrently. All access of the returned value must use further synchronization mechanisms.
If a value for a given CPU does not exist yet, Values allocates a new zero value. The value is guaranteed to be allocated in a memory block with sufficient padding to avoid false sharing. Standard value alignment guarantees apply. This means that the implementation does NOT guarantee that a 64-bit integer will be aligned to the 64-bit boundary on 32-bit systems. See also Bugs section in the documentation of sync/atomic.
A pointer returned by Get will be observed by Range forever, there isn't a way to free any of the values.
func (*Values[T]) Range ¶
func (v *Values[T]) Range(fn func(p *T))
Range runs fn on all values in v.
fn may be called zero or more times. fn might observe a new p before any goroutine calling Get has a chance to initialize it.
The pointers might be concurrently used by other goroutines. The user is responsible for synchronizing access to p.
Source Files
Directories