Skip to content

Add allocator selection guide #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
antono3 merged 1 commit into from
Sep 10, 2026
Merged

Add allocator selection guide #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ All notable changes to this project will be documented in this file.
comparisons, with success, failure, peak-use, and trace-integrity diagnostics.
- Run the allocator test suite and canonical `antono2.mem` public-import
examples on Linux, macOS, and Windows in CI.
- Add a task-oriented allocator selection guide covering lifetime, release
order, and fragmentation tradeoffs.

## 1.0.3 - 2026-09-10

Expand Down
17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,23 @@ the distribution repository and installed directory.
Projects that still import `generic_pool` should pin the 0.2.0 release until
they are ready to update their imports.

## Choosing an allocator

| Type | Use it when | Release order | Main tradeoff |
| --- | --- | --- | --- |
| `SlotPool[T]` | You need a fixed number of typed values with stable, checked handles | Any order | Capacity is fixed at construction |
| `ObjectPool[T]` | Creating a typed resource is expensive and released values can be reset and reused | Any order | A reset callback must restore reusable state |
| `RangeAllocator` | Requests have arbitrary sizes or non-power-of-two alignments | Any order | First-fit allocation and release scan free ranges |
| `LinearAllocator` | A whole batch shares one lifetime, such as frame or request scratch data | All at once with `reset()` | Individual ranges cannot be released |
| `RingAllocator` | Allocations are retired in the same order they are created | FIFO | Out-of-order release is rejected |
| `BuddyAllocator` | Power-of-two splitting and recursive coalescing suit the arena | Any order | Requests consume rounded-up blocks and tree metadata |

The allocators manage values or numeric ranges; they do not allocate, map, or
free an operating-system or GPU resource. Create the backing resource once,
use returned offsets or handles to address it, and destroy the backing resource
only after its allocations are no longer live. None of the types is internally
synchronized.

## Slot pool

Create a pool once, insert values until it reaches its fixed capacity, and use
Expand Down