...

Source file src/sync/atomic/doc.go

Documentation: sync/atomic

		 1  // Copyright 2011 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  // Package atomic provides low-level atomic memory primitives
		 6  // useful for implementing synchronization algorithms.
		 7  //
		 8  // These functions require great care to be used correctly.
		 9  // Except for special, low-level applications, synchronization is better
		10  // done with channels or the facilities of the sync package.
		11  // Share memory by communicating;
		12  // don't communicate by sharing memory.
		13  //
		14  // The swap operation, implemented by the SwapT functions, is the atomic
		15  // equivalent of:
		16  //
		17  //	old = *addr
		18  //	*addr = new
		19  //	return old
		20  //
		21  // The compare-and-swap operation, implemented by the CompareAndSwapT
		22  // functions, is the atomic equivalent of:
		23  //
		24  //	if *addr == old {
		25  //		*addr = new
		26  //		return true
		27  //	}
		28  //	return false
		29  //
		30  // The add operation, implemented by the AddT functions, is the atomic
		31  // equivalent of:
		32  //
		33  //	*addr += delta
		34  //	return *addr
		35  //
		36  // The load and store operations, implemented by the LoadT and StoreT
		37  // functions, are the atomic equivalents of "return *addr" and
		38  // "*addr = val".
		39  //
		40  package atomic
		41  
		42  import (
		43  	"unsafe"
		44  )
		45  
		46  // BUG(rsc): On 386, the 64-bit functions use instructions unavailable before the Pentium MMX.
		47  //
		48  // On non-Linux ARM, the 64-bit functions use instructions unavailable before the ARMv6k core.
		49  //
		50  // On ARM, 386, and 32-bit MIPS, it is the caller's responsibility
		51  // to arrange for 64-bit alignment of 64-bit words accessed atomically.
		52  // The first word in a variable or in an allocated struct, array, or slice can
		53  // be relied upon to be 64-bit aligned.
		54  
		55  // SwapInt32 atomically stores new into *addr and returns the previous *addr value.
		56  func SwapInt32(addr *int32, new int32) (old int32)
		57  
		58  // SwapInt64 atomically stores new into *addr and returns the previous *addr value.
		59  func SwapInt64(addr *int64, new int64) (old int64)
		60  
		61  // SwapUint32 atomically stores new into *addr and returns the previous *addr value.
		62  func SwapUint32(addr *uint32, new uint32) (old uint32)
		63  
		64  // SwapUint64 atomically stores new into *addr and returns the previous *addr value.
		65  func SwapUint64(addr *uint64, new uint64) (old uint64)
		66  
		67  // SwapUintptr atomically stores new into *addr and returns the previous *addr value.
		68  func SwapUintptr(addr *uintptr, new uintptr) (old uintptr)
		69  
		70  // SwapPointer atomically stores new into *addr and returns the previous *addr value.
		71  func SwapPointer(addr *unsafe.Pointer, new unsafe.Pointer) (old unsafe.Pointer)
		72  
		73  // CompareAndSwapInt32 executes the compare-and-swap operation for an int32 value.
		74  func CompareAndSwapInt32(addr *int32, old, new int32) (swapped bool)
		75  
		76  // CompareAndSwapInt64 executes the compare-and-swap operation for an int64 value.
		77  func CompareAndSwapInt64(addr *int64, old, new int64) (swapped bool)
		78  
		79  // CompareAndSwapUint32 executes the compare-and-swap operation for a uint32 value.
		80  func CompareAndSwapUint32(addr *uint32, old, new uint32) (swapped bool)
		81  
		82  // CompareAndSwapUint64 executes the compare-and-swap operation for a uint64 value.
		83  func CompareAndSwapUint64(addr *uint64, old, new uint64) (swapped bool)
		84  
		85  // CompareAndSwapUintptr executes the compare-and-swap operation for a uintptr value.
		86  func CompareAndSwapUintptr(addr *uintptr, old, new uintptr) (swapped bool)
		87  
		88  // CompareAndSwapPointer executes the compare-and-swap operation for a unsafe.Pointer value.
		89  func CompareAndSwapPointer(addr *unsafe.Pointer, old, new unsafe.Pointer) (swapped bool)
		90  
		91  // AddInt32 atomically adds delta to *addr and returns the new value.
		92  func AddInt32(addr *int32, delta int32) (new int32)
		93  
		94  // AddUint32 atomically adds delta to *addr and returns the new value.
		95  // To subtract a signed positive constant value c from x, do AddUint32(&x, ^uint32(c-1)).
		96  // In particular, to decrement x, do AddUint32(&x, ^uint32(0)).
		97  func AddUint32(addr *uint32, delta uint32) (new uint32)
		98  
		99  // AddInt64 atomically adds delta to *addr and returns the new value.
	 100  func AddInt64(addr *int64, delta int64) (new int64)
	 101  
	 102  // AddUint64 atomically adds delta to *addr and returns the new value.
	 103  // To subtract a signed positive constant value c from x, do AddUint64(&x, ^uint64(c-1)).
	 104  // In particular, to decrement x, do AddUint64(&x, ^uint64(0)).
	 105  func AddUint64(addr *uint64, delta uint64) (new uint64)
	 106  
	 107  // AddUintptr atomically adds delta to *addr and returns the new value.
	 108  func AddUintptr(addr *uintptr, delta uintptr) (new uintptr)
	 109  
	 110  // LoadInt32 atomically loads *addr.
	 111  func LoadInt32(addr *int32) (val int32)
	 112  
	 113  // LoadInt64 atomically loads *addr.
	 114  func LoadInt64(addr *int64) (val int64)
	 115  
	 116  // LoadUint32 atomically loads *addr.
	 117  func LoadUint32(addr *uint32) (val uint32)
	 118  
	 119  // LoadUint64 atomically loads *addr.
	 120  func LoadUint64(addr *uint64) (val uint64)
	 121  
	 122  // LoadUintptr atomically loads *addr.
	 123  func LoadUintptr(addr *uintptr) (val uintptr)
	 124  
	 125  // LoadPointer atomically loads *addr.
	 126  func LoadPointer(addr *unsafe.Pointer) (val unsafe.Pointer)
	 127  
	 128  // StoreInt32 atomically stores val into *addr.
	 129  func StoreInt32(addr *int32, val int32)
	 130  
	 131  // StoreInt64 atomically stores val into *addr.
	 132  func StoreInt64(addr *int64, val int64)
	 133  
	 134  // StoreUint32 atomically stores val into *addr.
	 135  func StoreUint32(addr *uint32, val uint32)
	 136  
	 137  // StoreUint64 atomically stores val into *addr.
	 138  func StoreUint64(addr *uint64, val uint64)
	 139  
	 140  // StoreUintptr atomically stores val into *addr.
	 141  func StoreUintptr(addr *uintptr, val uintptr)
	 142  
	 143  // StorePointer atomically stores val into *addr.
	 144  func StorePointer(addr *unsafe.Pointer, val unsafe.Pointer)
	 145  

View as plain text