github.com/go-ng/xatomic@v0.0.0-20230519181013-85c0ec87e55f/README.md (about)

     1  # `xatomic`
     2  
     3  [![GoDoc](https://godoc.org/github.com/go-ng/xatomic?status.svg)](https://pkg.go.dev/github.com/go-ng/xatomic?tab=doc)
     4  
     5  ## About
     6  
     7  This package just provides with additional primitives to available in [`sync/atomic`](https://pkg.go.dev/sync/atomic).
     8  
     9  Right now it provides with only 4 functions:
    10  
    11  * [`LoadMap`](https://pkg.go.dev/github.com/go-ng/xatomic#LoadMap), which works similar to [`atomic.LoadUint64`](https://pkg.go.dev/sync/atomic#LoadUint64), but for a `map`, instead of `uint64`.
    12  * [`StoreMap`](https://pkg.go.dev/github.com/go-ng/xatomic#StoreMap), which works similar to [`atomic.StoreUint64`](https://pkg.go.dev/sync/atomic#StoreUint64), but for a `map`, instead of `uint64`.
    13  * [`LoadPointer`](https://pkg.go.dev/github.com/go-ng/xatomic#LoadPointer), which works similar to [`atomic.LoadPointer`](https://pkg.go.dev/sync/atomic#LoadPointer), but avoids necessity to manually work with the `unsafe` package.
    14  * [`StorePointer`](https://pkg.go.dev/github.com/go-ng/xatomic#StorePointer), which works similar to [`atomic.StorePointer`](https://pkg.go.dev/sync/atomic#StorePointer), but avoids necessity to manually work with the `unsafe` package.
    15  
    16  ## Examples
    17  
    18  ### `Pointer`
    19  
    20  ```go
    21  import "github.com/go-ng/xatomic"
    22  
    23      ...
    24      var m *myStruct
    25      ...
    26      go func(){
    27          ...
    28          xatomic.StorePointer(&m, &myStruct{Err: myErr})
    29          ...
    30      }()
    31      go func(){
    32          ...
    33          fmt.Println(xatomic.LoadPointer(&m).Err.Error())
    34          ...
    35      }()
    36  ```
    37  
    38  ### `Slice`
    39  
    40  ```go
    41  import "github.com/go-ng/xatomic"
    42  
    43  
    44      ...
    45      var m map[string]any{}
    46      ...
    47      go func(){
    48          ...
    49          xatomic.StoreMap(m, myMap)
    50          ...
    51      }()
    52      go func(){
    53          ...
    54          myMap := xatomic.LoadMap(m)
    55          ...
    56      }()
    57  ```
    58  
    59  It uses Go generics, so the type of the map is preserved after `StoreMap` & `LoadMap`.
    60  
    61  ## Performance
    62  
    63  ```plain
    64  goos: linux
    65  goarch: amd64
    66  pkg: github.com/go-ng/xatomic
    67  cpu: 11th Gen Intel(R) Core(TM) i7-11800H @ 2.30GHz
    68  Benchmark/noop-16                     	1000000000	         0.2236 ns/op
    69  Benchmark/Map/Store/atomic-16         	987858870	         6.108 ns/op
    70  Benchmark/Map/Store/unatomic-16       	1000000000	         0.3973 ns/op
    71  Benchmark/Map/Load/atomic-16          	1000000000	         0.4589 ns/op
    72  Benchmark/Map/Load/unatomic-16        	1000000000	         0.4611 ns/op
    73  PASS
    74  ok  	github.com/go-ng/xatomic	8.364s
    75  ```