Table of Contents

What is a Slot Map?

Key Features

Quick Start

#include"slot_map.h"// Create a slot map for stringsdod::slot_map<std::string> strings;// Insert values and get unique keysauto red_key = strings.emplace("Red");auto green_key = strings.emplace("Green");auto blue_key = strings.emplace("Blue");// Access values using keysconst std::string* red_value = strings.get(red_key);if (red_value) {printf("Color: %s\n", red_value->c_str());// Output: Color: Red}// Remove a valuestrings.erase(green_key);// Check if keys are still validprintf("Green exists: %d\n", strings.has_key(green_key));// Output: 0printf("Blue exists: %d\n", strings.has_key(blue_key));// Output: 1// Iterate over all valuesfor (constauto& color : strings) {printf("Color: %s\n", color.c_str());}// Iterate over key-value pairsfor (constauto& [key, color] : strings.items()) {printf("Key: %" PRIslotkey", Color: %s\n",uint64_t(key), color.get().c_str());}

Building

Requirements

Header-Only Integration

#include"slot_map/slot_map.h"

Building Tests

git clone https://github.com/SergeyMakeev/SlotMap.gitcd SlotMapmkdir build&&cd buildcmake ..cmake --build.# Run tests./SlotMapTest01./SlotMapTest02./SlotMapTest03./SlotMapTest04

Custom Memory Allocator

#defineSLOT_MAP_ALLOC(sizeInBytes, alignment) your_aligned_alloc(alignment, sizeInBytes)#defineSLOT_MAP_FREE(ptr) your_free(ptr)#include"slot_map.h"

API Reference

Core Operations

emplace(Args&&... args) -> key

auto key = slot_map.emplace("Hello","World");// Construct string from args

get(key k) -> T* /get(key k) const -> const T*

const std::string* value = slot_map.get(key);

has_key(key k) const -> bool

if (slot_map.has_key(key)) {/* key is valid*/ }

erase(key k)

slot_map.erase(key);

pop(key k) -> std::optional<T>

auto value = slot_map.pop(key);// Returns optional<T>

Container Operations

size() const -> size_type

empty() const -> bool

clear()

reset()

swap(slot_map& other)

Iteration

Value iteration

for (constauto& value : slot_map) {// Process value}

Key-value iteration

for (constauto& [key, value] : slot_map.items()) {// Process key and value}

Debug and Statistics

debug_stats() const -> Stats

auto stats = slot_map.debug_stats();printf("Active items: %u\n", stats.numAliveItems);

Key Types

64-bit Keys (Default)

dod::slot_map<T>// Uses 64-bit keysdod::slot_map64<T>// Explicit 64-bit keys

32-bit Keys

dod::slot_map32<T>// Uses 32-bit keys

Key Operations

auto key = slot_map.emplace(value);// Type-safe: this won't compile// slot_map<int>::key int_key = int_map.emplace(42);// string_map.get(int_key);  // Compiler error!// Convert to/from raw numeric typeuint64_t raw_key = key;// Implicit conversionslot_map<T>::key restored_key{raw_key};// Explicit construction

Advanced Features

Tags

auto key = slot_map.emplace("Value");key.set_tag(42);// Store application dataauto tag = key.get_tag();// Retrieve: tag == 42// Tag limits:// 64-bit keys: 0..4,095 (12 bits)// 32-bit keys: 0..3 (2 bits)

Custom Page Size

// Default page size is 4096 elementsdod::slot_map<T, dod::slot_map_key64<T>,8192> large_pages;dod::slot_map<T, dod::slot_map_key64<T>,1024> small_pages;

Custom Free Indices Threshold

// Default threshold is 64dod::slot_map<T, dod::slot_map_key64<T>,4096,128> conservative_reuse;

Performance

Time Complexity

Memory Characteristics

Implementation Details

Version Overflow Protection

Free Index Management

Page Management

Thread Safety

std::shared_mutex mutex;dod::slot_map<T> slot_map;// Reader{    std::shared_locklock(mutex);auto value = slot_map.get(key);}// Writer{    std::unique_locklock(mutex);auto key = slot_map.emplace(value);}

Examples

Entity Component System

structTransform {float x, y, z; };structHealth {int hp, max_hp; };dod::slot_map<Transform> transforms;dod::slot_map<Health> healths;// Create entityauto entity_id = generate_entity_id();auto transform_key = transforms.emplace(Transform{0,0,0});auto health_key = healths.emplace(Health{100,100});// Store keys in entityregister_component(entity_id, transform_key);register_component(entity_id, health_key);

Resource Management

dod::slot_map<Texture> textures;dod::slot_map<Sound> sounds;classResourceManager {using TextureHandle = dod::slot_map<Texture>::key;using SoundHandle = dod::slot_map<Sound>::key;        TextureHandleload_texture(const std::string& path) {return textures.emplace(load_texture_from_file(path));    }const Texture*get_texture(TextureHandle handle) {return textures.get(handle);    }};

Object Pool with Versioning

classBulletPool {structBullet {float x, y, dx, dy;bool active; };    dod::slot_map<Bullet> bullets;public:using BulletHandle = dod::slot_map<Bullet>::key;        BulletHandlespawn(float x,float y,float dx,float dy) {return bullets.emplace(Bullet{x, y, dx, dy,true});    }voidupdate() {for (auto& bullet : bullets) {if (bullet.active) {                bullet.x += bullet.dx;                bullet.y += bullet.dy;            }        }    }voiddestroy(BulletHandle handle) {        bullets.erase(handle);// Handle becomes invalid automatically    }};

References