A Go library containing reusable utilities and data structures.
Ain (formal name of Epsilon Tauri star) is a collection of common Go packages and utilities. This library provides battle-tested, production-ready implementations of commonly needed functionality.
This library was created to solve a common problem: fixing the same bugs and implementing the same features across multiple projects. Instead of copying code between repositories, this centralized library ensures that bug fixes and improvements benefit all projects simultaneously, reducing maintenance overhead and improving code quality across the board.
This library is licensed under the MIT License. Please see the LICENSE file for the full license text.
- High-Performance Data Structures: Lock-free ring buffer (Disruptor), thread-safe queues, worker pools
- Logging System: Flexible, multi-level logging with forwarding capabilities
- Error Handling: Structured error types with HTTP status codes
- Retry Mechanism: Exponential backoff with jitter for resilient operations
- Common Utilities: Reusable helper functions
go get github.com/abaxoth0/Ain- Go 1.23.0 or later
A high-performance, lock-free ring buffer implementation based on the LMAX Disruptor pattern.
disruptor := structs.NewDisruptor[string]()
go disruptor.Consume(func(msg string) {
fmt.Println("Received:", msg)
})
disruptor.Publish("Hello, World!")Thread-safe FIFO queue with optional size limits and blocking operations.
queue := structs.NewSyncQueue[string](0) // 0 = no size limit
queue.Push("item1")
queue.Push("item2")
item, ok := queue.Pop()Classic LIFO stack in several implementations.
stack := structs.NewStaticStack[string](10)
stack.Push("example 1")
stack.Push("example 2")
stack.Pop() // "example 2", true
stack.Pop() // "example 1", true
stack.Pop() // "", falseConcurrent task processing with configurable worker count and graceful shutdown.
type MyTask struct{ data string }
func (t *MyTask) Process() { /* process task */ }
pool := structs.NewWorkerPool(context.Background(), nil)
pool.Start(4) // 4 workers
pool.Push(&MyTask{data: "test"})Multi-level logging with support for forwarding, configuration, and different output targets.
Features:
- Multiple log levels (Trace, Debug, Info, Warn, Error, Fatal, Panic)
- Forwarding capabilities to chain loggers
- Configurable output formatting
- Concurrent logger support with background processing
Structured error types with HTTP status code integration.
err := errs.NewStatusError("Invalid request", http.StatusBadRequest)
// err.Error() returns "Invalid request"
// err.Status() returns 400Common helper functions for everyday Go programming.
Retry functionality to handle transient failures.
config := &common.RetryConfig{
MaxAttempts: 3,
MaxBackoff: time.Second * 5,
BackoffScale: time.Millisecond * 100,
}
err := common.Retry(func() error {
return makeAPICall() // Your operation here
}, config)// Ternary operator
result := common.Ternary(condition, "yes", "no")The Disruptor implementation provides high-throughput, low-latency messaging suitable for:
- Event processing systems
- Message queues
- Producer-consumer patterns
- High-frequency trading systems
Benchmark results and performance characteristics are documented in the BENCHMARKS.md.
Current Performance Summary (100 iterations, statistical analysis):
- Single Operations: Disruptor 69.3B ops/s (0.01±0.00ns), Channels 42.5M ops/s (23.55±0.21ns), SyncQueue 14.2M ops/s (70.43±11.0ns)
- Throughput: Channels 876K±42K items/sec (most stable), Disruptor 834K±145K (competitive, higher variance), SyncQueue 832K±81K (surprisingly competitive)
- Memory Efficiency: Disruptor & Channels: 0 allocations, SyncQueue: 218K±839 B/op (47 allocs)
- Best Use Cases: Channels for consistency, Disruptor for high-concurrency scenarios, SyncQueue when features outweigh performance
All benchmarks use automated script (scripts/bench.py) for 100-iteration statistical analysis.