MmapCache 1.0.3

MmapCache (LSM Engine)

An off-heap LSM storage engine for .NET with active mutation support and zero-downtime compaction.

MmapCache stores data in off-heap memory-mapped (mmap) segment files utilizing a lock-free LSM (Log-Structured Merge-tree) architecture. It fully supports WAL (Write-Ahead Log) crash-recovery, active live mutations, automatic background compaction, and completely lock-free segment reads.

Table of Contents

• Why MmapCache LSM?
• Features
• Installation
• Quick Start
• Configuration Reference
• How It Works
• WAL and Crash Recovery
• Flush and Immutable SSTables
• Compaction
• TTL & Lazy Expiration
• Reload & Bootstrapping
• Performance & Stress-Test Benchmarks
• Contributing
• License

Why MmapCache LSM?

Most in-process caches and embedded stores suffer from:

• GC Fragmentation & Pauses - Constantly overwriting objects creates holes in the managed heap, leading to severe garbage collection compaction cycles.
• Data Volatility - Standard caching layers lose all mutated state instantly if the target process crashes or suffers an unhandled termination.
• Reload Lockouts - Having to periodically rebuild large data structures entirely from external databases is expensive, slow, and resource-heavy.

By restructuring the system strictly with an LSM architecture, every mutation is recorded purely with append-friendly I/O to a sequential WAL and a memory-efficient Radix Tree MemTable. When size triggers are reached, the memory is locked, serialized continuously off-heap into an SSTable mapped strictly via OS memory-mapping (mmap), and native pointers are safely recycled. This effectively guarantees Zero Managed Memory Leaks and deterministic overhead over time.

Features

Installation

dotnet add package MmapCache

Targets net8.0, net9.0, and net10.0.

-- MmapCache is released under the GPL-3.0 license. If you intend to use it inside a closed-source commercial product, review the license terms carefully.

Quick Start

using MmapCache.Cache;
using MmapCache.Config;
using System.Text.Json;

// -- 1. Initialize once at application startup --------------------------------
MmapCacheManager.Initialize(
    basePath : "/var/cache/myapp");  // LSM log and sst files are written here

// -- 2. Describe what to store ------------------------------------------------
var productDef = new MmapCacheDefinition<Product>
{
    Name = "products",
    // Supplier runs ONLY if the engine boots from an empty/clean disk state
    Supplier = () => db.Products.Select(p => (p.Id.ToString(), p)),
    Serializer = p => JsonSerializer.SerializeToUtf8Bytes(p),
    Deserializer = b => JsonSerializer.Deserialize<Product>(b)!,
    Ttl = TimeSpan.FromHours(1)
};

// -- 3. Register Engine Instance ----------------------------------------------
// Restores from on-disk SSTables instantly, replays WAL if recovering from a crash.
MmapCacheManager.Instance.Register(productDef);

// -- 4. Active Mutability (Put/Delete) ----------------------------------------
// Mutations are immediately visible and durably piped to the active WAL
MmapCacheManager.Instance.Put("products", "product_42", new Product("product_42", "Updated!", 9.99m, 50));
MmapCacheManager.Instance.Delete("products", "product_99");

// -- 5. Concurrent Reads (lock-free logic) ------------------------------------
var product = MmapCacheManager.Instance.Get<Product>("products", "product_42");

if (MmapCacheManager.Instance.TryGet<Product>("products", "product_42", out var p))
    Console.WriteLine(p!.Name);

// -- 6. Dispose on shutdown ----------------------------------------------------
// Safely unmaps memory handles and flushes remaining active WAL stream buffers
await MmapCacheManager.Instance.DisposeAsync();

Configuration Reference

MmapCacheDefinition<TValue> accepts the following core properties:

How It Works

WAL and Crash Recovery

When inserting new values, records are structured and packaged sequentially onto a wal_XX.log with a CRC32 checksum footprint. If the cache terminates unpredictably, the engine parses .sst segment offsets rapidly and walks forward along the WAL frames up to the last valid bitwise block to guarantee exact state synchronization.

Flush and Immutable SSTables

Whenever the active MemTable surpasses its memory threshold, operations swap the active buffer out into an asynchronous background flush task. Flushed tables output precisely structured segment_N.sst files. Because our unmanaged Radix Tree naturally maintains data in lexicographical order, SSTable segments are dumped to disk sequentially, eliminating expensive in-memory sorting overheads.

Compaction

Since MemTable writes sequentially produce separate SSTable files, modifying similar keys creates duplicate logical offsets across multiple segments over time. An asynchronous Compactor thread periodically scans these segments, merges overlapping key spaces, resolves tombstones (deletions), and atomically updates the unmanaged index mapping without interrupting concurrent Get actions.

TTL & Lazy Expiration

