🪣 hashmap-mem

A memory-efficient hashmap implementation designed for Virtual Machine implementations (specifically the Swamp VM) and similar low-level use cases.

What is this?

hashmap-mem is a specialized hashmap implementation designed primarily for use in Virtual Machine implementations, particularly the Swamp VM environment, following the Swamp VM collection standard.

This is not a general-purpose hashmap with all the safety guarantees you'd expect from a standard Rust collection. Instead, it's a memory-optimized implementation. For a more "normal" hashmap implementation with the rust security guarantees, please checkout my seq-map crate:

👉 📦 seq-map (github)

Features

Fast lookups: Uses FxHasher64 for efficient hashing
Tombstone-based deletion: Quick removal of entries without costly rehashing
Can not, by design, be resized

Safety

This crate uses unsafe code extensively and expects you to manage memory correctly.

Memory must be properly allocated and aligned and deallocated after use.
The map must be properly initialized before use
Key and value pointers must be valid

Memory Layout

The hashmap consists of a header followed by buckets:

+-------------+
| MapHeader   |
+-------------+
| Bucket 0    |
| Bucket 1    |
| ...         |
| Bucket N-1  |
+-------------+

Each bucket has:

A status byte (Empty, Tombstone, or Occupied)
Key data (properly aligned)
Value data (properly aligned)

API Overview

layout: Calculate memory layout for the map
init: Initialize a new map in pre-allocated memory
get_or_reserve_entry: Find or create an entry for a key
lookup: Find an existing entry
has: Check if a key exists
remove: Remove an entry
overwrite: Copy all entries from one map to another
find_next_valid_entry: Iterator-like functionality

License

This is my personal open source project. While you can use the code under the LICENSE, I'm not accepting pull requests at this time.

Feel free to:

Use and fork the code
Report issues
Share feedback
Spread the word

If you have ideas or find bugs, open an issue and I'll check it out. Though I can't merge external code right now, your input is always appreciated!

Thanks for understanding! 🙏