Atomic Queue

A high-performance, thread-safe queue and dispatcher library for Go. Designed for concurrent task processing, resource management, and flexible dispatch patterns.

Features

• Generic, thread-safe FIFO queue (AtomicQueue)
• Pluggable dispatcher (AtomicDispatcher) for sequential or concurrent processing
• Resource context injection for tasks
• Graceful shutdown and cancellation support
• Benchmark and test suite for reliability

Usage

Installation

Add to your Go project:

go get github.com/justdaile/atomic_queue

Basic Example

package main

import (
    "github.com/justdaile/atomic_queue"
    "fmt"
    "time"
)

type MyTask struct {
    ID int
}

func (t MyTask) Dispatch(ctx atomicq.ResourceContext[any]) chan any {
    out := make(chan any, 1)
    go func() {
        time.Sleep(100 * time.Millisecond)
        out <- fmt.Sprintf("Task %d done", t.ID)
        close(out)
    }()
    return out
}

func main() {
    dispatcher := NewAtomicDispatcher[any, any](nil, 4) // 4 concurrent
    for i := 0; i < 10; i++ {
        dispatcher.Enqueue(MyTask{ID: i})
    }
    results := make(chan any, 10)
    dispatcher.Listen(results)
    for result := range results {
        fmt.Println(result)
    }
    dispatcher.ForceStop()
}

API Overview

Queue Interface

• Enqueue(item T)
• Dequeue() (T, bool)
• Peek() (T, bool)
• Len() int
• IsEmpty() bool
• Clear()
• ToSlice() []T

Dispatcher

• NewAtomicDispatcher(queue, resource, maxConcurrent)
• Listen(outChan)
• Stop() (graceful)
• ForceStop() (immediate)
• GetInflight()

Advanced Usage

• Inject custom resources via ResourceContext
• Use maxConcurrent=0 for sequential, predictable dispatch
• Use maxConcurrent>0 for parallel, high-throughput dispatch
• Implement custom Dispatchable types for flexible task logic

Benchmarks & Testing

Run all tests and benchmarks:

go test -v -bench=. .

Project Structure

atomic_queue/
├── go.mod
├── queue.go
├── dispatcher.go
├── queue_test.go
└── dispatcher_test.go
└── examples/
    └── animals/
        ├── main.go
        └── random_animal.go

License

MIT

Author

justdaile