README
¶
Atoms 
Atoms is a QoL helper library which provides atomic primitives. The goal of this library is to reduce the amount of mundane boilplate code associated with managing atomic-friendly values
Provided primitives
- int
- uint
- int32
- int64
- uint32
- uint64
- boolean
- string
Non-primitive helpers
- generic value (interface{})
- mutex wrapper
- rwmutex wrapper
Features
Numeric values
- Load
- Store
- Swap
- Add
- CompareAndSwap
- JSON Marshal/Unmarshal
Boolean
- Get
- Set (Compare and swap functionality)
- JSON Marshal/Unmarshal
String
- Load
- Store
- Swap
- JSON
Generic
- Load
- Store
- Swap
- CompareAndSwap
- JSON Marshal/Unmarshal
Usage
Int64
package main
import (
"fmt"
"github.com/PathDNA/atoms"
)
func main() {
var i atoms.Int64
// Set value to 7
i.Store(7)
current := i.Load()
fmt.Printf("Current value: %d\n", current)
// Swap value with 13, returned value will be our old value
old := i.Swap(13)
fmt.Printf("Old value: %d\n", old)
// Increment value by 6, returned value will be our new value
new := i.Add(6)
fmt.Printf("New value: %d\n", new)
// Compare and swap value, will fail because value is 19 (not 20)
changed := i.CompareAndSwap(20, 40)
fmt.Printf("Changed: %v\n", changed)
}
Bool
package main
import (
"fmt"
"github.com/PathDNA/atoms"
)
func main() {
var b atoms.Bool
// Get current state
state := b.Get()
fmt.Printf("State: %v\n", state)
// Set value, will fail because value has not changed
changed := b.Set(false)
fmt.Printf("Changed: %v\n", changed)
// Set value to true
changed = b.Set(true)
fmt.Printf("Changed: %v\n", changed)
// Get current state
state = b.Get()
fmt.Printf("State: %v\n", state)
}
String
package main
import (
"fmt"
"github.com/PathDNA/atoms"
)
func main() {
var s atoms.String
// Set value to "Hello world"
s.Store("Hello world")
current := s.Load()
fmt.Printf("Current value: %s\n", current)
// Swap value with "Goodbye world", returned value will be our old value
old := s.Swap("Goodbye world")
fmt.Printf("Old value: %s\n", old)
current := s.Load()
fmt.Printf("New current value: %s\n", current)
}
Value
package main
import (
"encoding/json"
"fmt"
"log"
"github.com/PathDNA/atoms"
)
func main() {
type dummy struct {
V int `json:"v"`
}
var v atoms.Value
// set the internal type
v.Store(dummy{})
b := []byte(`{ "v" : 45066 }`)
if err := json.Unmarshal(b, &v); err != nil {
log.Fatal(err)
}
v.CompareAndSwap(func(oldV interface{}) (newV interface{}, ok bool) {
v, _ := oldV.(dummy)
v.V++
return v, true
})
dv, _ := v.Load().(dummy)
fmt.Printf("%#+v\n", dv)
fmt.Printf("0x%Xs\n", dv.V)
}
Mux/RWMux
package main
import (
"fmt"
"sync"
"github.com/PathDNA/atoms"
)
func main() {
var wg sync.WaitGroup
c := NewCounter()
wg.Add(3)
go func() {
c.Increment("foo")
wg.Done()
}()
go func() {
c.Increment("foo")
wg.Done()
}()
go func() {
c.Increment("foo")
wg.Done()
}()
// Wait for all goroutines to finish
wg.Wait()
// Output will be 3
fmt.Println(c.Get("foo"))
}
// NewCounter will return a new counter
func NewCounter() *Counter {
var c Counter
// Initialize our internal map
c.cm = make(map[string]uint64)
return &c
}
// Counter manages a counter
type Counter struct {
mux atoms.RWMux
cm map[string]uint64
}
// Increment will increment a given key
func (c *Counter) Increment(key string) {
c.mux.Update(func() {
c.cm[key]++
})
}
// Get will get the counter value for a given key
func (c *Counter) Get(key string) (n uint64) {
c.mux.Read(func() {
n = c.cm[key]
})
return
}
Note - Check out the examples directory for compilable examples
Documentation
¶
Index ¶
- Constants
- type Bool
- type Int
- type Int32
- func (i *Int32) Add(n int32) (new int32)
- func (i *Int32) CompareAndSwap(old, new int32) (changed bool)
- func (i *Int32) Load() (n int32)
- func (i *Int32) MarshalJSON() (b []byte, err error)
- func (i *Int32) Store(new int32)
- func (i *Int32) Swap(new int32) (old int32)
- func (i *Int32) UnmarshalJSON(b []byte) (err error)
- type Int64
- func (i *Int64) Add(n int64) (new int64)
- func (i *Int64) CompareAndSwap(old, new int64) (changed bool)
- func (i *Int64) Load() (n int64)
- func (i *Int64) MarshalJSON() (b []byte, err error)
- func (i *Int64) Store(new int64)
- func (i *Int64) Swap(new int64) (old int64)
- func (i *Int64) UnmarshalJSON(b []byte) (err error)
- type MultiMux
- type Mux
- type RWMux
- type String
- type Uint
- func (u *Uint) Add(n uint) (new uint)
- func (u *Uint) CompareAndSwap(old, new uint) (changed bool)
- func (u *Uint) Load() (n uint)
- func (u *Uint) MarshalJSON() (b []byte, err error)
- func (u *Uint) Store(new uint)
- func (u *Uint) Swap(new uint) (old uint)
- func (u *Uint) UnmarshalJSON(b []byte) (err error)
- type Uint32
- func (u *Uint32) Add(n uint32) (new uint32)
- func (u *Uint32) CompareAndSwap(old, new uint32) (changed bool)
- func (u *Uint32) Load() (n uint32)
- func (u *Uint32) MarshalJSON() (b []byte, err error)
- func (u *Uint32) Store(new uint32)
- func (u *Uint32) Swap(new uint32) (old uint32)
- func (u *Uint32) UnmarshalJSON(b []byte) (err error)
- type Uint64
- func (u *Uint64) Add(n uint64) (new uint64)
- func (u *Uint64) CompareAndSwap(old, new uint64) (changed bool)
- func (u *Uint64) Load() (n uint64)
- func (u *Uint64) MarshalJSON() (b []byte, err error)
- func (u *Uint64) Store(new uint64)
- func (u *Uint64) Swap(new uint64) (old uint64)
- func (u *Uint64) UnmarshalJSON(b []byte) (err error)
- type Value
- func (av *Value) CompareAndSwap(fn func(oldV interface{}) (newV interface{}, ok bool)) (ok bool)
- func (av *Value) Load() (v interface{})
- func (av *Value) MarshalJSON() (b []byte, err error)
- func (av *Value) Store(v interface{})
- func (av *Value) Swap(newV interface{}) (oldV interface{})
- func (av *Value) UnmarshalJSON(b []byte) (err error)
Constants ¶
const ( // False state False int32 = iota // True state True )
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 bool type
func (*Bool) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Bool) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type Int ¶
type Int struct {
// contains filtered or unexported fields
}
Int is an atomic int
func (*Int) CompareAndSwap ¶
CompareAndSwap will perform an atomic compare and swap for an old and new value
func (*Int) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Int) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type Int32 ¶
type Int32 struct {
// contains filtered or unexported fields
}
Int32 is an atomic int32
func (*Int32) CompareAndSwap ¶
CompareAndSwap will perform an atomic compare and swap for an old and new value
func (*Int32) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Int32) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type Int64 ¶
type Int64 struct {
// contains filtered or unexported fields
}
Int64 is an atomic int64
func (*Int64) CompareAndSwap ¶
CompareAndSwap will perform an atomic compare and swap for an old and new value
func (*Int64) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Int64) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type MultiMux ¶
type MultiMux struct {
// contains filtered or unexported fields
}
MultiMux allows to hold locks by a key.
func (*MultiMux) Delete ¶
Delete deletes the specific key, ensuring that it isn't used anywhere else.
type Mux ¶
type Mux struct {
// contains filtered or unexported fields
}
Mux wraps a sync.Mutex to allow simple and safe operation on the mutex.
type RWMux ¶
type RWMux struct {
// contains filtered or unexported fields
}
RWMux wraps a sync.RWMutex to allow simple and safe operation on the mutex.
type String ¶
type String struct {
// contains filtered or unexported fields
}
String is a string type
func (*String) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*String) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type Uint ¶
type Uint struct {
// contains filtered or unexported fields
}
Uint is an atomic uint
func (*Uint) CompareAndSwap ¶
CompareAndSwap will perform an atomic compare and swap for an old and new value
func (*Uint) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Uint) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type Uint32 ¶
type Uint32 struct {
// contains filtered or unexported fields
}
Uint32 is an atomic uint32
func (*Uint32) CompareAndSwap ¶
CompareAndSwap will perform an atomic compare and swap for an old and new value
func (*Uint32) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Uint32) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type Uint64 ¶
type Uint64 struct {
// contains filtered or unexported fields
}
Uint64 is an atomic uint64
func (*Uint64) CompareAndSwap ¶
CompareAndSwap will perform an atomic compare and swap for an old and new value
func (*Uint64) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Uint64) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is an atomic interface{}
func (*Value) CompareAndSwap ¶
CompareAndSwap will perform an atomic compare and swap for an old and new value, fn is expected to check the old value and return the new value and true, or return false
func (*Value) MarshalJSON ¶
MarshalJSON is a json encoding helper function
func (*Value) Store ¶
func (av *Value) Store(v interface{})
Store will perform an atomic store for a new value
func (*Value) Swap ¶
func (av *Value) Swap(newV interface{}) (oldV interface{})
Swap will perform an atomic swap for a new value and return the old value
func (*Value) UnmarshalJSON ¶
UnmarshalJSON is a json decoding helper function, to specify the type of the value make sure to call .Set with the zero type you want. Example:
v.Set(&Struct{})
err := json.Unmarshal(data, &v)
Source Files
Directories