> ## Documentation Index
> Fetch the complete documentation index at: https://osinet.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Warning>
  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.
</Warning>

## 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:

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

<Note>
  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.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Quick start" icon="rocket" href="/quickstart">
    Install the module and run your first example in minutes.
  </Card>

  <Card title="Choosing an implementation" icon="code-compare" href="/guides/choosing-implementation">
    Decide which backing store fits your performance requirements.
  </Card>
</CardGroup>