Source file src/internal/runtime/atomic/types.go

     1  // Copyright 2021 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
     6  
     7  import "unsafe"
     8  
     9  // Int32 is an atomically accessed int32 value.
    10  //
    11  // An Int32 must not be copied.
    12  type Int32 struct {
    13  	noCopy noCopy
    14  	value  int32
    15  }
    16  
    17  // Load accesses and returns the value atomically.
    18  //
    19  //go:nosplit
    20  func (i *Int32) Load() int32 {
    21  	return Loadint32(&i.value)
    22  }
    23  
    24  // Store updates the value atomically.
    25  //
    26  //go:nosplit
    27  func (i *Int32) Store(value int32) {
    28  	Storeint32(&i.value, value)
    29  }
    30  
    31  // CompareAndSwap atomically compares i's value with old,
    32  // and if they're equal, swaps i's value with new.
    33  // It reports whether the swap ran.
    34  //
    35  //go:nosplit
    36  func (i *Int32) CompareAndSwap(old, new int32) bool {
    37  	return Casint32(&i.value, old, new)
    38  }
    39  
    40  // Swap replaces i's value with new, returning
    41  // i's value before the replacement.
    42  //
    43  //go:nosplit
    44  func (i *Int32) Swap(new int32) int32 {
    45  	return Xchgint32(&i.value, new)
    46  }
    47  
    48  // Add adds delta to i atomically, returning
    49  // the new updated value.
    50  //
    51  // This operation wraps around in the usual
    52  // two's-complement way.
    53  //
    54  //go:nosplit
    55  func (i *Int32) Add(delta int32) int32 {
    56  	return Xaddint32(&i.value, delta)
    57  }
    58  
    59  // Int64 is an atomically accessed int64 value.
    60  //
    61  // 8-byte aligned on all platforms, unlike a regular int64.
    62  //
    63  // An Int64 must not be copied.
    64  type Int64 struct {
    65  	noCopy noCopy
    66  	_      align64
    67  	value  int64
    68  }
    69  
    70  // Load accesses and returns the value atomically.
    71  //
    72  //go:nosplit
    73  func (i *Int64) Load() int64 {
    74  	return Loadint64(&i.value)
    75  }
    76  
    77  // Store updates the value atomically.
    78  //
    79  //go:nosplit
    80  func (i *Int64) Store(value int64) {
    81  	Storeint64(&i.value, value)
    82  }
    83  
    84  // CompareAndSwap atomically compares i's value with old,
    85  // and if they're equal, swaps i's value with new.
    86  // It reports whether the swap ran.
    87  //
    88  //go:nosplit
    89  func (i *Int64) CompareAndSwap(old, new int64) bool {
    90  	return Casint64(&i.value, old, new)
    91  }
    92  
    93  // Swap replaces i's value with new, returning
    94  // i's value before the replacement.
    95  //
    96  //go:nosplit
    97  func (i *Int64) Swap(new int64) int64 {
    98  	return Xchgint64(&i.value, new)
    99  }
   100  
   101  // Add adds delta to i atomically, returning
   102  // the new updated value.
   103  //
   104  // This operation wraps around in the usual
   105  // two's-complement way.
   106  //
   107  //go:nosplit
   108  func (i *Int64) Add(delta int64) int64 {
   109  	return Xaddint64(&i.value, delta)
   110  }
   111  
   112  // Uint8 is an atomically accessed uint8 value.
   113  //
   114  // A Uint8 must not be copied.
   115  type Uint8 struct {
   116  	noCopy noCopy
   117  	value  uint8
   118  }
   119  
   120  // Load accesses and returns the value atomically.
   121  //
   122  //go:nosplit
   123  func (u *Uint8) Load() uint8 {
   124  	return Load8(&u.value)
   125  }
   126  
   127  // Store updates the value atomically.
   128  //
   129  //go:nosplit
   130  func (u *Uint8) Store(value uint8) {
   131  	Store8(&u.value, value)
   132  }
   133  
   134  // And takes value and performs a bit-wise
   135  // "and" operation with the value of u, storing
   136  // the result into u.
   137  //
   138  // The full process is performed atomically.
   139  //
   140  //go:nosplit
   141  func (u *Uint8) And(value uint8) {
   142  	And8(&u.value, value)
   143  }
   144  
   145  // Or takes value and performs a bit-wise
   146  // "or" operation with the value of u, storing
   147  // the result into u.
   148  //
   149  // The full process is performed atomically.
   150  //
   151  //go:nosplit
   152  func (u *Uint8) Or(value uint8) {
   153  	Or8(&u.value, value)
   154  }
   155  
   156  // Bool is an atomically accessed bool value.
   157  //
   158  // A Bool must not be copied.
   159  type Bool struct {
   160  	// Inherits noCopy from Uint8.
   161  	u Uint8
   162  }
   163  
   164  // Load accesses and returns the value atomically.
   165  //
   166  //go:nosplit
   167  func (b *Bool) Load() bool {
   168  	return b.u.Load() != 0
   169  }
   170  
   171  // Store updates the value atomically.
   172  //
   173  //go:nosplit
   174  func (b *Bool) Store(value bool) {
   175  	s := uint8(0)
   176  	if value {
   177  		s = 1
   178  	}
   179  	b.u.Store(s)
   180  }
   181  
   182  // Uint32 is an atomically accessed uint32 value.
   183  //
   184  // A Uint32 must not be copied.
   185  type Uint32 struct {
   186  	noCopy noCopy
   187  	value  uint32
   188  }
   189  
   190  // Load accesses and returns the value atomically.
   191  //
   192  //go:nosplit
   193  func (u *Uint32) Load() uint32 {
   194  	return Load(&u.value)
   195  }
   196  
   197  // LoadAcquire is a partially unsynchronized version
   198  // of Load that relaxes ordering constraints. Other threads
   199  // may observe operations that precede this operation to
   200  // occur after it, but no operation that occurs after it
   201  // on this thread can be observed to occur before it.
   202  //
   203  // WARNING: Use sparingly and with great care.
   204  //
   205  //go:nosplit
   206  func (u *Uint32) LoadAcquire() uint32 {
   207  	return LoadAcq(&u.value)
   208  }
   209  
   210  // Store updates the value atomically.
   211  //
   212  //go:nosplit
   213  func (u *Uint32) Store(value uint32) {
   214  	Store(&u.value, value)
   215  }
   216  
   217  // StoreRelease is a partially unsynchronized version
   218  // of Store that relaxes ordering constraints. Other threads
   219  // may observe operations that occur after this operation to
   220  // precede it, but no operation that precedes it
   221  // on this thread can be observed to occur after it.
   222  //
   223  // WARNING: Use sparingly and with great care.
   224  //
   225  //go:nosplit
   226  func (u *Uint32) StoreRelease(value uint32) {
   227  	StoreRel(&u.value, value)
   228  }
   229  
   230  // CompareAndSwap atomically compares u's value with old,
   231  // and if they're equal, swaps u's value with new.
   232  // It reports whether the swap ran.
   233  //
   234  //go:nosplit
   235  func (u *Uint32) CompareAndSwap(old, new uint32) bool {
   236  	return Cas(&u.value, old, new)
   237  }
   238  
   239  // CompareAndSwapRelease is a partially unsynchronized version
   240  // of Cas that relaxes ordering constraints. Other threads
   241  // may observe operations that occur after this operation to
   242  // precede it, but no operation that precedes it
   243  // on this thread can be observed to occur after it.
   244  // It reports whether the swap ran.
   245  //
   246  // WARNING: Use sparingly and with great care.
   247  //
   248  //go:nosplit
   249  func (u *Uint32) CompareAndSwapRelease(old, new uint32) bool {
   250  	return CasRel(&u.value, old, new)
   251  }
   252  
   253  // Swap replaces u's value with new, returning
   254  // u's value before the replacement.
   255  //
   256  //go:nosplit
   257  func (u *Uint32) Swap(value uint32) uint32 {
   258  	return Xchg(&u.value, value)
   259  }
   260  
   261  // And takes value and performs a bit-wise
   262  // "and" operation with the value of u, storing
   263  // the result into u.
   264  //
   265  // The full process is performed atomically.
   266  //
   267  //go:nosplit
   268  func (u *Uint32) And(value uint32) {
   269  	And(&u.value, value)
   270  }
   271  
   272  // Or takes value and performs a bit-wise
   273  // "or" operation with the value of u, storing
   274  // the result into u.
   275  //
   276  // The full process is performed atomically.
   277  //
   278  //go:nosplit
   279  func (u *Uint32) Or(value uint32) {
   280  	Or(&u.value, value)
   281  }
   282  
   283  // Add adds delta to u atomically, returning
   284  // the new updated value.
   285  //
   286  // This operation wraps around in the usual
   287  // two's-complement way.
   288  //
   289  //go:nosplit
   290  func (u *Uint32) Add(delta int32) uint32 {
   291  	return Xadd(&u.value, delta)
   292  }
   293  
   294  // Uint64 is an atomically accessed uint64 value.
   295  //
   296  // 8-byte aligned on all platforms, unlike a regular uint64.
   297  //
   298  // A Uint64 must not be copied.
   299  type Uint64 struct {
   300  	noCopy noCopy
   301  	_      align64
   302  	value  uint64
   303  }
   304  
   305  // Load accesses and returns the value atomically.
   306  //
   307  //go:nosplit
   308  func (u *Uint64) Load() uint64 {
   309  	return Load64(&u.value)
   310  }
   311  
   312  // Store updates the value atomically.
   313  //
   314  //go:nosplit
   315  func (u *Uint64) Store(value uint64) {
   316  	Store64(&u.value, value)
   317  }
   318  
   319  // CompareAndSwap atomically compares u's value with old,
   320  // and if they're equal, swaps u's value with new.
   321  // It reports whether the swap ran.
   322  //
   323  //go:nosplit
   324  func (u *Uint64) CompareAndSwap(old, new uint64) bool {
   325  	return Cas64(&u.value, old, new)
   326  }
   327  
   328  // Swap replaces u's value with new, returning
   329  // u's value before the replacement.
   330  //
   331  //go:nosplit
   332  func (u *Uint64) Swap(value uint64) uint64 {
   333  	return Xchg64(&u.value, value)
   334  }
   335  
   336  // Add adds delta to u atomically, returning
   337  // the new updated value.
   338  //
   339  // This operation wraps around in the usual
   340  // two's-complement way.
   341  //
   342  //go:nosplit
   343  func (u *Uint64) Add(delta int64) uint64 {
   344  	return Xadd64(&u.value, delta)
   345  }
   346  
   347  // Uintptr is an atomically accessed uintptr value.
   348  //
   349  // A Uintptr must not be copied.
   350  type Uintptr struct {
   351  	noCopy noCopy
   352  	value  uintptr
   353  }
   354  
   355  // Load accesses and returns the value atomically.
   356  //
   357  //go:nosplit
   358  func (u *Uintptr) Load() uintptr {
   359  	return Loaduintptr(&u.value)
   360  }
   361  
   362  // LoadAcquire is a partially unsynchronized version
   363  // of Load that relaxes ordering constraints. Other threads
   364  // may observe operations that precede this operation to
   365  // occur after it, but no operation that occurs after it
   366  // on this thread can be observed to occur before it.
   367  //
   368  // WARNING: Use sparingly and with great care.
   369  //
   370  //go:nosplit
   371  func (u *Uintptr) LoadAcquire() uintptr {
   372  	return LoadAcquintptr(&u.value)
   373  }
   374  
   375  // Store updates the value atomically.
   376  //
   377  //go:nosplit
   378  func (u *Uintptr) Store(value uintptr) {
   379  	Storeuintptr(&u.value, value)
   380  }
   381  
   382  // StoreRelease is a partially unsynchronized version
   383  // of Store that relaxes ordering constraints. Other threads
   384  // may observe operations that occur after this operation to
   385  // precede it, but no operation that precedes it
   386  // on this thread can be observed to occur after it.
   387  //
   388  // WARNING: Use sparingly and with great care.
   389  //
   390  //go:nosplit
   391  func (u *Uintptr) StoreRelease(value uintptr) {
   392  	StoreReluintptr(&u.value, value)
   393  }
   394  
   395  // CompareAndSwap atomically compares u's value with old,
   396  // and if they're equal, swaps u's value with new.
   397  // It reports whether the swap ran.
   398  //
   399  //go:nosplit
   400  func (u *Uintptr) CompareAndSwap(old, new uintptr) bool {
   401  	return Casuintptr(&u.value, old, new)
   402  }
   403  
   404  // Swap replaces u's value with new, returning
   405  // u's value before the replacement.
   406  //
   407  //go:nosplit
   408  func (u *Uintptr) Swap(value uintptr) uintptr {
   409  	return Xchguintptr(&u.value, value)
   410  }
   411  
   412  // Add adds delta to u atomically, returning
   413  // the new updated value.
   414  //
   415  // This operation wraps around in the usual
   416  // two's-complement way.
   417  //
   418  //go:nosplit
   419  func (u *Uintptr) Add(delta uintptr) uintptr {
   420  	return Xadduintptr(&u.value, delta)
   421  }
   422  
   423  // Float64 is an atomically accessed float64 value.
   424  //
   425  // 8-byte aligned on all platforms, unlike a regular float64.
   426  //
   427  // A Float64 must not be copied.
   428  type Float64 struct {
   429  	// Inherits noCopy and align64 from Uint64.
   430  	u Uint64
   431  }
   432  
   433  // Load accesses and returns the value atomically.
   434  //
   435  //go:nosplit
   436  func (f *Float64) Load() float64 {
   437  	r := f.u.Load()
   438  	return *(*float64)(unsafe.Pointer(&r))
   439  }
   440  
   441  // Store updates the value atomically.
   442  //
   443  //go:nosplit
   444  func (f *Float64) Store(value float64) {
   445  	f.u.Store(*(*uint64)(unsafe.Pointer(&value)))
   446  }
   447  
   448  // UnsafePointer is an atomically accessed unsafe.Pointer value.
   449  //
   450  // Note that because of the atomicity guarantees, stores to values
   451  // of this type never trigger a write barrier, and the relevant
   452  // methods are suffixed with "NoWB" to indicate that explicitly.
   453  // As a result, this type should be used carefully, and sparingly,
   454  // mostly with values that do not live in the Go heap anyway.
   455  //
   456  // An UnsafePointer must not be copied.
   457  type UnsafePointer struct {
   458  	noCopy noCopy
   459  	value  unsafe.Pointer
   460  }
   461  
   462  // Load accesses and returns the value atomically.
   463  //
   464  //go:nosplit
   465  func (u *UnsafePointer) Load() unsafe.Pointer {
   466  	return Loadp(unsafe.Pointer(&u.value))
   467  }
   468  
   469  // StoreNoWB updates the value atomically.
   470  //
   471  // WARNING: As the name implies this operation does *not*
   472  // perform a write barrier on value, and so this operation may
   473  // hide pointers from the GC. Use with care and sparingly.
   474  // It is safe to use with values not found in the Go heap.
   475  // Prefer Store instead.
   476  //
   477  //go:nosplit
   478  func (u *UnsafePointer) StoreNoWB(value unsafe.Pointer) {
   479  	StorepNoWB(unsafe.Pointer(&u.value), value)
   480  }
   481  
   482  // Store updates the value atomically.
   483  func (u *UnsafePointer) Store(value unsafe.Pointer) {
   484  	storePointer(&u.value, value)
   485  }
   486  
   487  // provided by runtime
   488  //
   489  //go:linkname storePointer
   490  func storePointer(ptr *unsafe.Pointer, new unsafe.Pointer)
   491  
   492  // CompareAndSwapNoWB atomically (with respect to other methods)
   493  // compares u's value with old, and if they're equal,
   494  // swaps u's value with new.
   495  // It reports whether the swap ran.
   496  //
   497  // WARNING: As the name implies this operation does *not*
   498  // perform a write barrier on value, and so this operation may
   499  // hide pointers from the GC. Use with care and sparingly.
   500  // It is safe to use with values not found in the Go heap.
   501  // Prefer CompareAndSwap instead.
   502  //
   503  //go:nosplit
   504  func (u *UnsafePointer) CompareAndSwapNoWB(old, new unsafe.Pointer) bool {
   505  	return Casp1(&u.value, old, new)
   506  }
   507  
   508  // CompareAndSwap atomically compares u's value with old,
   509  // and if they're equal, swaps u's value with new.
   510  // It reports whether the swap ran.
   511  func (u *UnsafePointer) CompareAndSwap(old, new unsafe.Pointer) bool {
   512  	return casPointer(&u.value, old, new)
   513  }
   514  
   515  func casPointer(ptr *unsafe.Pointer, old, new unsafe.Pointer) bool
   516  
   517  // Pointer is an atomic pointer of type *T.
   518  type Pointer[T any] struct {
   519  	u UnsafePointer
   520  }
   521  
   522  // Load accesses and returns the value atomically.
   523  //
   524  //go:nosplit
   525  func (p *Pointer[T]) Load() *T {
   526  	return (*T)(p.u.Load())
   527  }
   528  
   529  // StoreNoWB updates the value atomically.
   530  //
   531  // WARNING: As the name implies this operation does *not*
   532  // perform a write barrier on value, and so this operation may
   533  // hide pointers from the GC. Use with care and sparingly.
   534  // It is safe to use with values not found in the Go heap.
   535  // Prefer Store instead.
   536  //
   537  //go:nosplit
   538  func (p *Pointer[T]) StoreNoWB(value *T) {
   539  	p.u.StoreNoWB(unsafe.Pointer(value))
   540  }
   541  
   542  // Store updates the value atomically.
   543  //
   544  //go:nosplit
   545  func (p *Pointer[T]) Store(value *T) {
   546  	p.u.Store(unsafe.Pointer(value))
   547  }
   548  
   549  // CompareAndSwapNoWB atomically (with respect to other methods)
   550  // compares u's value with old, and if they're equal,
   551  // swaps u's value with new.
   552  // It reports whether the swap ran.
   553  //
   554  // WARNING: As the name implies this operation does *not*
   555  // perform a write barrier on value, and so this operation may
   556  // hide pointers from the GC. Use with care and sparingly.
   557  // It is safe to use with values not found in the Go heap.
   558  // Prefer CompareAndSwap instead.
   559  //
   560  //go:nosplit
   561  func (p *Pointer[T]) CompareAndSwapNoWB(old, new *T) bool {
   562  	return p.u.CompareAndSwapNoWB(unsafe.Pointer(old), unsafe.Pointer(new))
   563  }
   564  
   565  // CompareAndSwap atomically (with respect to other methods)
   566  // compares u's value with old, and if they're equal,
   567  // swaps u's value with new.
   568  // It reports whether the swap ran.
   569  func (p *Pointer[T]) CompareAndSwap(old, new *T) bool {
   570  	return p.u.CompareAndSwap(unsafe.Pointer(old), unsafe.Pointer(new))
   571  }
   572  
   573  // noCopy may be embedded into structs which must not be copied
   574  // after the first use.
   575  //
   576  // See https://golang.org/issues/8005#issuecomment-190753527
   577  // for details.
   578  type noCopy struct{}
   579  
   580  // Lock is a no-op used by -copylocks checker from `go vet`.
   581  func (*noCopy) Lock()   {}
   582  func (*noCopy) Unlock() {}
   583  
   584  // align64 may be added to structs that must be 64-bit aligned.
   585  // This struct is recognized by a special case in the compiler
   586  // and will not work if copied to any other package.
   587  type align64 struct{}
   588  

View as plain text