libgo/go/sync/atomic/doc.go

   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 compare-and-swap operation, implemented by the CompareAndSwapT
  15 // functions, is the atomic equivalent of:
  16 //
  17 //      if *val == old {
  18 //              *val = new
  19 //              return true
  20 //      }
  21 //      return false
  22 //
  23 package atomic
  24
  25 // BUG(rsc): On ARM, the 64-bit functions use instructions unavailable before ARM 11.
  26 //
  27 // On x86-32, the 64-bit functions use instructions unavailable before the Pentium.
  28
  29 // CompareAndSwapInt32 executes the compare-and-swap operation for an int32 value.
  30 func CompareAndSwapInt32(val *int32, old, new int32) (swapped bool)
  31
  32 // CompareAndSwapInt64 executes the compare-and-swap operation for an int64 value.
  33 func CompareAndSwapInt64(val *int64, old, new int64) (swapped bool)
  34
  35 // CompareAndSwapUint32 executes the compare-and-swap operation for a uint32 value.
  36 func CompareAndSwapUint32(val *uint32, old, new uint32) (swapped bool)
  37
  38 // CompareAndSwapUint64 executes the compare-and-swap operation for a uint64 value.
  39 func CompareAndSwapUint64(val *uint64, old, new uint64) (swapped bool)
  40
  41 // CompareAndSwapUintptr executes the compare-and-swap operation for a uintptr value.
  42 func CompareAndSwapUintptr(val *uintptr, old, new uintptr) (swapped bool)
  43
  44 // AddInt32 atomically adds delta to *val and returns the new value.
  45 func AddInt32(val *int32, delta int32) (new int32)
  46
  47 // AddUint32 atomically adds delta to *val and returns the new value.
  48 func AddUint32(val *uint32, delta uint32) (new uint32)
  49
  50 // AddInt64 atomically adds delta to *val and returns the new value.
  51 func AddInt64(val *int64, delta int64) (new int64)
  52
  53 // AddUint64 atomically adds delta to *val and returns the new value.
  54 func AddUint64(val *uint64, delta uint64) (new uint64)
  55
  56 // AddUintptr atomically adds delta to *val and returns the new value.
  57 func AddUintptr(val *uintptr, delta uintptr) (new uintptr)
  58
  59 // LoadInt32 atomically loads *addr.
  60 func LoadInt32(addr *int32) (val int32)
  61
  62 // LoadUint32 atomically loads *addr.
  63 func LoadUint32(addr *uint32) (val uint32)
  64
  65 // Helper for ARM.  Linker will discard on other systems
  66 func panic64() {
  67         panic("sync/atomic: broken 64-bit atomic operations (buggy QEMU)")
  68 }