Introduction

Overview of Go Container’s type-safe data structure implementations.

Go Container is a Go module that provides minimal, high-performance implementations of common data structures using Go generics. Every type is fully type-safe at compile time — no interface casts, no any values leaking into your code.

What you get

The module ships five data structures, each available in multiple backing-storage variants so you can tune for your specific workload:

Type	Slice	Map	List	List + sync.Pool	List + internal pool	Recommended
OrderedMap	✓					Slice with size hint
Queue	✓		✓	✓	✓	Slice with size hint
WaitableQueue	✓					Slice with size hint
Set		✓				Map with size hint
Stack	✓		✓	✓	✓	Slice with size hint

OrderedMap

OrderedMap[K, V] is a key-value map that preserves a deterministic iteration order. Unlike a plain Go map, ranging over an OrderedMap always produces keys in a consistent sequence. It supports two ordering modes:

• Stable (in-place): updates overwrite the value without changing the key’s position — ideal for the highest performance.
• Recency: updates move the key to the most-recently-used position — ideal for LRU caches.

Queue

Queue[E] is a classic first-in, first-out queue. Use it when you need ordered processing of elements within a single goroutine.

WaitableQueue

WaitableQueue[E] is a concurrency-safe, unbounded queue designed for producer-consumer patterns. Unlike a Go channel, it has no fixed capacity limit. Flow control is managed through configurable low and high watermarks that signal when a consumer should scale up or a producer should throttle.

Set

Set[E] is an idiomatic Go set that eliminates duplicates and supports standard set operations: Union, Intersection, and Difference.

Stack

Stack[E] is a last-in, first-out stack for single-goroutine use.

Concurrency safety

All implementations except WaitableQueue are not safe for concurrent use. You must protect them with a sync.Mutex or equivalent if you share them across goroutines.

WaitableQueue is explicitly designed for concurrent producer-consumer use and is the only type with built-in concurrency guarantees.

The Countable interface

Some implementations optionally satisfy the container.Countable interface, which exposes a Len() int method. Always use a type assertion to check before calling it:

if c, ok := q.(container.Countable); ok {
    fmt.Println("elements:", c.Len())
}

For concurrency-safe types, Len() is not atomic with respect to other operations. Use it for observability and debugging only, not to make control-flow decisions.

Requirements

Go Container uses generics and requires Go 1.18 or later. The module itself targets Go 1.24+, so you will get the best experience on a recent toolchain.

Next steps

Quick start

Install the module and run your first example in minutes.

Choosing an implementation

Decide which backing store fits your performance requirements.