Documentation
¶
Overview ¶
Package atomic provides atomic operations.
On most platforms, the compiler is aware of the functions defined in this package, and they're replaced with platform-specific intrinsics. On other platforms, generic implementations are made available.
Unless otherwise noted, operations defined in this package are sequentially consistent across threads with respect to the values they manipulate. More specifically, operations that happen in a specific order on one thread, will always be observed to happen in exactly that order by another thread.
Index ¶
- func Add32(ptr *uint32, delta int32) uint32
- func Add64(ptr *uint64, delta int64) uint64
- func AddInt32(ptr *int32, delta int32) int32
- func AddInt64(ptr *int64, delta int64) int64
- func AddUintptr(ptr *uintptr, delta uintptr) uintptr
- func And8(ptr *uint8, val uint8)
- func And32(ptr *uint32, val uint32)
- func Cas32(ptr *uint32, old, new uint32) bool
- func Cas64(ptr *uint64, old, new uint64) bool
- func CasInt32(ptr *int32, old, new int32) bool
- func CasInt64(ptr *int64, old, new int64) bool
- func CasRel32(ptr *uint32, old, new uint32) bool
- func CasUintptr(ptr *uintptr, old, new uintptr) bool
- func CasUnsafePointer(ptr *unsafe.Pointer, old, new unsafe.Pointer) bool
- func Load8(ptr *uint8) uint8
- func Load32(ptr *uint32) uint32
- func Load64(ptr *uint64) uint64
- func LoadAcq32(ptr *uint32) uint32
- func LoadAcq64(ptr *uint64) uint64
- func LoadAcqUintptr(ptr *uintptr) uintptr
- func LoadInt32(ptr *int32) int32
- func LoadInt64(ptr *int64) int64
- func LoadPointer(ptr unsafe.Pointer) unsafe.Pointer
- func LoadUint(ptr *uint) uint
- func LoadUintptr(ptr *uintptr) uintptr
- func Or8(ptr *uint8, val uint8)
- func Or32(ptr *uint32, val uint32)
- func PublicationBarrier()
- func Store8(ptr *uint8, val uint8)
- func Store32(ptr *uint32, val uint32)
- func Store64(ptr *uint64, val uint64)
- func StoreInt32(ptr *int32, new int32)
- func StoreInt64(ptr *int64, new int64)
- func StorePointer(ptr unsafe.Pointer, val unsafe.Pointer)
- func StoreRel32(ptr *uint32, val uint32)
- func StoreRel64(ptr *uint64, val uint64)
- func StoreRelUintptr(ptr *uintptr, val uintptr)
- func StoreUintptr(ptr *uintptr, new uintptr)
- func Swap32(ptr *uint32, new uint32) uint32
- func Swap64(ptr *uint64, new uint64) uint64
- func SwapInt32(ptr *int32, new int32) int32
- func SwapInt64(ptr *int64, new int64) int64
- func SwapUintptr(ptr *uintptr, new uintptr) uintptr
- type Bool
- type Float64
- type Int32
- type Int64
- type Pointer
- type Uint8
- type Uint32
- func (u *Uint32[T]) Add(delta int32) T
- func (u *Uint32[T]) And(value T)
- func (u *Uint32[T]) Cas(old, new T) bool
- func (u *Uint32[T]) CasRelease(old, new T) bool
- func (u *Uint32[T]) Load() T
- func (u *Uint32[T]) LoadAcquire() T
- func (u *Uint32[T]) Or(value T)
- func (u *Uint32[T]) Store(value T)
- func (u *Uint32[T]) StoreRelease(value T)
- func (u *Uint32[T]) Swap(value T) T
- type Uint64
- type Uintptr
- type UnsafePointer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddUintptr ¶
func CasUintptr ¶
func CasUnsafePointer ¶
NO go:noescape annotation; see atomic_pointer.go.
func LoadAcqUintptr ¶
func LoadUintptr ¶
func PublicationBarrier ¶
func PublicationBarrier()
PublicationBarrier performs a store/store barrier (a "publication" or "export" barrier). Some form of synchronization is required between initializing an object and making that object accessible to another processor. Without synchronization, the initialization writes and the "publication" write may be reordered, allowing the other processor to follow the pointer and observe an uninitialized object. In general, higher-level synchronization should be used, such as locking or an atomic pointer write. publicationBarrier is for when those aren't an option, such as in the implementation of the memory manager.
There's no corresponding barrier for the read side because the read side naturally has a data dependency order. All architectures that Go supports or seems likely to ever support automatically enforce data dependency ordering.
func StoreInt32 ¶
func StoreInt64 ¶
func StorePointer ¶
StorePointer performs *ptr = val atomically and without a write barrier.
NO go:noescape annotation; see atomic_pointer.go.
func StoreRel32 ¶
func StoreRel64 ¶
func StoreRelUintptr ¶
func StoreUintptr ¶
func SwapUintptr ¶
Types ¶
type Float64 ¶
Float64 is an atomically accessed float64 value.
8-byte aligned on all platforms, unlike a regular float64.
A Float64 must not be copied.
type Int32 ¶
type Int32[T ~int32] struct { Value T // contains filtered or unexported fields }
Int32 is an atomically accessed int32 value.
An Int32 must not be copied.
func (*Int32[T]) Add ¶
func (i *Int32[T]) Add(delta T) T
Add adds delta to i atomically, returning the new updated value.
This operation wraps around in the usual two's-complement way.
type Int64 ¶
type Int64[T ~int64] struct { Value T // contains filtered or unexported fields }
Int64 is an atomically accessed int64 value.
8-byte aligned on all platforms, unlike a regular int64.
An Int64 must not be copied.
func (*Int64[T]) Add ¶
func (i *Int64[T]) Add(delta T) T
Add adds delta to i atomically, returning the new updated value.
This operation wraps around in the usual two's-complement way.
type Pointer ¶
type Pointer[T any] struct { UnsafePointer }
Pointer is an atomic pointer of type *T.
func (*Pointer[T]) Cas ¶
Cas atomically (with respect to other methods) compares u's value with old, and if they're equal, swaps u's value with new. It reports whether the swap ran.
func (*Pointer[T]) CasNoWB ¶
CasNoWB atomically (with respect to other methods) compares u's value with old, and if they're equal, swaps u's value with new. It reports whether the swap ran.
WARNING: As the name implies this operation does *not* perform a write barrier on value, and so this operation may hide pointers from the GC. Use with care and sparingly. It is safe to use with values not found in the Go heap. Prefer Cas instead.
func (*Pointer[T]) Load ¶
func (p *Pointer[T]) Load() *T
Load accesses and returns the value atomically.
func (*Pointer[T]) StoreNoWB ¶
func (p *Pointer[T]) StoreNoWB(value *T)
StoreNoWB updates the value atomically.
WARNING: As the name implies this operation does *not* perform a write barrier on value, and so this operation may hide pointers from the GC. Use with care and sparingly. It is safe to use with values not found in the Go heap. Prefer Store instead.
type Uint8 ¶
type Uint8[T ~uint8] struct { Value T // contains filtered or unexported fields }
Uint8 is an atomically accessed uint8 value.
A Uint8 must not be copied.
func (*Uint8[T]) And ¶
func (u *Uint8[T]) And(value T)
And takes value and performs a bit-wise "and" operation with the value of u, storing the result into u.
The full process is performed atomically.
type Uint32 ¶
type Uint32[T ~uint32] struct { Value T // contains filtered or unexported fields }
Uint32 is an atomically accessed uint32 value.
A Uint32 must not be copied.
func (*Uint32[T]) Add ¶
Add adds delta to u atomically, returning the new updated value.
This operation wraps around in the usual two's-complement way.
func (*Uint32[T]) And ¶
func (u *Uint32[T]) And(value T)
And takes value and performs a bit-wise "and" operation with the value of u, storing the result into u.
The full process is performed atomically.
func (*Uint32[T]) Cas ¶
Cas atomically compares u's value with old, and if they're equal, swaps u's value with new. It reports whether the swap ran.
func (*Uint32[T]) CasRelease ¶
CasRelease is a partially unsynchronized version of Cas that relaxes ordering constraints. Other threads may observe operations that occur after this operation to precede it, but no operation that precedes it on this thread can be observed to occur after it. It reports whether the swap ran.
WARNING: Use sparingly and with great care.
func (*Uint32[T]) Load ¶
func (u *Uint32[T]) Load() T
Load accesses and returns the value atomically.
func (*Uint32[T]) LoadAcquire ¶
func (u *Uint32[T]) LoadAcquire() T
LoadAcquire is a partially unsynchronized version of Load that relaxes ordering constraints. Other threads may observe operations that precede this operation to occur after it, but no operation that occurs after it on this thread can be observed to occur before it.
WARNING: Use sparingly and with great care.
func (*Uint32[T]) Or ¶
func (u *Uint32[T]) Or(value T)
Or takes value and performs a bit-wise "or" operation with the value of u, storing the result into u.
The full process is performed atomically.
func (*Uint32[T]) StoreRelease ¶
func (u *Uint32[T]) StoreRelease(value T)
StoreRelease is a partially unsynchronized version of Store that relaxes ordering constraints. Other threads may observe operations that occur after this operation to precede it, but no operation that precedes it on this thread can be observed to occur after it.
WARNING: Use sparingly and with great care.
type Uint64 ¶
type Uint64[T ~uint64] struct { Value T // contains filtered or unexported fields }
Uint64 is an atomically accessed uint64 value.
8-byte aligned on all platforms, unlike a regular uint64.
A Uint64 must not be copied.
func (*Uint64[T]) Add ¶
Add adds delta to u atomically, returning the new updated value.
This operation wraps around in the usual two's-complement way.
func (*Uint64[T]) Cas ¶
Cas atomically compares u's value with old, and if they're equal, swaps u's value with new. It reports whether the swap ran.
func (*Uint64[T]) Load ¶
func (u *Uint64[T]) Load() T
Load accesses and returns the value atomically.
func (*Uint64[T]) LoadAcquire ¶
func (u *Uint64[T]) LoadAcquire() T
LoadAcquire is a partially unsynchronized version of Load that relaxes ordering constraints. Other threads may observe operations that precede this operation to occur after it, but no operation that occurs after it on this thread can be observed to occur before it.
WARNING: Use sparingly and with great care.
func (*Uint64[T]) StoreRelease ¶
func (u *Uint64[T]) StoreRelease(value T)
StoreRelease is a partially unsynchronized version of Store that relaxes ordering constraints. Other threads may observe operations that occur after this operation to precede it, but no operation that precedes it on this thread can be observed to occur after it.
WARNING: Use sparingly and with great care.
type Uintptr ¶
type Uintptr[T ~uintptr] struct { Value T // contains filtered or unexported fields }
Uintptr is an atomically accessed uintptr value.
A Uintptr must not be copied.
func (*Uintptr[T]) Add ¶
func (u *Uintptr[T]) Add(delta T) T
Add adds delta to u atomically, returning the new updated value.
This operation wraps around in the usual two's-complement way.
func (*Uintptr[T]) Cas ¶
Cas atomically compares u's value with old, and if they're equal, swaps u's value with new. It reports whether the swap ran.
func (*Uintptr[T]) Load ¶
func (u *Uintptr[T]) Load() T
Load accesses and returns the value atomically.
func (*Uintptr[T]) LoadAcquire ¶
func (u *Uintptr[T]) LoadAcquire() T
LoadAcquire is a partially unsynchronized version of Load that relaxes ordering constraints. Other threads may observe operations that precede this operation to occur after it, but no operation that occurs after it on this thread can be observed to occur before it.
WARNING: Use sparingly and with great care.
func (*Uintptr[T]) StoreRelease ¶
func (u *Uintptr[T]) StoreRelease(value T)
StoreRelease is a partially unsynchronized version of Store that relaxes ordering constraints. Other threads may observe operations that occur after this operation to precede it, but no operation that precedes it on this thread can be observed to occur after it.
WARNING: Use sparingly and with great care.
type UnsafePointer ¶
UnsafePointer is an atomically accessed unsafe.Pointer value.
Note that because of the atomicity guarantees, stores to values of this type never trigger a write barrier, and the relevant methods are suffixed with "NoWB" to indicate that explicitly. As a result, this type should be used carefully, and sparingly, mostly with values that do not live in the Go heap anyway.
An UnsafePointer must not be copied.
func (*UnsafePointer) Cas ¶
func (u *UnsafePointer) Cas(old, new unsafe.Pointer) bool
Cas atomically compares u's value with old, and if they're equal, swaps u's value with new. It reports whether the swap ran.
func (*UnsafePointer) CasNoWB ¶
func (u *UnsafePointer) CasNoWB(old, new unsafe.Pointer) bool
CasNoWB atomically (with respect to other methods) compares u's value with old, and if they're equal, swaps u's value with new. It reports whether the swap ran.
WARNING: As the name implies this operation does *not* perform a write barrier on value, and so this operation may hide pointers from the GC. Use with care and sparingly. It is safe to use with values not found in the Go heap. Prefer Cas instead.
func (*UnsafePointer) Load ¶
func (u *UnsafePointer) Load() unsafe.Pointer
Load accesses and returns the value atomically.
func (*UnsafePointer) Store ¶
func (u *UnsafePointer) Store(value unsafe.Pointer)
Store updates the value atomically.
func (*UnsafePointer) StoreNoWB ¶
func (u *UnsafePointer) StoreNoWB(value unsafe.Pointer)
StoreNoWB updates the value atomically.
WARNING: As the name implies this operation does *not* perform a write barrier on value, and so this operation may hide pointers from the GC. Use with care and sparingly. It is safe to use with values not found in the Go heap. Prefer Store instead.
Source Files
Directories