Time-To-Live (TTL) is handled seamlessly without imposing structural overhead on the underlying LSM engine. MmapCacheManager prefixes the serialized byte array with an 8-byte expireTicks timestamp. The Radix Tree and Bloom Filter remain fully agnostic to this, storing and retrieving raw payloads efficiently. When a record is fetched (Get), the timestamp is evaluated in real-time. If expired, the record is immediately dropped via a lazy-delete mechanism (Tombstone), making it logically invisible.

Reload & Bootstrapping

When ReloadAsync is invoked, it completely resets the engine state with zero downtime. The Radix Tree, Bloom Filter, and active MemTables are instantly cleared from RAM, while stale .sst and .log files are wiped from the disk. The engine immediately re-hydrates itself by streaming fresh, up-to-date data directly from the user-defined Supplier.

Performance & Stress-Test Benchmarks

The metrics below represent the performance of the off-heap unmanaged engine under high-concurrency stress testing. Writes execute in consecutive chunks (Super Chunks), with each batch triggering deep native cleanup routines. Configurations include dynamically scaling RadixTreeCapacity to match payload size, paired with aggressive FlushThreshold constraints for memory safety.

Scalability Measurement Ledger (StressTest_Scale_Measurements)

Note: GC counts shown are cumulative across both write and read phases for each test iteration. Write throughput remains consistently above 120K ops/sec even at 100M scale, demonstrating linear scalability.

Read Latency Distribution (Percentile Analysis)

Key Insight: p50 latency remains < 3.1 us across all scales. Even at 100M records, the median read latency is only 1.30 us, proving the effectiveness of the unmanaged RadixTree and Bloom Filter front-end.

Detailed Heap Metrics (100M Record Benchmark)

Architectural Insights & Analysis

1. Memory Stabilization Success (Working Set)

By leveraging chunked write boundaries past 1M records and implementing a completely off-heap unmanaged ConcurrentRadixTree, the operating system physical RAM footprint demonstrates remarkable stability:

• 5M-100M scale (20x growth): Post-write Working Set remains between 2.56-15.68 MB
• Each test iteration returns to pristine baseline (~0.8-0.9 MB) after cleanup
• No cumulative memory leakage across progressively larger datasets

2. Deterministic O(1)-like Read Latency

While total read duration naturally scales with dataset size, per-operation latency remains exceptionally stable:

Key takeaway: After warm-up, read latency stabilizes to ~1.5-1.9 us average regardless of dataset size. Pointer hopping on unmanaged memory layout, combined with front-facing Bloom Filter evaluations, keeps read speeds isolated from scale degradation.

3. Write Throughput Scaling

Observation: Intentionally lowering FlushThreshold at high volumes (dropping to 2MB at 100M keys) bounds memory overhead but introduces more frequent disk I/O switching. This represents a clean engineering tradeoff between memory safety and maximum disk ingestion speeds.

4. Zero LOH or Managed Bloat

Despite processing massive total throughput (cumulative net allocated memory ~134 GB across the 100M sequence), unmanaged pointer mappings keep the Large Object Heap (LOH) remarkably clean:

• Post-write LOH: 0.09 MB (baseline) for all scales except 1M+ read phases
• Post-read LOH: Grows to accommodate read buffers but cleans up completely
• Aggressive GC collections sweep managed residue effectively

5. GC Pressure Analysis

The write phase generates most GC pressure due to serialization and temporary buffer allocations. The read phase is significantly more efficient, with Gen2 collections dropping to near-zero at smaller scales. At 100M, read phase Gen2 collections (401) represent only ~15% of write phase collections (2,686).

Performance Notes

• Early Read Exits: Read requests (Get) first pass through an internal Bloom Filter. If a key does not exist, the engine returns immediately without traversing the tree or touching the disk.
• Prefix Memory Sharing: By replacing traditional Hash Maps with a ConcurrentRadixTree, keys with common prefixes (like session_xyz, session_abc) share memory nodes. This prevents massive string allocation overheads and reduces the managed heap footprint significantly.
• Lock-Free Reads: Read traversals down the Radix Tree do not use heavy locking mechanisms (like ReaderWriterLock or SemaphoreSlim). Node structural integrity is maintained safely, allowing thousands of concurrent reads.
• GC Impact is Minimal: The only managed allocation per read is the deserialized TValue object. Shard data and binary payloads are sliced directly from the MemoryMappedViewAccessor via zero-copy ReadOnlySpan<byte>.
• Deterministic Cleanup: After each stress test iteration, the engine returns to ~0.8 MB working set - proof of zero memory leaks in the unmanaged layer.

Contributing

Pull requests are welcome. For significant architectural adjustments, please open an issue first to discuss your proposed strategy.

git clone https://github.com/BurakKontas/MmapCache
cd MmapCache
dotnet build
dotnet test MmapCache.Tests/MmapCache.Tests.csproj -v normal

Please note that contributions are subject to the terms of the GPL-3.0 license - by submitting a pull request you agree that your contribution will be distributed under the same license terms.

License

Copyright (C) 2026 Arda Burak Kontas

MmapCache is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.