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

Loading...
Searching...
No Matches
Classes | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
maph::Maph Class Reference

Main maph class - lean and fast. More...

`#include <maph.hpp>`

Collaboration diagram for maph::Maph:

## Classes
class | DurabilityManager
struct | Stats
| Database statistics. More...

## Public Member Functions
| Maph ()=default
| ~Maph ()
| Maph (const Maph &)=delete
Maph & | operator= (const Maph &)=delete
| Maph (Maph &&other) noexcept
Maph & | operator= (Maph &&other) noexcept
std::optional< JsonView > | get (JsonView key) const
| Get value for a key.
bool | set (JsonView key, JsonView value)
| Store a key-value pair.
bool | remove (JsonView key)
| Remove a key-value pair.
bool | exists (JsonView key) const
| Check if a key exists.
template<typename Callback >
void | mget (const std::vector< JsonView > &keys, Callback &&cb) const
| Get multiple keys in a single operation.
size_t | mset (const std::vector< std::pair< JsonView, JsonView > > &kvs)
| Set multiple key-value pairs.
template<typename Visitor >
void | scan (Visitor &&visit) const
| Scan all key-value pairs in the database.
void | sync ()
| Force synchronization to disk.
void | close ()
| Close the database and unmap memory.
Stats | stats () const
| Get database statistics.
template<typename Callback >
void | parallel_mget (const std::vector< JsonView > &keys, Callback &&cb, size_t thread_count=0) const
size_t | parallel_mset (const std::vector< std::pair< JsonView, JsonView > > &kvs, size_t thread_count=0)
template<typename Visitor >
void | parallel_scan (Visitor &&visit, size_t thread_count=0) const
void | enable_durability (std::chrono::milliseconds interval=std::chrono::seconds(1))
void | disable_durability ()
void | sync_now ()
| Maph ()=default
| ~Maph ()
| Maph (const Maph &)=delete
Maph & | operator= (const Maph &)=delete
| Maph (Maph &&other) noexcept
Maph & | operator= (Maph &&other) noexcept
std::string | get (const std::string &json_key) const
bool | set (const std::string &json_key, const std::string &json_value)
bool | exists (const std::string &json_key) const
bool | remove (const std::string &json_key)
std::vector< std::string > | mget (const std::vector< std::string > &keys) const
void | set_hash_function (std::function< uint32_t(const std::string &)> fn)
size_t | size () const
size_t | used () const
uint64_t | generation () const
void | sync ()
void | close ()

## Static Public Member Functions
static std::unique_ptr< Maph > | create (const std::string &path, uint64_t total_slots, uint64_t static_slots=0)
| Create a new database file.
static std::unique_ptr< Maph > | open (const std::string &path, bool readonly=false)
| Open an existing database file.
static std::unique_ptr< Maph > | create (const std::string &path, size_t num_slots)
static std::unique_ptr< Maph > | open (const std::string &path, bool readonly=false)

## Public Attributes
std::unique_ptr< DurabilityManager > | durability_

## Detailed Description

Main maph class - lean and fast.

High-performance memory-mapped key-value store.

Provides a persistent key-value database with sub-microsecond lookups using memory-mapped I/O and approximate perfect hashing.

Features:

- O(1) average-case lookups
- Zero-copy string operations
- Lock-free reads
- Automatic persistence via mmap
- Parallel batch operations
- Optional async durability

Usage Example:

auto db = Maph::create("data.maph", 1000000);
db->set("user:123", "{\"name\":\"Alice\"}");
auto value = db->get("user:123");
maph::Maph::create
static std::unique_ptr< Maph > create(const std::string &path, uint64_t total_slots, uint64_t static_slots=0)
Create a new database file.
Definition maph.hpp:387

Definition at line 351 of file maph.hpp.

## Class Documentation

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

## Constructor & Destructor Documentation

## ◆ Maph() [1/6]

maph::Maph::Maph | ( |  | ) |
| default

## ◆ ~Maph() [1/2]

maph::Maph::~Maph | ( |  | ) |
| inline

Definition at line 362 of file maph.hpp.

References close().

Here is the call graph for this function:

## ◆ Maph() [2/6]

maph::Maph::Maph | ( | const Maph & |  | ) |
| delete

## ◆ Maph() [3/6]

maph::Maph::Maph | ( | Maph && | other | ) |
| inline noexcept

