mleku
e56bf76257
- Introduced a new `sync` package for managing NIP-11 relay information and relay group configurations. - Implemented a cache for NIP-11 documents, allowing retrieval of relay public keys and authoritative configurations. - Enhanced the sync manager to update peer lists based on authoritative configurations from relay group events. - Updated event handling to incorporate policy checks during event imports, ensuring compliance with relay rules. - Refactored various components to utilize the new `sha256-simd` package for improved performance. - Added comprehensive tests to validate the new synchronization and group management functionalities. - Bumped version to v0.24.1 to reflect these changes.
175 lines
3.8 KiB
Markdown
175 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
// 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
|
|
|
|
```go
|
|
// 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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.
|