next.orly.dev/pkg/utils/atomic/README.md

atomic

Type-safe atomic operations for Go primitive types. This package provides convenient wrappers around Go's sync/atomic package to ensure safe concurrent access to shared variables.

Features

• Type Safety: Strongly typed wrappers prevent accidental misuse
• Memory Safety: Prevents race conditions in concurrent programs
• Performance: Zero-overhead wrappers around standard library atomics
• Comprehensive Coverage: Supports all common primitive types
• Thread Safe: All operations are atomic and safe for concurrent access

Installation

go get next.orly.dev/pkg/utils/atomic

Usage

The atomic package provides type-safe wrappers around Go's standard sync/atomic operations:

Basic Operations

import "next.orly.dev/pkg/utils/atomic"

// Integer types
var counter atomic.Uint64
counter.Store(42)
value := counter.Load()  // 42
counter.Add(8)          // 50

// Boolean operations
var flag atomic.Bool
flag.Store(true)
if flag.Load() {
    // Handle true case
}

// Pointer operations
var ptr atomic.Pointer[string]
ptr.Store(&someString)
loadedPtr := ptr.Load()

Advanced Operations

// Compare and swap
var value atomic.Int64
value.Store(100)
swapped := value.CompareAndSwap(100, 200)  // true, value is now 200

// Swap operations
oldValue := value.Swap(300)  // oldValue = 200, new value = 300

// Atomic add/subtract
delta := value.Add(50)  // Add 50, return new value (350)
value.Sub(25)           // Subtract 25, value is now 325

Supported Types

Type	Description
Bool	Atomic boolean operations
Int32	32-bit signed integer
Int64	64-bit signed integer
Uint32	32-bit unsigned integer
Uint64	64-bit unsigned integer
Uintptr	Pointer-sized unsigned integer
Float64	64-bit floating point
Pointer[T]	Generic pointer type

Generic Pointer Example

// Type-safe pointer operations
var config atomic.Pointer[Config]
config.Store(&myConfig)

// Load with type safety
currentConfig := config.Load()
if currentConfig != nil {
    // Use config with full type safety
}

API Reference

All atomic types implement a consistent interface:

• Load() T - Atomically load the current value
• Store(val T) - Atomically store a new value
• Swap(new T) T - Atomically swap values, return old value
• CompareAndSwap(old, new T) bool - CAS operation

Additional methods by type:

Integer Types (Int32, Int64, Uint32, Uint64):

• Add(delta T) T - Atomically add delta, return new value
• Sub(delta T) T - Atomically subtract delta, return new value

Float64:

• Add(delta float64) float64 - Atomically add delta

Testing

The atomic package includes comprehensive tests:

Running Tests

# Run atomic package tests
go test ./pkg/utils/atomic

# Run with verbose output
go test -v ./pkg/utils/atomic

# Run with race detection
go test -race ./pkg/utils/atomic

# Run with coverage
go test -cover ./pkg/utils/atomic

Integration Testing

Part of the full test suite:

# Run all tests including atomic
./scripts/test.sh

# Run specific package tests
go test ./pkg/utils/...

Test Coverage

Tests cover:

• All atomic operations
• Concurrent access patterns
• Race condition prevention
• Type safety
• Memory ordering guarantees

Performance

The atomic wrappers have zero runtime overhead compared to direct sync/atomic calls. The Go compiler inlines all wrapper methods, resulting in identical generated code.

Development

Building

go build ./pkg/utils/atomic

Code Quality

• Full test coverage with race detection
• Go best practices compliance
• Comprehensive documentation
• Thread-safe by design

Examples

See the test files for comprehensive usage examples and edge cases.

License

Part of the next.orly.dev project. See main LICENSE file.