Definition at line 367 of file maph.hpp.

## ◆ Maph() [4/6]

maph::Maph::Maph | ( |  | ) |
| default

## ◆ ~Maph() [2/2]

maph::Maph::~Maph | ( |  | ) |
| inline

Definition at line 68 of file maph.hpp.

References close().

Here is the call graph for this function:

## ◆ Maph() [5/6]

maph::Maph::Maph | ( | const Maph & |  | ) |
| delete

## ◆ Maph() [6/6]

maph::Maph::Maph | ( | Maph && | other | ) |
| inline noexcept

Definition at line 73 of file maph.hpp.

## Member Function Documentation

## ◆ close() [1/2]

void maph::Maph::close | ( |  | ) |
| inline

Close the database and unmap memory.

Unmaps the memory region and closes the file descriptor. Any pending changes are automatically flushed by the OS.

Note
  Automatically called by destructor

Definition at line 715 of file maph.hpp.

References close().

Referenced by close(), create(), create(), open(), operator=(), and ~Maph().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ close() [2/2]

void maph::Maph::close | ( |  | ) |
| inline

Definition at line 293 of file maph.hpp.

References close().

Here is the call graph for this function:

## ◆ create() [1/2]

static std::unique_ptr< Maph > maph::Maph::create | ( | const std::string & | path,
|  | size_t | num_slots
| ) |  |
| inline static

Definition at line 92 of file maph.hpp.

References close(), maph::Header::num_slots, and open().

Here is the call graph for this function:

## ◆ create() [2/2]

static std::unique_ptr< Maph > maph::Maph::create | ( | const std::string & | path,
|  | uint64_t | total_slots,
|  | uint64_t | static_slots = `0`
| ) |  |
| inline static

Create a new database file.

Creates a new memory-mapped database with specified capacity. The file is immediately mapped into memory and ready for use.

Parameters

  path | File path for the database
  total_slots | Total number of slots to allocate
  static_slots | Number of slots for perfect hashing (default: 80% of total)

Returns
  Unique pointer to database, or nullptr on failure

Note
  File size will be: 512 bytes (header) + total_slots * 512 bytes
  Static slots use perfect hashing (no collisions)
  Dynamic slots use linear probing for collision resolution

Definition at line 387 of file maph.hpp.

References close(), maph::DEFAULT_STATIC_RATIO, open(), and maph::Header::total_slots.

Referenced by maph::MaphBuilder::build(), StoreRegistry::create(), and maph::create().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ disable_durability()

void maph::Maph::disable_durability | ( |  | ) |
| inline

Definition at line 929 of file maph.hpp.

## ◆ enable_durability()

void maph::Maph::enable_durability | ( | std::chrono::milliseconds | interval = `std::chrono::seconds(1)` | ) |
| inline

Definition at line 923 of file maph.hpp.

## ◆ exists() [1/2]

bool maph::Maph::exists | ( | const std::string & | json_key | ) | const
| inline

Definition at line 224 of file maph.hpp.

References maph::Header::num_slots, and maph::Slot::size.

## ◆ exists() [2/2]

bool maph::Maph::exists | ( | JsonView | key | ) | const
| inline

Check if a key exists.

Parameters

  key | Key to check

Returns
  true if key exists in database

Definition at line 617 of file maph.hpp.

References get().

Here is the call graph for this function:

## ◆ generation()

uint64_t maph::Maph::generation | ( |  | ) | const
| inline

Definition at line 285 of file maph.hpp.

References maph::Header::generation.

## ◆ get() [1/2]

std::string maph::Maph::get | ( | const std::string & | json_key | ) | const
| inline

Definition at line 187 of file maph.hpp.

References maph::Header::num_slots.

## ◆ get() [2/2]

std::optional< JsonView > maph::Maph::get | ( | JsonView | key | ) | const
| inline

Get value for a key.

Performs O(1) lookup using perfect hashing for static slots or linear probing for dynamic slots.

Parameters

  key | Key to look up

Returns
  Optional containing value if found, empty optional otherwise

Note
  Returns a string_view - data is valid until slot is modified
  Thread-safe for concurrent reads

Performance:

- Static slots: 1 memory access
- Dynamic slots: 1-10 memory accesses (average ~1.5)

Definition at line 498 of file maph.hpp.

