maph 1.0.0 High-Performance Memory-Mapped Key-Value Database with O(1) Lookups

Loading...
Searching...
No Matches
Classes | Namespaces | Typedefs | Enumerations | Functions | Variables
maph.hpp File Reference

maph - Memory-mapped Approximate Perfect Hash More...

`#include <sys/mman.h>`
`#include <sys/stat.h>`
`#include <fcntl.h>`
`#include <unistd.h>`
`#include <cstring>`
`#include <atomic>`
`#include <string_view>`
`#include <optional>`
`#include <memory>`
`#include <vector>`
`#include <thread>`
`#include <future>`
`#include <algorithm>`
`#include <execution>`
`#include <chrono>`
`#include <immintrin.h>`
Include dependency graph for maph.hpp:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Classes
struct | maph::Result
| Operation result containing error code and message. More...
struct | maph::Slot
| Storage slot for key-value pairs. More...
struct | maph::Header
| Database file header containing metadata. More...
struct | maph::Hash
| Hash function implementation for key distribution. More...
struct | maph::Hash::Result
| Hash computation result. More...
class | maph::Maph
| Main maph class - lean and fast. More...
struct | maph::Maph::Stats
| Database statistics. More...
class | maph::Maph::DurabilityManager

## Namespaces
namespace | maph

## Typedefs
using | maph::JsonView = std::string_view

## Enumerations
enum class | maph::ErrorCode { maph::SUCCESS = 0 , maph::FILE_OPEN_FAILED , maph::FILE_TRUNCATE_FAILED , maph::MMAP_FAILED , maph::INVALID_MAGIC , maph::VERSION_MISMATCH , maph::VALUE_TOO_LARGE , maph::TABLE_FULL , maph::KEY_NOT_FOUND , maph::READONLY_STORE }
| Error codes returned by maph operations. More...

## Functions
auto | maph::create (const std::string &path, uint64_t slots)
auto | maph::open (const std::string &path)
auto | maph::open_readonly (const std::string &path)

## Variables
static constexpr uint32_t | maph::MAGIC_NUMBER = 0x4D415048
static constexpr uint32_t | maph::CURRENT_VERSION = 1
static constexpr size_t | maph::SLOT_SIZE = 512
static constexpr size_t | maph::HEADER_SIZE = 512
static constexpr size_t | maph::SLOT_DATA_SIZE = 496
static constexpr size_t | maph::MAX_PROBE_DISTANCE = 10
static constexpr double | maph::DEFAULT_STATIC_RATIO = 0.8

## Detailed Description

maph - Memory-mapped Approximate Perfect Hash

Ultra-fast JSON key-value store using mmap and perfect hashing. Provides sub-microsecond lookups with O(1) complexity.

Design principles:

- Zero-copy via string_view
- Single hash computation (reused)
- Fixed 512-byte slots
- Lock-free operations
- No allocations on hot path

Thread Safety:

- All read operations are thread-safe
- Concurrent writes require external synchronization
- Atomic operations on slot versions prevent torn reads

Performance Characteristics:

- Lookup: O(1) average, O(k) worst case where k = MAX_PROBE_DISTANCE
- Insert: O(1) average for static slots, O(k) for dynamic slots
- Memory: 512 bytes per slot + 512 byte header
- Cache: Optimized for CPU cache lines (64-byte aligned slots)

Definition in file maph.hpp.

## Class Documentation

## ◆ maph::Header

struct maph::Header

Database file header containing metadata.

The header is exactly 512 bytes and contains database configuration and runtime statistics. It's placed at the beginning of the mmap'd file.

Definition at line 196 of file maph.hpp.

Collaboration diagram for maph::Header:

Class Members
atomic< uint64_t > | generation {0} | Global generation counter (incremented on modifications)
uint32_t | magic {MAGIC_NUMBER} | Magic number for file validation ("MAPH")
uint64_t | num_slots {0} |
char | padding[488] {} |
char | reserved[480] {} | Reserved space for future extensions.
uint64_t | slot_size {sizeof(Slot)} |
uint64_t | static_slots {0} | Number of slots using perfect hashing (no collisions)
uint64_t | total_slots {0} | Total number of slots in database.
uint32_t | version {CURRENT_VERSION} | Database format version.

## ◆ maph::Hash::Result

struct maph::Hash::Result

Hash computation result.

Definition at line 221 of file maph.hpp.

Collaboration diagram for maph::Hash::Result:

Class Members
uint32_t | hash | Full 32-bit hash value.
uint32_t | index | Slot index (hash % num_slots)

## ◆ maph::Maph::Stats

struct maph::Maph::Stats

Database statistics.

Definition at line 730 of file maph.hpp.

Collaboration diagram for maph::Maph::Stats:

Class Members
uint64_t | generation | Current generation number.
double | load_factor | Ratio of used to total slots.
size_t | memory_bytes | Total memory usage in bytes.
uint64_t | static_slots | Number of perfect hash slots.
uint64_t | total_slots | Total number of slots.
uint64_t | used_slots | Number of occupied slots.