How MMKV Achieves Fast Multi‑Process Key‑Value Storage on Android

Preface

MMKV is a mobile‑oriented key‑value component built on mmap with protobuf serialization, proven stable on iOS for three years and recently ported to Android. After open‑sourcing, it gained wide internal adoption at Tencent.

IPC Selection

CS Architecture vs Decentralized Architecture

Using a ContentProvider (a client‑server CS model) on Android is simple but slow because every access incurs Binder communication and additional memory copies. MMKV aims for extreme speed, so it avoids CS architectures and adopts a decentralized approach: each process mmaps the same file, uses a process lock, and synchronizes data.

Choosing a Process Lock

Android’s limited IPC support makes robust locking challenging. Pthread mutexes are not robust on Android; if a process holding the lock is killed, the lock remains forever. Robust options are file descriptors, file locks, and Binder death notifications.

File lock : naturally robust but lacks recursive locking and read‑write lock upgrades.

pthread_mutex : supports recursion and lock upgrades but is not robust and requires manual cleanup.

The team initially adopts file locks as a simple mutex and plans to address recursion and lock upgrades later.

Multi‑Process Implementation Details

MMKV maps a file into memory and appends new key‑value pairs. When the write pointer moves, memory is compacted, or the file grows, other processes must detect these changes.

State Synchronization

Write‑pointer sync: each process caches its write pointer and compares it with the value stored in the mmap header (the effective memory size).

Memory compaction detection: a monotonically increasing sequence number is stored in mmap; processes compare their cached value to detect compaction.

Memory growth detection: growth follows a failed compaction, so the same sequence‑number logic applies; the new file size can be obtained from the file itself.

The synchronization logic can be expressed in pseudocode (illustrated in the following diagram).

Write‑Pointer Growth

When a process detects that the mmap write pointer has advanced, it reads the newly appended entries, merges or replaces existing keys, and updates its local write pointer.

Memory Compaction

If a process discovers that memory has been compacted, the previous keys become invalid; the simplest solution is to discard the old state and reload from the beginning.

Memory Growth

Memory growth always follows a compaction, so the handling is identical to the compaction case.

File Lock Enhancements

To support recursive locking and lock upgrade/downgrade, the file lock is wrapped with counters for read and write locks.

Recursive lock: a process that already holds a lock can acquire it again without deadlocking; unlocking once releases the lock entirely.

Lock upgrade/downgrade: upgrading a shared lock to exclusive can cause deadlock if multiple processes attempt it simultaneously; downgrading is not directly supported by file locks.

The lock handling logic is summarized in the diagram below.

Key points:

When acquiring a write lock while holding a read lock, attempt a try‑lock; if it fails, release the read lock first to avoid deadlock.

When releasing a write lock, if a read lock was previously held, acquire a read lock before fully releasing to prevent accidental read‑lock loss.

MMKV Multi‑Process Performance

A simple benchmark creates two services and measures read/write latency of MMKV, MultiProcessSharedPreferences, and SQLite under identical conditions (Pixel 2 XL, Android 8.1, 1000 iterations per test). Results are shown below.

(Test environment: Pixel 2 XL 64 GB, Android 8.1.0; times in ms; MultiProcessSharedPreferences uses apply(); SQLite opened with WAL.)