References maph::Hash::compute(), maph::Slot::empty(), maph::Slot::hash, maph::MAX_PROBE_DISTANCE, maph::Header::total_slots, and maph::Slot::view().

Referenced by exists(), main(), mget(), mget(), and parallel_mget().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ mget() [1/2]

template<typename Callback >

void maph::Maph::mget | ( | const std::vector< JsonView > & | keys,
|  | Callback && | cb
| ) |  | const
| inline

Get multiple keys in a single operation.

Retrieves multiple keys efficiently by prefetching memory. Calls the callback for each key-value pair found.

Template Parameters

  Callback | Callable with signature void(JsonView key, JsonView value)

Parameters

  keys | Vector of keys to retrieve
  cb | Callback function for each found key-value pair

Note
  Uses memory prefetching for better cache performance

Definition at line 636 of file maph.hpp.

References maph::Hash::compute(), get(), and maph::Header::total_slots.

Referenced by parallel_mget().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ mget() [2/2]

std::vector< std::string > maph::Maph::mget | ( | const std::vector< std::string > & | keys | ) | const
| inline

Definition at line 249 of file maph.hpp.

References get().

Here is the call graph for this function:

## ◆ mset()

size_t maph::Maph::mset | ( | const std::vector< std::pair< JsonView, JsonView > > & | kvs | ) |
| inline

Set multiple key-value pairs.

Parameters

  kvs | Vector of key-value pairs to store

Returns
  Number of pairs successfully stored

Note
  Some pairs may fail if table is full or values too large

Definition at line 659 of file maph.hpp.

References set().

Referenced by parallel_mset().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ open() [1/2]

static std::unique_ptr< Maph > maph::Maph::open | ( | const std::string & | path,
|  | bool | readonly = `false`
| ) |  |
| inline static

Open an existing database file.

Opens and memory-maps an existing database file. Validates the file format and version compatibility.

Parameters

  path | Path to existing database file
  readonly | Open in read-only mode (default: read-write)

Returns
  Unique pointer to database, or nullptr on failure

Note
  Read-only mode allows multiple readers without locking
  Returns nullptr if file doesn't exist or has invalid format

Definition at line 442 of file maph.hpp.

References close(), and open().

Referenced by create(), create(), open(), and StoreRegistry::StoreRegistry().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ open() [2/2]

static std::unique_ptr< Maph > maph::Maph::open | ( | const std::string & | path,
|  | bool | readonly = `false`
| ) |  |
| inline static

Definition at line 138 of file maph.hpp.

References close(), maph::Header::magic, maph::Header::num_slots, and open().

Here is the call graph for this function:

## ◆ operator=() [1/4]

Maph & maph::Maph::operator= | ( | const Maph & |  | ) |
| delete

## ◆ operator=() [2/4]

Maph & maph::Maph::operator= | ( | const Maph & |  | ) |
| delete

## ◆ operator=() [3/4]

Maph & maph::Maph::operator= | ( | Maph && | other | ) |
| inline noexcept

Definition at line 368 of file maph.hpp.

## ◆ operator=() [4/4]

Maph & maph::Maph::operator= | ( | Maph && | other | ) |
| inline noexcept

Definition at line 74 of file maph.hpp.

References close().

Here is the call graph for this function:

## ◆ parallel_mget()

template<typename Callback >

void maph::Maph::parallel_mget | ( | const std::vector< JsonView > & | keys,
|  | Callback && | cb,
|  | size_t | thread_count = `0`
| ) |  | const
| inline

Definition at line 766 of file maph.hpp.

References maph::Hash::compute(), get(), mget(), and maph::Header::total_slots.

Here is the call graph for this function:

## ◆ parallel_mset()

size_t maph::Maph::parallel_mset | ( | const std::vector< std::pair< JsonView, JsonView > > & | kvs,
|  | size_t | thread_count = `0`
| ) |  |
| inline

Definition at line 808 of file maph.hpp.

References mset(), and set().

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ parallel_scan()

template<typename Visitor >

void maph::Maph::parallel_scan | ( | Visitor && | visit,
|  | size_t | thread_count = `0`
| ) |  | const
| inline

Definition at line 848 of file maph.hpp.

References maph::Slot::empty(), and maph::Header::total_slots.

Here is the call graph for this function:

## ◆ remove() [1/2]

bool maph::Maph::remove | ( | const std::string & | json_key | ) |
| inline

Definition at line 231 of file maph.hpp.

