README

atomic GoDoc Build Status Coverage Status Go Report Card

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.

Expand ▾ Collapse ▴

Documentation

Overview

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

    Example
    Output:
    
    43
    true
    0
    

    Index

    Examples

    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

                                                                                                                                                                                                  Directories

                                                                                                                                                                                                  Path Synopsis
                                                                                                                                                                                                  internal
                                                                                                                                                                                                  gen-atomicint
                                                                                                                                                                                                  gen-atomicint generates an atomic wrapper around an integer type.
                                                                                                                                                                                                  gen-atomicint generates an atomic wrapper around an integer type.
                                                                                                                                                                                                  gen-atomicwrapper
                                                                                                                                                                                                  gen-atomicwrapper generates wrapper types around other atomic types.
                                                                                                                                                                                                  gen-atomicwrapper generates wrapper types around other atomic types.