README

atomic

Simple wrappers for primitive types to enforce atomic access.

Installation

$ go get -u go.uber.org/atomic@v1

Legacy Import Path

As of v1.5.0, the import path go.uber.org/atomic is the only supported way of using this package. If you are using Go modules, this package will fail to compile with the legacy import path path github.com/uber-go/atomic.

We recommend migrating your code to the new import path but if you're unable to do so, or if your dependencies are still using the old import path, you will have to add a replace directive to your go.mod file downgrading the legacy import path to an older version.

replace github.com/uber-go/atomic => github.com/uber-go/atomic v1.4.0

You can do so automatically by running the following command.

$ go mod edit -replace github.com/uber-go/atomic=github.com/uber-go/atomic@v1.4.0

Usage

The standard library's sync/atomic is powerful, but it's easy to forget which variables must be accessed atomically. go.uber.org/atomic preserves all the functionality of the standard library, but wraps the primitive types to provide a safer, more convenient API.

var atom atomic.Uint32
atom.Store(42)
atom.Sub(2)
atom.CAS(40, 11)

See the documentation for a complete API specification.

Development Status

Stable.

---

Released under the MIT License.

Documentation

Overview

Package atomic provides simple wrappers around numerics to enforce atomic access.

Example

package main import ( "fmt" "go.uber.org/atomic" ) func main() { // Uint32 is a thin wrapper around the primitive uint32 type. var atom atomic.Uint32 // The wrapper ensures that all operations are atomic. atom.Store(42) fmt.Println(atom.Inc()) fmt.Println(atom.CAS(43, 0)) fmt.Println(atom.Load()) }

Output:

43
true
0

Index

• type Bool
  • func NewBool(v bool) *Bool
  • func (x *Bool) CAS(o, n bool) bool
  • func (x *Bool) Load() bool
  • func (x *Bool) MarshalJSON() ([]byte, error)
  • func (x *Bool) Store(v bool)
  • func (b *Bool) String() string
  • func (x *Bool) Swap(o bool) bool
  • func (b *Bool) Toggle() bool
  • func (x *Bool) UnmarshalJSON(b []byte) error
• type Duration
  • func NewDuration(v time.Duration) *Duration
  • func (d *Duration) Add(n time.Duration) time.Duration
  • func (x *Duration) CAS(o, n time.Duration) bool
  • func (x *Duration) Load() time.Duration
  • func (x *Duration) MarshalJSON() ([]byte, error)
  • func (x *Duration) Store(v time.Duration)
  • func (d *Duration) String() string
  • func (d *Duration) Sub(n time.Duration) time.Duration
  • func (x *Duration) Swap(o time.Duration) time.Duration
  • func (x *Duration) UnmarshalJSON(b []byte) error
• type Error
  • func NewError(v error) *Error
  • func (x *Error) Load() error
  • func (x *Error) Store(v error)
• type Float64
  • func NewFloat64(v float64) *Float64
  • func (f *Float64) Add(s float64) float64
  • func (x *Float64) CAS(o, n float64) bool
  • func (x *Float64) Load() float64
  • func (x *Float64) MarshalJSON() ([]byte, error)
  • func (x *Float64) Store(v float64)
  • func (f *Float64) String() string
  • func (f *Float64) Sub(s float64) float64
  • func (x *Float64) UnmarshalJSON(b []byte) error
• type Int32
  • func NewInt32(i int32) *Int32
  • func (i *Int32) Add(n int32) int32
  • func (i *Int32) CAS(old, new int32) bool
  • func (i *Int32) Dec() int32
  • func (i *Int32) Inc() int32
  • func (i *Int32) Load() int32
  • func (i *Int32) MarshalJSON() ([]byte, error)
  • func (i *Int32) Store(n int32)
  • func (i *Int32) String() string
  • func (i *Int32) Sub(n int32) int32
  • func (i *Int32) Swap(n int32) int32
  • func (i *Int32) UnmarshalJSON(b []byte) error
• type Int64
  • func NewInt64(i int64) *Int64
  • func (i *Int64) Add(n int64) int64
  • func (i *Int64) CAS(old, new int64) bool
  • func (i *Int64) Dec() int64
  • func (i *Int64) Inc() int64
  • func (i *Int64) Load() int64
  • func (i *Int64) MarshalJSON() ([]byte, error)
  • func (i *Int64) Store(n int64)
  • func (i *Int64) String() string
  • func (i *Int64) Sub(n int64) int64
  • func (i *Int64) Swap(n int64) int64
  • func (i *Int64) UnmarshalJSON(b []byte) error
• type String
  • func NewString(v string) *String
  • func (x *String) Load() string
  • func (s *String) MarshalText() ([]byte, error)
  • func (x *String) Store(v string)
  • func (s *String) String() string
  • func (s *String) UnmarshalText(b []byte) error
• type Uint32
  • func NewUint32(i uint32) *Uint32
  • func (i *Uint32) Add(n uint32) uint32
  • func (i *Uint32) CAS(old, new uint32) bool
  • func (i *Uint32) Dec() uint32
  • func (i *Uint32) Inc() uint32
  • func (i *Uint32) Load() uint32
  • func (i *Uint32) MarshalJSON() ([]byte, error)
  • func (i *Uint32) Store(n uint32)
  • func (i *Uint32) String() string
  • func (i *Uint32) Sub(n uint32) uint32
  • func (i *Uint32) Swap(n uint32) uint32
  • func (i *Uint32) UnmarshalJSON(b []byte) error
• type Uint64
  • func NewUint64(i uint64) *Uint64
  • func (i *Uint64) Add(n uint64) uint64
  • func (i *Uint64) CAS(old, new uint64) bool
  • func (i *Uint64) Dec() uint64
  • func (i *Uint64) Inc() uint64
  • func (i *Uint64) Load() uint64
  • func (i *Uint64) MarshalJSON() ([]byte, error)
  • func (i *Uint64) Store(n uint64)
  • func (i *Uint64) String() string
  • func (i *Uint64) Sub(n uint64) uint64
  • func (i *Uint64) Swap(n uint64) uint64
  • func (i *Uint64) UnmarshalJSON(b []byte) error
• type Value

Examples

• Package

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bool

type Bool struct {
	// contains filtered or unexported fields
}

Bool is an atomic type-safe wrapper for bool values.

func NewBool

func NewBool(v bool) *Bool

NewBool creates a new Bool.

func (*Bool) CAS

func (x *Bool) CAS(o, n bool) bool

CAS is an atomic compare-and-swap for bool values.

func (*Bool) Load

func (x *Bool) Load() bool

Load atomically loads the wrapped bool.

func (*Bool) MarshalJSON

func (x *Bool) MarshalJSON() ([]byte, error)

MarshalJSON encodes the wrapped bool into JSON.

func (*Bool) Store

func (x *Bool) Store(v bool)

Store atomically stores the passed bool.

func (*Bool) String

func (b *Bool) String() string

String encodes the wrapped value as a string.

func (*Bool) Swap

func (x *Bool) Swap(o bool) bool

Swap atomically stores the given bool and returns the old value.

func (*Bool) Toggle

func (b *Bool) Toggle() bool

Toggle atomically negates the Boolean and returns the previous value.

func (*Bool) UnmarshalJSON

func (x *Bool) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes a bool from JSON.

type Duration

type Duration struct {
	// contains filtered or unexported fields
}

Duration is an atomic type-safe wrapper for time.Duration values.

func NewDuration

func NewDuration(v time.Duration) *Duration

NewDuration creates a new Duration.

func (*Duration) Add

func (d *Duration) Add(n time.Duration) time.Duration

Add atomically adds to the wrapped time.Duration and returns the new value.

func (*Duration) CAS

func (x *Duration) CAS(o, n time.Duration) bool

CAS is an atomic compare-and-swap for time.Duration values.

func (*Duration) Load

func (x *Duration) Load() time.Duration

Load atomically loads the wrapped time.Duration.

func (*Duration) MarshalJSON

func (x *Duration) MarshalJSON() ([]byte, error)

MarshalJSON encodes the wrapped time.Duration into JSON.

func (*Duration) Store

func (x *Duration) Store(v time.Duration)

Store atomically stores the passed time.Duration.

func (*Duration) String

func (d *Duration) String() string

String encodes the wrapped value as a string.

func (*Duration) Sub

func (d *Duration) Sub(n time.Duration) time.Duration

Sub atomically subtracts from the wrapped time.Duration and returns the new value.

func (*Duration) Swap

func (x *Duration) Swap(o time.Duration) time.Duration

Swap atomically stores the given time.Duration and returns the old value.

func (*Duration) UnmarshalJSON

func (x *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes a time.Duration from JSON.

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is an atomic type-safe wrapper for error values.

func NewError

func NewError(v error) *Error

NewError creates a new Error.

func (*Error) Load

func (x *Error) Load() error

Load atomically loads the wrapped error.

func (*Error) Store

func (x *Error) Store(v error)

Store atomically stores the passed error.

type Float64

type Float64 struct {
	// contains filtered or unexported fields
}

Float64 is an atomic type-safe wrapper for float64 values.

func NewFloat64

func NewFloat64(v float64) *Float64

NewFloat64 creates a new Float64.

func (*Float64) Add

func (f *Float64) Add(s float64) float64

Add atomically adds to the wrapped float64 and returns the new value.

func (*Float64) CAS

func (x *Float64) CAS(o, n float64) bool

CAS is an atomic compare-and-swap for float64 values.

func (*Float64) Load

func (x *Float64) Load() float64

Load atomically loads the wrapped float64.

func (*Float64) MarshalJSON

func (x *Float64) MarshalJSON() ([]byte, error)

MarshalJSON encodes the wrapped float64 into JSON.

func (*Float64) Store

func (x *Float64) Store(v float64)

Store atomically stores the passed float64.

func (*Float64) String

func (f *Float64) String() string

String encodes the wrapped value as a string.

func (*Float64) Sub

func (f *Float64) Sub(s float64) float64

Sub atomically subtracts from the wrapped float64 and returns the new value.

func (*Float64) UnmarshalJSON

func (x *Float64) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes a float64 from JSON.

type Int32

type Int32 struct {
	// contains filtered or unexported fields
}

Int32 is an atomic wrapper around int32.

func NewInt32

func NewInt32(i int32) *Int32

NewInt32 creates a new Int32.

func (*Int32) Add

func (i *Int32) Add(n int32) int32

Add atomically adds to the wrapped int32 and returns the new value.

func (*Int32) CAS

func (i *Int32) CAS(old, new int32) bool

CAS is an atomic compare-and-swap.

func (*Int32) Dec

func (i *Int32) Dec() int32

Dec atomically decrements the wrapped int32 and returns the new value.

func (*Int32) Inc

func (i *Int32) Inc() int32

Inc atomically increments the wrapped int32 and returns the new value.

func (*Int32) Load

func (i *Int32) Load() int32

Load atomically loads the wrapped value.

func (*Int32) MarshalJSON

func (i *Int32) MarshalJSON() ([]byte, error)

MarshalJSON encodes the wrapped int32 into JSON.

func (*Int32) Store

func (i *Int32) Store(n int32)

Store atomically stores the passed value.

func (*Int32) String

func (i *Int32) String() string

String encodes the wrapped value as a string.

func (*Int32) Sub

func (i *Int32) Sub(n int32) int32

Sub atomically subtracts from the wrapped int32 and returns the new value.

func (*Int32) Swap

func (i *Int32) Swap(n int32) int32

Swap atomically swaps the wrapped int32 and returns the old value.

func (*Int32) UnmarshalJSON

func (i *Int32) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes JSON into the wrapped int32.

type Int64

type Int64 struct {
	// contains filtered or unexported fields
}

Int64 is an atomic wrapper around int64.

func NewInt64

func NewInt64(i int64) *Int64

NewInt64 creates a new Int64.

func (*Int64) Add

func (i *Int64) Add(n int64) int64

Add atomically adds to the wrapped int64 and returns the new value.

func (*Int64) CAS

func (i *Int64) CAS(old, new int64) bool

CAS is an atomic compare-and-swap.

func (*Int64) Dec

func (i *Int64) Dec() int64

Dec atomically decrements the wrapped int64 and returns the new value.

func (*Int64) Inc

func (i *Int64) Inc() int64

Inc atomically increments the wrapped int64 and returns the new value.

func (*Int64) Load

func (i *Int64) Load() int64

Load atomically loads the wrapped value.

func (*Int64) MarshalJSON

func (i *Int64) MarshalJSON() ([]byte, error)

MarshalJSON encodes the wrapped int64 into JSON.

func (*Int64) Store

func (i *Int64) Store(n int64)

Store atomically stores the passed value.

func (*Int64) String

func (i *Int64) String() string

String encodes the wrapped value as a string.

func (*Int64) Sub

func (i *Int64) Sub(n int64) int64

Sub atomically subtracts from the wrapped int64 and returns the new value.

func (*Int64) Swap

func (i *Int64) Swap(n int64) int64

Swap atomically swaps the wrapped int64 and returns the old value.

func (*Int64) UnmarshalJSON

func (i *Int64) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes JSON into the wrapped int64.

type String

type String struct {
	// contains filtered or unexported fields
}

String is an atomic type-safe wrapper for string values.

func NewString

func NewString(v string) *String

NewString creates a new String.

func (*String) Load

func (x *String) Load() string

Load atomically loads the wrapped string.

func (*String) MarshalText

func (s *String) MarshalText() ([]byte, error)

MarshalText encodes the wrapped string into a textual form.

This makes it encodable as JSON, YAML, XML, and more.

func (*String) Store

func (x *String) Store(v string)

Store atomically stores the passed string.

func (*String) String

func (s *String) String() string

String returns the wrapped value.

func (*String) UnmarshalText

func (s *String) UnmarshalText(b []byte) error

UnmarshalText decodes text and replaces the wrapped string with it.

This makes it decodable from JSON, YAML, XML, and more.

type Uint32

type Uint32 struct {
	// contains filtered or unexported fields
}

Uint32 is an atomic wrapper around uint32.

func NewUint32

func NewUint32(i uint32) *Uint32

NewUint32 creates a new Uint32.

func (*Uint32) Add

func (i *Uint32) Add(n uint32) uint32

Add atomically adds to the wrapped uint32 and returns the new value.

func (*Uint32) CAS

func (i *Uint32) CAS(old, new uint32) bool

CAS is an atomic compare-and-swap.

func (*Uint32) Dec

func (i *Uint32) Dec() uint32

Dec atomically decrements the wrapped uint32 and returns the new value.

func (*Uint32) Inc

func (i *Uint32) Inc() uint32

Inc atomically increments the wrapped uint32 and returns the new value.

func (*Uint32) Load

func (i *Uint32) Load() uint32

Load atomically loads the wrapped value.

func (*Uint32) MarshalJSON

func (i *Uint32) MarshalJSON() ([]byte, error)

MarshalJSON encodes the wrapped uint32 into JSON.

func (*Uint32) Store

func (i *Uint32) Store(n uint32)

Store atomically stores the passed value.

func (*Uint32) String

func (i *Uint32) String() string

String encodes the wrapped value as a string.

func (*Uint32) Sub

func (i *Uint32) Sub(n uint32) uint32

Sub atomically subtracts from the wrapped uint32 and returns the new value.

func (*Uint32) Swap

func (i *Uint32) Swap(n uint32) uint32

Swap atomically swaps the wrapped uint32 and returns the old value.

func (*Uint32) UnmarshalJSON

func (i *Uint32) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes JSON into the wrapped uint32.

type Uint64

type Uint64 struct {
	// contains filtered or unexported fields
}

Uint64 is an atomic wrapper around uint64.

func NewUint64

func NewUint64(i uint64) *Uint64

NewUint64 creates a new Uint64.

func (*Uint64) Add

func (i *Uint64) Add(n uint64) uint64

Add atomically adds to the wrapped uint64 and returns the new value.

func (*Uint64) CAS

func (i *Uint64) CAS(old, new uint64) bool

CAS is an atomic compare-and-swap.

func (*Uint64) Dec

func (i *Uint64) Dec() uint64

Dec atomically decrements the wrapped uint64 and returns the new value.

func (*Uint64) Inc

func (i *Uint64) Inc() uint64

Inc atomically increments the wrapped uint64 and returns the new value.

func (*Uint64) Load

func (i *Uint64) Load() uint64

Load atomically loads the wrapped value.

func (*Uint64) MarshalJSON

func (i *Uint64) MarshalJSON() ([]byte, error)

MarshalJSON encodes the wrapped uint64 into JSON.

func (*Uint64) Store

func (i *Uint64) Store(n uint64)

Store atomically stores the passed value.

func (*Uint64) String

func (i *Uint64) String() string

String encodes the wrapped value as a string.

func (*Uint64) Sub

func (i *Uint64) Sub(n uint64) uint64

Sub atomically subtracts from the wrapped uint64 and returns the new value.

func (*Uint64) Swap

func (i *Uint64) Swap(n uint64) uint64

Swap atomically swaps the wrapped uint64 and returns the old value.

func (*Uint64) UnmarshalJSON

func (i *Uint64) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes JSON into the wrapped uint64.

type Value

type Value struct {
	atomic.Value
	// contains filtered or unexported fields
}

Value shadows the type of the same name from sync/atomic https://godoc.org/sync/atomic#Value