References maph::Header::generation, and maph::Header::num_slots.

## ◆ remove() [2/2]

bool maph::Maph::remove | ( | JsonView | key | ) |
| inline

Remove a key-value pair.

Removes the specified key from the database. The slot is marked as empty and can be reused.

Parameters

  key | Key to remove

Returns
  true if key was found and removed, false otherwise

Note
  Not thread-safe - requires external synchronization

Definition at line 579 of file maph.hpp.

References maph::Slot::clear(), maph::Hash::compute(), maph::Slot::empty(), maph::Header::generation, maph::Slot::hash, maph::MAX_PROBE_DISTANCE, and maph::Header::total_slots.

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ scan()

template<typename Visitor >

void maph::Maph::scan | ( | Visitor && | visit | ) | const
| inline

Scan all key-value pairs in the database.

Iterates through all non-empty slots and calls the visitor.

Template Parameters

  Visitor | Callable with signature void(uint64_t index, uint32_t hash, JsonView value)

Parameters

  visit | Visitor function called for each key-value pair

Note
  Scans all slots sequentially - O(n) where n is total_slots

Definition at line 682 of file maph.hpp.

References maph::Slot::empty(), maph::Slot::hash, maph::Header::total_slots, and maph::Slot::view().

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ set() [1/2]

bool maph::Maph::set | ( | const std::string & | json_key,
|  | const std::string & | json_value
| ) |  |
| inline

Definition at line 201 of file maph.hpp.

References maph::Header::generation, maph::Slot::MAX_JSON_SIZE, and maph::Header::num_slots.

## ◆ set() [2/2]

bool maph::Maph::set | ( | JsonView | key,
|  | JsonView | value
| ) |  |
| inline

Store a key-value pair.

Stores or updates a key-value pair in the database. For static slots, always overwrites existing value. For dynamic slots, uses linear probing to find slot.

Parameters

  key | Key to store
  value | Value to store (max 496 bytes)

Returns
  true if stored successfully, false if table full or value too large

Note
  Not thread-safe - requires external synchronization for concurrent writes
  Automatically persisted via mmap (OS handles disk sync)

Definition at line 539 of file maph.hpp.

References maph::Hash::compute(), maph::Slot::empty(), maph::Header::generation, maph::Slot::hash, maph::MAX_PROBE_DISTANCE, maph::Slot::MAX_SIZE, maph::Slot::set(), and maph::Header::total_slots.

Referenced by main(), mset(), and parallel_mset().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ set_hash_function()

void maph::Maph::set_hash_function | ( | std::function< uint32_t(const std::string &)> | fn | ) |
| inline

Definition at line 271 of file maph.hpp.

## ◆ size()

size_t maph::Maph::size | ( |  | ) | const
| inline

Definition at line 275 of file maph.hpp.

References maph::Header::num_slots.

Referenced by used().

Here is the caller graph for this function:

## ◆ stats()

Stats maph::Maph::stats | ( |  | ) | const
| inline

Get database statistics.

Computes current database statistics including memory usage and load factor. This operation scans all slots (O(n)).

Returns
  Statistics structure

Definition at line 747 of file maph.hpp.

References maph::Header::generation, maph::Header::static_slots, maph::Header::total_slots, and used().

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ sync() [1/2]

void maph::Maph::sync | ( |  | ) |
| inline

Force synchronization to disk.

Requests the OS to flush memory-mapped changes to disk. Uses MS_ASYNC for non-blocking operation.

Note
  Usually not needed - OS handles sync automatically

Definition at line 701 of file maph.hpp.

## ◆ sync() [2/2]

void maph::Maph::sync | ( |  | ) |
| inline

Definition at line 287 of file maph.hpp.

## ◆ sync_now()

void maph::Maph::sync_now | ( |  | ) |
| inline

Definition at line 933 of file maph.hpp.

## ◆ used()

size_t maph::Maph::used | ( |  | ) | const
| inline

Definition at line 277 of file maph.hpp.

References maph::Header::num_slots, and size().

Referenced by stats().

Here is the call graph for this function:
Here is the caller graph for this function:

## Member Data Documentation

## ◆ durability_

std::unique_ptr<DurabilityManager> maph::Maph::durability_

Definition at line 920 of file maph.hpp.

The documentation for this class was generated from the following files:

- include/maph.hpp
- include/maph/maph.hpp