概述
透過 mmap 技術實現的高效能通用 key-value 元件。同時選用 protobuf 協議，進一步壓縮資料儲存。
標準 protobuf 不提供增量更新的能力，每次寫入都必須全量寫入。考慮到主要使用場景是頻繁地進行寫入更新，我們需要有增量更新的能力：將增量 kv 物件序列化後，直接 append 到記憶體末尾；這樣同一個 key 會有新舊若干份資料，最新的資料在最後；那麼只需在程式啟動第一次開啟 mmkv 時，不斷用後讀入的 value 替換之前的值，就可以保證資料是最新有效的。
使用 append 實現增量更新帶來了一個新的問題，就是不斷 append 的話，檔案大小會增長得不可控。例如同一個 key 不斷更新的話，是可能耗盡幾百 M 甚至上 G 空間，而事實上整個 kv 檔案就這一個 key，不到 1k 空間就存得下。這明顯是不可取的。我們需要在效能和空間上做個折中：以記憶體 pagesize 為單位申請空間，在空間用盡之前都是 append 模式；當 append 到檔案末尾時，進行檔案重整、key 排重，嘗試序列化儲存排重結果；排重後空間還是不夠用的話，將檔案擴大一倍，直到空間足夠。
檔案資料結構
一個 MMKV 物件會生成兩個檔案，一個儲存資料的主檔案，一個 crc 校驗檔案，檔名規則為：
// 主檔名為 mmapedKVKey() 返回值， crc 校驗檔名為 mmapedKVKey()返回值加上 .crc 字尾
string mmapedKVKey(const string &mmapID, const MMKVPath_t *rootPath) {
if (rootPath && g_rootDir != (*rootPath)) {
return md5(*rootPath + MMKV_PATH_SLASH + string2MMKVPath_t(mmapID));
}
return mmapID;
}
主檔案
前四個位元組記錄了儲存資料的總大小，緊接著儲存每一個 key-value 對，由於使用了 protobuf 編碼，為了便於讀取 key、value 的資料，在儲存具體資料前都先記錄下其佔用的位元組數。由於 keyLength 和 valueLength 都為 int32 整數，因此直接按照 protobuf 編碼規則讀取即可，無需像 key、value 需要一個長度來確定值的結束邊界。
+--------------+------------+------+--------------+--------+------------+------+---------------+-------+
| 儲存的資料大小 | keyLength1 | key1 | valueLength1 | value1 | keyLength2 | key2 | valueLength2 | value2 |
+--------------+------------+------+--------------+--------+------------+------+---------------+-------+
CRC檔案
CRC檔案中儲存的內容為以下結構體定義的資料結構，包括 crc32 校驗和的值以及一堆輔助資料，用以驗證檔案的一致性。
struct MMKVMetaInfo {
uint32_t m_crcDigest = 0;
uint32_t m_version = MMKVVersionSequence;
uint32_t m_sequence = 0; // full write-back count
uint8_t m_vector[AES_KEY_LEN] = {};
uint32_t m_actualSize = 0;
// confirmed info: it's been synced to file
struct {
uint32_t lastActualSize = 0;
uint32_t lastCRCDigest = 0;
uint32_t _reserved[16] = {};
} m_lastConfirmedMetaInfo;
}
資料初始化
MMKV 物件構造時會呼叫 loadFromFile 讀取資料，將檔案中的 key-value 對讀取到一個 dict 中儲存。dict 是一個 std::unordered_map<std::string, mmkv::KeyValueHolder> 結構，dict 的 key 即為儲存的 key-value 對中的 key。並且透過 KeyValueHolder 來儲存 key-value 對的內容。
// MiniPBCoder.cpp#decodeOneMap
auto block = [position, this](MMKVMap &dictionary) {
if (position) {
m_inputData->seek(position);
} else {
m_inputData->readInt32();
}
while (!m_inputData->isAtEnd()) {
KeyValueHolder kvHolder;
// 讀取 key，儲存 key 的 起始位置和size資訊到 KeyValueHoder 中
const auto &key = m_inputData->readString(kvHolder);
if (key.length() > 0) {
// 讀取 value，儲存 value 的size資訊到 KeyValueHolder，此時並不會將 value 解碼出來
m_inputData->readData(kvHolder);
if (kvHolder.valueSize > 0) {
dictionary[key] = move(kvHolder);
} else {
auto itr = dictionary.find(key);
if (itr != dictionary.end()) {
dictionary.erase(itr);
}
}
}
}
};
// CodedInputData.cpp#readString
// 讀取 key
string CodedInputData::readString(KeyValueHolder &kvHolder) {
kvHolder.offset = static_cast<uint32_t>(m_position);
int32_t size = this->readRawVarint32();
if (size < 0) {
throw length_error("InvalidProtocolBuffer negativeSize");
}
auto s_size = static_cast<size_t>(size);
if (s_size <= m_size - m_position) {
kvHolder.keySize = static_cast<uint16_t>(s_size);
auto ptr = m_ptr + m_position;
string result((char *) (m_ptr + m_position), s_size);
m_position += s_size;
return result;
} else {
throw out_of_range("InvalidProtocolBuffer truncatedMessage");
}
}
// CodedInputData.cpp#readData
// 讀取 value
void CodedInputData::readData(KeyValueHolder &kvHolder) {
int32_t size = this->readRawVarint32();
if (size < 0) {
throw length_error("InvalidProtocolBuffer negativeSize");
}
auto s_size = static_cast<size_t>(size);
if (s_size <= m_size - m_position) {
kvHolder.computedKVSize = static_cast<uint16_t>(m_position - kvHolder.offset);
kvHolder.valueSize = static_cast<uint32_t>(s_size);
m_position += s_size;
} else {
throw out_of_range("InvalidProtocolBuffer truncatedMessage");
}
}
資料寫入與讀取
這裡僅分析在 Android 平臺的主流程邏輯，因此對於加密功能和在 iOS 裝置上的邏輯不去關注。由於 MMKV 對於 value 支援多種型別格式，這裡也主要透過型別為 int 和 string 的寫入和讀取邏輯來進行了解。
MMBuffer
MMKV 中定義的記憶體單元，用來更方便的進行一些操作而抽象的結構。對於佔用記憶體小的資料，直接儲存在棧中，而對於佔用記憶體大的資料則儲存在堆中。
判斷佔用記憶體的大小取決於 sizeof(MMBuffer) - offsetof(MMBuffer, paddedBuffer) 計算的值，其實也就是 paddedBuffer[10] 的大小。這裡應該是考慮到對於基本數值型別進行 protobuf 編碼後最多佔用10個位元組，因此使用這種方式來更高效的進行記憶體操作。
MMBuffer 中包含一個聯合體，其中的兩個結構體共用儲存空間，在實際使用時只能使用其中的一個。在預設情況下，編譯器會對 MMBuffer 進行記憶體對齊，新增了 7 個填充位元組，以保證 size 和 ptr 成員都按照 8 位元組對齊。而對於第二個結構體，由於其成員都是 1 位元組大小，因此沒有進行記憶體對齊，沒有填充位元組。其記憶體佈局如下：
+--------------------+------------------------+---------------+--------------+
| isNoCopy(1 byte) | padding(7 bytes) | size(8 bytes) | ptr(8 bytes) |
+--------------------+------------------------+---------------+--------------+
+--------------------+----------------------------+
| paddedSize(1 byte) | paddedBuffer(10 bytes) |
+--------------------+----------------------------+
class MMBuffer {
enum MMBufferType : uint8_t {
MMBufferType_Small, // store small buffer in stack memory
MMBufferType_Normal, // store in heap memory
};
MMBufferType type;
union {
struct {
MMBufferCopyFlag isNoCopy;
size_t size;
void *ptr;
};
struct {
uint8_t paddedSize;
// make at least 10 bytes to hold all primitive types (negative int32, int64, double etc) on 32 bit device
// on 64 bit device it's guaranteed larger than 10 bytes
uint8_t paddedBuffer[10];
};
};
static constexpr size_t SmallBufferSize() {
return sizeof(MMBuffer) - offsetof(MMBuffer, paddedBuffer);
}
public:
explicit MMBuffer(size_t length = 0);
MMBuffer(void *source, size_t length, MMBufferCopyFlag flag = MMBufferCopy);
MMBuffer(MMBuffer &&other) noexcept;
~MMBuffer();
bool isStoredOnStack() const { return (type == MMBufferType_Small); }
void *getPtr() const { return isStoredOnStack() ? (void *) paddedBuffer : ptr; }
size_t length() const { return isStoredOnStack() ? paddedSize : size; }
};
int型別資料寫入
寫入的 value 為 int 型別時，計算 value 透過 protobuf 編碼需要佔用多少個位元組，並將其編碼後的結果寫入到分配的記憶體段中。
// MMKV.cpp#set
bool MMKV::set(int32_t value, MMKVKey_t key) {
if (isKeyEmpty(key)) {
return false;
}
// 根據 protobuf 編碼規則，獲取 value 透過 protobuf 編碼需要佔用幾個位元組
size_t size = pbInt32Size(value);
// 宣告 MMBuffer，其為 MMKV 中定義的記憶體單元，儲存了對映的指標和大小
MMBuffer data(size);
// 將 MMBuffer 的 ptr 與 CodedOutputData 關聯在一起，
// 則 CodedOutputData 寫入資料後，透過 MMBuffer 也能獲取得到
CodedOutputData output(data.getPtr(), size);
// CodedOutputData 主要負責 protobuf 的編碼邏輯，
output.writeInt32(value);
return setDataForKey(move(data), key);
}
setDataForKey
對 value 進行 protobuf 編碼後，將資料寫入到檔案尾部，同時還需要更新 dic 中的內容，以便為後續快速讀取資料服務。
查詢 dic 中是否已存在要寫入 key 相關的 key-value 對。
- 當 dic 中存在這個 key，直接使用 dic 中儲存的 KeyValueHolder 使用。在
doAppendDataWithKey流程將 key 寫入檔案時複製 KeyValueHolder 指向的 key 資料塊。這個分支走向決定了doAppendDataWithKey中isKeyEncoded為 true。 - 當 dic 中沒有這個 key 時，
doAppendDataWithKey中isKeyEncoded為 false，在寫入檔案時需要寫入 keyLength，再寫入 key。
// MMKV_IO.cpp#setDataForKey
auto itr = m_dic->find(key);
//
if (itr != m_dic->end()) {
auto ret = appendDataWithKey(data, itr->second, isDataHolder);
if (!ret.first) {
return false;
}
itr->second = std::move(ret.second);
} else {
auto ret = appendDataWithKey(data, key, isDataHolder);
if (!ret.first) {
return false;
}
m_dic->emplace(key, std::move(ret.second));
}
appendDataWithKey
根據 setDataForKey 的邏輯分支，appendDataWithKey 也有兩種邏輯，主要區別在於構造 key 的 MMBuffer 方式不一樣。
- 當 dic 中存有相關 key，對應的 MMBuffer 將 protobuf 編碼的 keyLength 計算在內
- 當 dic 中沒有相關 key，對應的 MMBuffer 長度即為 key 的長度大小
// MMKV_IO.cpp#appendDataWithKey
// dic 中已有相關 key 的邏輯分支
KVHolderRet_t MMKV::appendDataWithKey(const MMBuffer &data, const KeyValueHolder &kvHolder, bool isDataHolder) {
SCOPED_LOCK(m_exclusiveProcessLock);
uint32_t keyLength = kvHolder.keySize;
// size needed to encode the key
size_t rawKeySize = keyLength + pbRawVarint32Size(keyLength);
//
// ensureMemorySize() might change kvHolder.offset, so have to do it early
{
auto valueLength = static_cast<uint32_t>(data.length());
if (isDataHolder) {
valueLength += pbRawVarint32Size(valueLength);
}
auto size = rawKeySize + valueLength + pbRawVarint32Size(valueLength);
// ensureMemorySize 確保有足夠的空間大小以供這次寫入，內部邏輯比較複雜，
// 這裡簡單記住當申請的 mmap 空間不夠時會嘗試擴容
bool hasEnoughSize = ensureMemorySize(size);
if (!hasEnoughSize) {
return make_pair(false, KeyValueHolder());
}
}
auto basePtr = (uint8_t *) m_file->getMemory() + Fixed32Size;
MMBuffer keyData(basePtr + kvHolder.offset, rawKeySize, MMBufferNoCopy);
return doAppendDataWithKey(data, keyData, isDataHolder, keyLength);
}
// dic 中沒有相關 key 的邏輯分支
KVHolderRet_t MMKV::appendDataWithKey(const MMBuffer &data, MMKVKey_t key, bool isDataHolder) {
auto keyData = MMBuffer((void *) key.data(), key.size(), MMBufferNoCopy);
return doAppendDataWithKey(data, keyData, isDataHolder, static_cast<uint32_t>(keyData.length()));
}
doAppendDataWithKey
實際將 key-value 對進行寫入的地方。這裡需要先了解兩個欄位代表的含義，否則對於寫入流程可能並不會太過清晰。
isDataHolder
isDataHolder 的取值從 setDataForKey 一路傳下來，這裡看下其函式定義，對於 isDataHolder 預設取值為 false。
bool setDataForKey(mmkv::MMBuffer &&data, MMKVKey_t key, bool isDataHolder = false);
資料型別為 string/char* 時，才進行了 true 的賦值。而當 isDataHolder 為 true 時，對 value 的寫入會再額外寫入一個欄位，表示 valueLength。在Github Discussion 中的討論，作者解釋是為了在寫入 string 列表中使用的，而為了程式碼的統一性就沒有再進行區分了。
isKeyEncoded
透過原始 key 長度和將 key 封裝為 MMBuffer 的 length 做比較來判斷是否已經包含 keyLength 的 protobuf 編碼值。實際上在 MMKV_IO.cpp#setDataForKey 中根據 dic 是否存在寫入的 key 就決定了 isKeyEncoded 的值，當 dic 中存在寫入的 key 時，isKeyEncoded 為 true，表示寫入時不需要再將 keyLength 的 protobuf 編碼資料寫入。
+-----------+-----+
| keyLength | key |
+-----------+-----+
這樣做的原因上面其實也提及過，對於 key 的寫入其格式如上。當 dic 中存有這個 key，那麼說明初始 loadFromFile 或在此之前已經構造了相關的 KeyValueHolder 資訊。透過 KeyValueHolder 拿到 offset 資料後，offset 後面的一段記憶體區資料即為 key 寫入所需的格式資料。
// MMKV_IO.cpp#doAppendDataWithKey
KVHolderRet_t
MMKV::doAppendDataWithKey(const MMBuffer &data, const MMBuffer &keyData, bool isDataHolder, uint32_t originKeyLength) {
auto isKeyEncoded = (originKeyLength < keyData.length());
auto keyLength = static_cast<uint32_t>(keyData.length());
auto valueLength = static_cast<uint32_t>(data.length());
if (isDataHolder) {
valueLength += pbRawVarint32Size(valueLength);
}
// size needed to encode the key
size_t size = isKeyEncoded ? keyLength : (keyLength + pbRawVarint32Size(keyLength));
// size needed to encode the value
size += valueLength + pbRawVarint32Size(valueLength);
SCOPED_LOCK(m_exclusiveProcessLock);
bool hasEnoughSize = ensureMemorySize(size);
if (!hasEnoughSize || !isFileValid()) {
return make_pair(false, KeyValueHolder());
}
try {
// 仍然是區分 key 是否已經編碼過了
if (isKeyEncoded) {
// 直接將 MMBuffer 的資料複製寫入
m_output->writeRawData(keyData);
} else {
// 寫入 protobuf 編碼的 keyLength，再寫入 key 的值
m_output->writeData(keyData);
}
if (isDataHolder) {
m_output->writeRawVarint32((int32_t) valueLength);
}
m_output->writeData(data); // note: write size of data
} catch (std::exception &e) {
MMKVError("%s", e.what());
return make_pair(false, KeyValueHolder());
}
auto offset = static_cast<uint32_t>(m_actualSize);
auto ptr = (uint8_t *) m_file->getMemory() + Fixed32Size + m_actualSize;
m_actualSize += size;
updateCRCDigest(ptr, size);
return make_pair(true, KeyValueHolder(originKeyLength, valueLength, offset));
}
int 型別資料讀取
資料讀取內容相對簡單點，根據要獲取的資料 key，從 dic 中獲取到相應的 KeyValueHolder，並將其轉換為 MMBuffer 記憶體單元，讀取出對映的指標地址開始的資料。
int32_t MMKV::getInt32(MMKVKey_t key, int32_t defaultValue, bool *hasValue) {
if (isKeyEmpty(key)) {
if (hasValue != nullptr) {
*hasValue = false;
}
return defaultValue;
}
SCOPED_LOCK(m_lock);
SCOPED_LOCK(m_sharedProcessLock);
// 從 dic 中獲取資料
auto data = getDataForKey(key);
if (data.length() > 0) {
try {
CodedInputData input(data.getPtr(), data.length());
if (hasValue != nullptr) {
*hasValue = true;
}
return input.readInt32();
} catch (std::exception &exception) {
MMKVError("%s", exception.what());
}
}
if (hasValue != nullptr) {
*hasValue = false;
}
return defaultValue;
}
MMBuffer MMKV::getDataForKey(MMKVKey_t key) {
checkLoadData();
{
auto itr = m_dic->find(key);
if (itr != m_dic->end()) {
auto basePtr = (uint8_t *) (m_file->getMemory()) + Fixed32Size;
// 拿到 KeyValueHolder 資訊，將其轉換為 MMBuffer 資料格式
return itr->second.toMMBuffer(basePtr);
}
}
MMBuffer nan;
return nan;
}
缺陷
- 沒有型別資訊，不支援 getAll
MMKV的儲存使用 Protobuf 的編碼方式，只儲存 key 和 value 本身，沒有存型別資訊。由於沒有記錄型別資訊，MMKV無法自動反序列化，也就無法實現 getAll 介面，因此在需要遍歷所有 key-value 的時候（比如遷移資料）就比較棘手了。 - 檔案大小問題
擴容後如果進行 key-value 的刪除不會主動 trim size