介绍

MMKV is an efficient, small, easy-to-use mobile key-value storage framework used in the WeChat application. It’s currently available on Android, iOS/macOS, Win32 and POSIX.

作为一个精简易用且性能强悍的全平台 K-V 存储框架,MMKV 有如下特点:

  • 高效
    • 利用 mmap 直接将文件映射到内存;
    • 利用 protobuf 对键值进行编解码压缩;
    • 多进程并发;
  • 易用:无需手动 synchronize 和配置,全程自动同步;
  • 精简.
    • 少量的文件: 仅包括了编解码工具类和 mmap 逻辑代码,无冗余依赖;
    • 二进制文件仅小于 30K: 如为 ipa 文件则会更小;

具体性能,微信团队提供了简单的 benchmark。总之就是秒杀苹果的 NSUserDefaults,性能差异达 100 多倍。

说明,现在大家看到的这篇文章是重写的 2.0 版本。就在前不久,MMKV 悄摸地发布了主版本更新 v1.1.0,而原有的实现已面目全非 💔,原因详见

We refactor the whole MMKV project and unify the cross-platform Core library. From now on, MMKV on iOS/macOS, Android, Win32 all share the same core logic code.

另,本篇涉及大量 C++ 实现,如果描述有误望及时指出。

准备工作

在开始之前,我们需要了解几个概念,熟悉的同学可 pass。

mmap

mmap是一种内存映射文件的方法,即将一个文件或者其它对象映射到进程的地址空间,实现文件磁盘地址和进程虚拟地址空间中一段虚拟地址的一一对映关系。实现这样的映射关系后,进程就可以采用指针的方式读写操作这一段内存,而系统会自动回写脏页面到对应的文件磁盘上,即完成了对文件的操作而不必再调用read,write等系统调用函数。相反,内核空间对这段区域的修改也直接反映用户空间,从而可以实现不同进程间的文件共享。

通常,我们的文件读写操作需要页缓存作为内核和应用层的中转。因此,一次文件操作需要两次数据拷贝(内核到页缓存,页缓存到应用层),而 mmap 实现了用户空间和内核空间数据的直接交互而省去了页缓存。当然有利也有弊,如 苹果文档 所述,想高效使用 mmap 需要符合以下场景:

  • You have a large file whose contents you want to access randomly one or more times.
  • You have a small file whose contents you want to read into memory all at once and access frequently. This technique is best for files that are no more than a few virtual memory pages in size.
  • You want to cache specific portions of a file in memory. File mapping eliminates the need to cache the data at all, which leaves more room in the system disk caches for other data.

因此,当我们需要高频率的访问某一较大文件中的一小部分内容的时候,mmap 的效率是最高的。

其实不光是 MMKV 包括微信的 XLog 和 美团的 Logan 日志工具,还有 SQLight 都使用 mmap 来提升高频更新场景下的文件访问效率。

Protocol Buffer

Protobuf is a method of serializing structured data. It is useful in developing programs to communicate with each other over a wire or for storing data. The method involves an interface description language that describes the structure of some data and a program that generates source code from that description for generating or parsing a stream of bytes that represents the structured data.

Protobuf 是一种将结构化数据进行序列化的方法。它最初是为了解决服务器端新旧协议(高低版本)兼容性问题而诞生的。因此,称为“协议缓冲区”,只不过后期慢慢发展成用于传输数据和存储等。

MMKV 正是考虑到了 protobuf 在性能和空间上的不错表现,以简化版 protobuf 作为序列化方案,还扩展了 protobuf 的增量更新的能力,将 K-V 对象序列化后,直接 append 到内存末尾进行序列化。

那 Protobuf 是如何实现高效编码?

  1. Tag - Value (Tag - Length - Value)的编码方式的实现。减少了分隔符的使用,数据存储更加紧凑;
  2. 利用 base 128 varint (变长编码)原理压缩数据以后,二进制数据非常紧凑,pb 体积更小。不过 pb 并没有压缩到极限,float、double 浮点型都没有压缩;
  3. 相比 JSON 和 XML 少了 {、}、: 这些符号,体积也减少一些。再加上 varint、gzip 压缩以后体积更小。

CRC 校验

循环冗余校验(Cyclic redundancy check)是一种根据网络数据包或计算机文件等数据产生简短固定位数校验码的一种散列函数,主要用来检测或校验数据传输或者保存后可能出现的错误。生成的数字在传输或者存储之前计算出来并且附加到数据后面,然后接收方进行检验确定数据是否发生变化。

同样是用于计算校验值,相比 MD5 或者 SHA1,CRC 的计算效率较高,安全性较弱。考虑到文件系统、操作系统都有一定的不稳定性,MMKV 增加了 CRC 校验,对无效数据进行甄别。

在 iOS 微信现网环境上,有平均约 70万日次的数据校验不通过。

初始化

在 v1.1.0 版本 Tencent 团队重写了整个 MMVK 项目,统一跨平台核心库。自此 MMKV 在 iOS/macOS, Android, Win32 共享同一份核心逻辑。在一定程度上提高了可维护性,以及优势共享。也正是由于这一点,在 iOS/macOS 上可以实现 Multi-Process Access

在代码结构上,MMKV 独立出单独的 MMVKCore,Apple 平台基于 MMKV Core 做了一层 Objc 的封装。

MMVK Core.png

原有的实现基本都迁移到 MMKV Core 中并替换成了 C++ 实现。对不同平台的所独有的 API 或逻辑通过不同的文件名和宏来隔离。以 MemoryFile 为例:

1MemoryFile.h
2MemoryFile.cpp
3MemoryFile_Android.cpp
4MemoryFile_OSX.cpp
5MemoryFile_Win32.cpp

本篇我们重点关注 Apple 相关逻辑。

Class Initialize

MMKV 在使用前的准备工作分成两个阶段:

  1. 初始化 g_instanceDic 等静态变量。它在应用启动时的 pre_main 函数前,在 MMKV class 的 + initialize 里完成的。
  2. 需要用户手动执行 +initializeMMKV 来完成 g_basePath 的指定,即 MMKV 的根目录。
 1+ (void)initialize {
 2    if (self == MMKV.class) {
 3        g_instanceDic = [[NSMutableDictionary alloc] init];
 4        g_lock = new mmkv::ThreadLock();
 5        g_lock->initialize();
 6
 7        mmkv::MMKV::minimalInit([self mmkvBasePath].UTF8String);
 8        
 9        /* 注册启动通知 */ 
10    }
11}

在类的初始化中,做了四件事情:

  • g_instanceDic :全局 MMKV 实例的容器,key 由多个字段混合生成的,后面会说明;
  • g_lock : 为 g_instanceDic 配了把线程锁;
  • minimalInit:以 MMKV 默认的根目录 (~/Document/mmkv) ,初始化 MMKV Core 中的全局变量;
  • 注册 App 生命周期相关的通知 (仅 iOS 应用主体)

这里之前有不明白之处,就是为什么这里没有使用 dispatch_once 来保证不可重入呢?

当翻看该文件的 history 时,发现早期版本确实用到了 dispatch_once 来避免重入。而现在换成这种写法难道是

用了什么新特性吗?

我们知道 +initialize 是有可能被多次调用的,但是对其如何被多次调用,被谁多次调用,这里理解有误。

以 MMKV 为例,假设我们声明 MMKVTest 作为其 MMKV 的子类,但未实现 +initialize 或者 MMKVTest 在其 +initialize 中显式的调用 [super initialize] 方法,那么 MMKV 的 +initialize 才会被调用多次。

但是忽略了很重要的一点,+initialize 是 class method,完全可以通过判断 class 类型来避免重入。这也是第一行判断 self == MMKV.class 的重要性和作用。

MinimalInit

protect from some old code that don’t call initializeMMKV()

为了确保相关属性访问时已初始化完成,在类初始化时需要提前备好全局变量。

 1void MMKV::minimalInit(MMKVPath_t defaultRootDir) {
 2    ThreadLock::ThreadOnce(&once_control, initialize);
 3
 4    int device = 0, version = 0;
 5    GetAppleMachineInfo(device, version);
 6#    ifdef __aarch64__
 7    if ((device == iPhone && version >= 9) || (device == iPad && version >= 7)) {
 8        CRC32 = mmkv::armv8_crc32;
 9    }
10#    endif
11
12    g_rootDir = defaultRootDir;
13    mkPath(g_rootDir);
14}

该方法以最低限度把必须要完成的事情放到了应用的启动前,主要三件事:

  1. 执行 initialize 完成全局变量的 init。
  2. 确定 CRC 校验的算法;
  3. 生成 mmkv 根目录;

Initialize

ThreadLock::ThreadOnce 背后以 pthread_once 来保证单词调用,以完成 initialize(),最后用 g_rootDir 创建对应的文件目录。来看私有的 initialize 方法做了啥:

1void initialize() {
2    g_instanceDic = new unordered_map<string, MMKV *>;
3    g_instanceLock = new ThreadLock();
4    g_instanceLock->initialize();
5
6    mmkv::DEFAULT_MMAP_SIZE = mmkv::getPageSize();
7}

在 MMKV Core 实现中也维护了 g_instanceDicg_instanceLock 。看到这不太理解,那在 iOS / MacOS 端为何仍旧保留了这两 ?求告知。

1static NSMutableDictionary *g_instanceDic = nil;
2static mmkv::ThreadLock *g_lock;

CRC32

该方法用于获取文件的 digest 校验值。

1typedef uint32_t (*CRC32_Func_t)(uint32_t crc, const unsigned char *buf, size_t len);
2extern CRC32_Func_t CRC32;

这里的 CRC32 就是正儿八经的函数指针,默认指向的是:

1static inline uint32_t _crc32Wrap(uint32_t crc, const unsigned char *buf, size_t len) {
2    return static_cast<uint32_t>(::crc32(crc, buf, static_cast<uInt>(len)));
3}

不过这里作者做了优化,当 CPU 架构为 aarch64,则改换了 mmkv::armv8_crc32 的实现。由于 crc32 指令需要A10芯片,也就是 iPhone 7 或 iPad 的第六代。因此,这个通过 GetAppleMachineInfo 获取设备和系统版本来判断。

最后一步,获取内存页的大小用于后续文件存取时计算所需内存,并存入 DEFAULT_MMAP_SIZE

注册通知

MMKV 在 Core/MMKVPredef.h 定义了各个平台的宏,这里只在 iOS 应用主体注册了 Notification:

1#if defined(MMKV_IOS) && !defined(MMKV_IOS_EXTENSION)
2if ([[[NSBundle mainBundle] bundlePath] hasSuffix:@".appex"]) {
3     g_isRunningInAppExtension = YES;
4}

这里由于担心遗漏对 MMKV_IOS_EXTENSION 的判断,故此添加了 g_isRunningInAppExtension 静态变量;

注册的两个 Notification 的方法为:didEnterBackgrounddidBecomeActive,用于监听 UIApplicationState 在前后台的状态变化。在注册通知时,也会获取了当前 applicationState 并通过方法:

1void MMKV::setIsInBackground(bool isInBackground)

来更新 g_isInBackground。这么做是为了保证在后台时能够安全的执行文件写入。

InitializeMMKV

真正使用前还需要手动调用一次 +initializeMMKV: logLevel: 或其相关 convene method。

方法内部使用 static BOOL g_hasCalledInitializeMMKV 来防止被多次调用:

1if (g_hasCalledInitializeMMKV) {
2    MMKVWarning("already called +initializeMMKV before, ignore this request");
3    return [self mmkvBasePath];
4}
5g_hasCalledInitializeMMKV = YES;

initializeMMKV: 第一个参数为 rootDir 用于更新 g_basePath,为空的话就用默认值。接着传入 logLevel,执行 MMKV Core 提供的初始化方法:

1void MMKV::initializeMMKV(const MMKVPath_t &rootDir, MMKVLogLevel logLevel) {
2    g_currentLogLevel = logLevel;
3
4    ThreadLock::ThreadOnce(&once_control, initialize);
5
6    g_rootDir = rootDir;
7    mkPath(g_rootDir);
8}

这里同样也调用了 ThreadLock::ThreadOnce 保证 MMKV Core 能够成功初始化。

在 1.1 版本中,由于底层实现的统一,iOS 端可以支持多进程调用,这里多出来一个控制参数,对应的方法为:

+initializeMMKV: groupDir: logLevel:。内部也是走上面的方法,不过多出来一个全局变量:

1g_groupPath = [groupDir stringByAppendingPathComponent:@"mmkv"];

Instance Initialize

mmkvWithID

获取实例 MMKV 同样提供了多个 convince method,最终收口的私有类方法如下:

1+ (instancetype)mmkvWithID:(NSString *)mmapID 
2                  cryptKey:(NSData *)cryptKey
3              relativePath:(nullable NSString *)relativePath 
4                      mode:(MMKVMode)mode

注意,正式因为 relativePath 和 mode 是互斥的,不能同时设置,这才作为私有方法。那就一探究竟吧。

首先,会检查 g_hasCalledInitializeMMKV 是否执行过 +initializeMMKV: 以及 mmapID 是否有效。

上锁 SCOPED_LOCK(g_lock)之后,接着就是处理 relativePath 和 mode 的问题了:

1if (mode == MMKVMultiProcess) {
2    if (!relativePath) {
3        relativePath = g_groupPath;
4    }
5    if (!relativePath) {
6        MMKVError("Getting a multi-process MMKV [%@] without setting groupDir makes no sense", mmapID);
7        MMKV_ASSERT(0);
8    }
9}

g_groupPath 本身是服务于 multi-process 的,对于单进程而言 g_groupPath 值自然为 nil,也就不会有冲突一说。上述逻辑做的事情也比较清晰,就是在 multi-process 下,会将 relativePath 覆盖,并保证起不能为空。

至于为何不能为空?MMKVError 中已经做了很明确的说明了。

初始化 MMKV 实例

 1NSString *kvKey = [MMKV mmapKeyWithMMapID:mmapID relativePath:relativePath];
 2MMKV *kv = [g_instanceDic objectForKey:kvKey];
 3if (kv == nil) {
 4    kv = [[MMKV alloc] initWithMMapID:mmapID cryptKey:cryptKey relativePath:relativePath mode:mode];
 5    if (!kv->m_mmkv) {
 6        return nil;
 7    }
 8    kv->m_mmapKey = kvKey;
 9    [g_instanceDic setObject:kv forKey:kvKey];
10}

首先,通过 mmapID 和 relativePath 来生成 kvKey,用于关联生成的 mmkv 实例,最终存储在 g_instanceDic 中。如果 relativePath 为有效字符串,key 值为 relativePath 和 mmapID 拼接后的的 md5 值。

接着,尝试通过 key 来获取实例。没有的话就需要进行初始化,并将 mmkv 实例保存到 g_instanceDic

这里每个实例本身也会将 key 保存在 m_mmapKey 中,以待其结束时,将自身从 g_instanceDic 中移除。

initWithMMapID

通过 MMKV Core 的 mmkv::MMKV::mmkvWithID 方法来获取 m_mmkv 实例。参数就是将 mmapID、cryptKey、relativePath 转为 c string 传入。

同类的初始化一样,MMKV Core 构造函数的实现与 iOS 侧无异,只是用 C++ 的方式再做了一遍。这里除了对 variable 进行默认值的赋值之外,最终调用 loadFromFile() 来加载 mmkv 文件和 CRC 文体。MMKV 的构造函数完整实现就不贴出来了,简单看一下声明吧:

1#ifndef MMKV_ANDROID
2    MMKV(const std::string &mmapID, MMKVMode mode, std::string *cryptKey, MMKVPath_t *relativePath);
3    std::string m_mmapKey;
4#else // defined(MMKV_ANDROID)
5    MMKV(const std::string &mmapID, int size, MMKVMode mode, std::string *cryptKey, MMKVPath_t *relativePath);
6
7    MMKV(const std::string &mmapID, int ashmemFD, int ashmemMetaFd, std::string *cryptKey = nullptr);
8#endif

Data Structure

本节,会稍微介绍一下 MMKV 中用到的相关数据结构和一些变量。对主要数据结构有基本了解后,在解释实现时我们更能够 Focus 在核心逻辑。

先来看 MMKV 的实例变量:

 1mmkv::MMKVMap m_dic; /// 保存当前映射到内存的 k-v 
 2std::string m_mmapID;
 3MMKVPath_t m_path; // mmkv path
 4MMKVPath_t m_crcPath; // crc file path
 5
 6mmkv::MemoryFile *m_file; // mmap 映射真实数据文件的相关信息,包括 file descrpitot 等
 7size_t m_actualSize; //当前 k-v 占用内存大小
 8mmkv::CodedOutputData *m_output; // 映射内存所剩余空间
 9
10bool m_needLoadFromFile; // 标记是否需要重新载入 m_file
11bool m_hasFullWriteback; // 是否需要执行写回,例如 m_file 读取失败,内存异常等等
12
13uint32_t m_crcDigest;
14mmkv::MemoryFile *m_metaFile; // mmap 映射 crc 文件的相关信息,包括 file descrpitot etc.
15mmkv::MMKVMetaInfo *m_metaInfo; // 保存了 crc 文件的 digest 和 size etc.
16
17mmkv::AESCrypt *m_crypter; // 加密器,文件内容更新后会重新计算加密值
18
19mmkv::ThreadLock *m_lock; // k-v 文件锁
20mmkv::FileLock *m_fileLock; // crc 文件锁
21mmkv::InterProcessLock *m_sharedProcessLock; // 读锁
22mmkv::InterProcessLock *m_exclusiveProcessLock; // 写锁

上述变量会在 MMKV 构造函数调用时完成 initialize。

MMKVMap

首先是 MMKVMap,它区分了 Apple 系和其他系统。如果是 Apple 系,则使用 NSString 为 key,value 不仅是 MMBuffer 类型,需要实现 KeyHasher 和 KeyEqualer 协议,毕竟 unordered_map 是 C++ 泛型。

 1struct KeyHasher {
 2    size_t operator()(NSString *key) const { return key.hash; }
 3};
 4
 5struct KeyEqualer {
 6    bool operator()(NSString *left, NSString *right) const { /* left isEqual right */ }
 7};
 8#ifdef MMKV_APPLE
 9using MMKVMap = std::unordered_map<NSString *, mmkv::MMBuffer, KeyHasher, KeyEqualer>;
10#else
11using MMKVMap = std::unordered_map<std::string, mmkv::MMBuffer>;
12#endif

注意,在我们的 m_dic 中存储的数据类型是 MMBuffer 而非真实数据类型。只有当我们通过 Access 访问的时候才会 encode / decode 出来。

MMKVKey_t

1#ifdef MMKV_APPLE
2    using MMKVKey_t = NSString *__unsafe_unretained;
3    static bool isKeyEmpty(MMKVKey_t key) { return key.length <= 0; }
4#else
5    using MMKVKey_t = const std::string &;
6    static bool isKeyEmpty(MMKVKey_t key) { return key.empty(); }
7#endif

注意,整个 MMKV Core 的源码中,应该只有 MMKV.cpp 这个文件是以 MRC 的方式进行内存管理的,其他的 C++ 类则使用了 ARC,可以查看 MMKVCore.podspec:

1s.requires_arc = ['Core/MemoryFile.cpp', ...]

这里并未发现包含了 MMKV.cpp 文件,后续代码中会说明。

MMKVPath_t

1using MMKVPath_t = std::string;

MemoryFile

 1class MemoryFile {
 2    MMKVPath_t m_name;
 3    MMKVFileHandle_t m_fd; // file descriptior (不同平台有所差异)
 4#ifdef MMKV_WIN32
 5    HANDLE m_fileMapping;
 6#endif
 7    void *m_ptr; // 指向 mmap 内存的起始地址
 8    size_t m_size; // 表示的是文件按照内存整数页截断后的 size。
 9
10    bool mmap();
11    void doCleanMemoryCache(bool forceClean);
12public:
13#ifndef MMKV_ANDROID
14    explicit MemoryFile(const MMKVPath_t &path);
15#else
16    MemoryFile(const MMKVPath_t &path, size_t size, FileType fileType);
17    explicit MemoryFile(MMKVFileHandle_t ashmemFD);
18
19    const FileType m_fileType;
20#endif // MMKV_ANDROID
21    
22   /* methods ... */
23}

MMKV 之所以高效就是源自 mmap,正是 MemoryFile 封装了 mmap、mumap、msync 等。

非安卓平台构造函数只需 filePath,其余变量均通过 reloadFromFile() 来获取。这里多说一嘴 FileType:

1enum FileType : bool { MMFILE_TYPE_FILE = false, MMFILE_TYPE_ASHMEM = true };

MMFILE_TYPE_ASHMEM 指 Android 中所独有的匿名共享内存方式 ASharedMemory,本质也是 mmap 哈。

reloadFromFile

 1void MemoryFile::reloadFromFile() {
 2#    ifdef MMKV_ANDROID
 3    if (m_fileType == MMFILE_TYPE_ASHMEM) {
 4        return;
 5    }
 6#    endif
 7    if (isFileValid()) {
 8        MMKVWarning("calling reloadFromFile while the cache [%s] is still valid", m_name.c_str());
 9        MMKV_ASSERT(0);
10        clearMemoryCache();
11    }
12
13    m_fd = open(m_name.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, S_IRWXU);
14    if (m_fd < 0) {
15        MMKVError("fail to open:%s, %s", m_name.c_str(), strerror(errno));
16    } else {
17        FileLock fileLock(m_fd);
18        InterProcessLock lock(&fileLock, ExclusiveLockType);
19        SCOPED_LOCK(&lock);
20
21        mmkv::getFileSize(m_fd, m_size);
22        // round up to (n * pagesize)
23        if (m_size < DEFAULT_MMAP_SIZE || (m_size % DEFAULT_MMAP_SIZE != 0)) {
24            size_t roundSize = ((m_size / DEFAULT_MMAP_SIZE) + 1) * DEFAULT_MMAP_SIZE;
25            truncate(roundSize);
26        } else {
27            auto ret = mmap();
28            if (!ret) {
29                doCleanMemoryCache(true);
30            }
31        }
32#    ifdef MMKV_IOS
33        tryResetFileProtection(m_name);
34#    endif
35    }
36}

第一步就是判断 m_fileType,如果为 MMFILE_TYPE_ASHMEM 则直接 return 以通过 ASharedMemory_create 来完成内存映射。

接着判断 fd 是否指向有效内存:

1#ifndef MMKV_WIN32
2    bool isFileValid() { return m_fd >= 0 && m_size > 0 && m_ptr; }
3#else
4    bool isFileValid() { return m_fd != INVALID_HANDLE_VALUE && m_size > 0 && m_fileMapping && m_ptr; }
5#endif

如果有效,则会执行 MemoryFile::clearMemoryCache() ,内部先调用 mumap(m_ptr, m_size) 清理内存缓存,再关闭文件访问 close(m_fd) 还原 m_fdm_size

在 mmap 前会有一个内存取整的检查,以保证所映射的数据是内存页 DEFAULT_MMAP_SIZE 的整数倍,以减少内存碎片。

最后,在 iOS 上会调整文件的读写保护,前面在注册通知中提到过,为了确保应用在后台时能安全的进行文件访问,而不至于被系统错杀 ⚠️。

truncate

内存区取整。

 1bool MemoryFile::truncate(size_t size) {
 2    if (m_fd < 0) {
 3        return false;
 4    }
 5    if (size == m_size) {
 6        return true;
 7    }
 8#    ifdef MMKV_ANDROID
 9        ...
10#    endif // MMKV_ANDROID
11
12    auto oldSize = m_size;
13    m_size = size;
14    // round up to (n * pagesize)
15    if (m_size < DEFAULT_MMAP_SIZE || (m_size % DEFAULT_MMAP_SIZE != 0)) {
16        m_size = ((m_size / DEFAULT_MMAP_SIZE) + 1) * DEFAULT_MMAP_SIZE;
17    }
18
19    if (::ftruncate(m_fd, static_cast<off_t>(m_size)) != 0) {
20        MMKVError("fail to truncate [%s] to size %zu, %s", m_name.c_str(), m_size, strerror(errno));
21        m_size = oldSize;
22        return false;
23    }
24    if (m_size > oldSize) {
25        if (!zeroFillFile(m_fd, oldSize, m_size - oldSize)) {
26            MMKVError("fail to zeroFile [%s] to size %zu, %s", m_name.c_str(), m_size, strerror(errno));
27            m_size = oldSize;
28            return false;
29        }
30    }
31
32    if (m_ptr) {
33        if (munmap(m_ptr, oldSize) != 0) {
34            MMKVError("fail to munmap [%s], %s", m_name.c_str(), strerror(errno));
35        }
36    }
37    auto ret = mmap();
38    if (!ret) {
39        doCleanMemoryCache(true);
40    }
41    return ret;
42}

为保证 size 准确性,再进行一次 round up to (n * pagesize) 后才进行取整。两步走:

ftruncate + lseek

对文件扩容或裁剪,并将 file offset 更新至当前容量的最后位置。由于 truncate 并不会操作 file offset 所以需要借助 lseek,剩余的部分均用 '\0' 写入。

munmap + mmap

由于 mmap 关联的是 oldSize 的内存,而现在我们调整了 m_size 大小,需要重新绑定文件与内存关系。

MMBuffer

 1class MMBuffer {
 2private:
 3    void *ptr;
 4    size_t size;
 5    MMBufferCopyFlag isNoCopy;
 6#ifdef MMKV_APPLE
 7    NSData *m_data = nil;
 8#endif
 9
10public:
11    explicit MMBuffer(size_t length = 0);
12    MMBuffer(void *source, size_t length, MMBufferCopyFlag flag = MMBufferCopy);
13#ifdef MMKV_APPLE
14    explicit MMBuffer(NSData *data, MMBufferCopyFlag flag = MMBufferCopy);
15#endif
16   // 数据读写方法 ...
17}

就是一段连续的内存地址,在 Apple 上则用 NSData 指向,其他平台则是通过 ptr + size 来引用。

在 MMKV 中不论是从数据写入文件还是从文件中读取,统一转换为 MMBuffer 作为过渡。

CodedOutputData

 1class CodedOutputData {
 2    uint8_t *const m_ptr;
 3    size_t m_size;
 4    size_t m_position;
 5
 6public:
 7    CodedOutputData(void *ptr, size_t len);
 8    size_t spaceLeft();
 9    uint8_t *curWritePointer();
10    void seek(size_t addedSize);
11    void writeRawByte(uint8_t value);
12    /// 其他基本数据类型写入 ...
13}

CodedOutputData

 1class CodedInputData {
 2    uint8_t *const m_ptr;
 3	 size_t m_size;
 4    size_t m_position;
 5
 6    int8_t readRawByte();
 7
 8public:
 9    CodedInputData(const void *oData, size_t length);
10    bool isAtEnd() { return m_position == m_size; };
11    /// 其他基本数据类型读取 ...
12}

CodedInputDataCodedOutputData 主要用于真实数据类型和 MMBuffer 之间转换,关系如下:

1MMBuffer -> Input -> 真实数据 -> output -> MMBuffer

CodedInputData 将 binary Data 从 MMBuffer 中读取出来,转换为真实数据类型;

CodedOutputData 则将真实数据类型转换为 binaryData 输出到 MMBuffer 中;

可见,它们两起到了桥梁的作用,完成了真实数据和 MMBuffer 的相互转换。

InterProcessLock

MMKV 采用文件锁来处理多进程中的文件访问。用排他锁作为写锁,用共享锁作为读锁。 这里没有直接使用系统的 flock 而是用 FileLock 将其封装了一层,读写锁均为 InterProcessLock 本质为 FileLock。

 1class InterProcessLock {
 2    FileLock *m_fileLock;
 3    LockType m_lockType;
 4
 5public:
 6    InterProcessLock(FileLock *fileLock, LockType lockType)
 7        : m_fileLock(fileLock), m_lockType(lockType), m_enable(true) {
 8        MMKV_ASSERT(m_fileLock);
 9    }
10
11    bool m_enable;
12
13    void lock() {
14        if (m_enable) {
15            m_fileLock->lock(m_lockType);
16        }
17    }
18
19    bool try_lock() {
20        if (m_enable) {
21            return m_fileLock->try_lock(m_lockType);
22        }
23        return false;
24    }
25
26    void unlock() {
27        if (m_enable) {
28            m_fileLock->unlock(m_lockType);
29        }
30    }
31};

MMVK.h 中还声明了变量 m_isInterProcess 用于控制锁功能开关。对于支持多进程的 MMKV 而言,m_isInterProcess 代表了当前实例所采用的读写模式:MMKVMode

1enum MMKVMode : uint32_t {
2    MMKV_SINGLE_PROCESS = 0x1,
3    MMKV_MULTI_PROCESS = 0x2,
4#ifdef MMKV_ANDROID
5    CONTEXT_MODE_MULTI_PROCESS = 0x4, // in case someone mistakenly pass Context.MODE_MULTI_PROCESS
6    MMKV_ASHMEM = 0x8,
7#endif
8};

关于锁的,感兴趣的可以看看这篇:flock 文件锁

由于本文篇幅较长,很多描述中忽略了锁相关的细节(其实非常重要的),之后会单独开篇来聊聊。

LoadData

本节主要介绍 MMKV 如何从文件中读取数据、异常数据处理、以及如何利用 CRC 来校验文件的完整性。

在应用首次初始化、数据异常,内存警告、清理数据时都会执行 loadFromFile() 来刷新内存中对应的数据,保证其准确性。整个 m_file 加载主要分三步:

  1. 校验 CRC 文件、m_file 的有效性,初始化 AESCrypter;
  2. 检查文件内部数据的有效性;
  3. 加载数据到内存。

文件有效性

在 MMKV 构造函数执行时,m_metaFile 为本地 crc 文件的内存映射,而 m_metaInfo 则记录了当前内存数据的相关 crc 校验值,默认为空。

 1struct MMKVMetaInfo {
 2    uint32_t m_crcDigest = 0;
 3    uint32_t m_version = MMKVVersionSequence;
 4    uint32_t m_sequence = 0; // full write-back count
 5    unsigned char m_vector[AES_KEY_LEN] = {};
 6    uint32_t m_actualSize = 0;
 7
 8    // confirmed info: it's been synced to file
 9    struct {
10        uint32_t lastActualSize = 0;
11        uint32_t lastCRCDigest = 0;
12        uint32_t __reserved__[16] = {};
13    } m_lastConfirmedMetaInfo;
14
15    void write(void *ptr) {
16        MMKV_ASSERT(ptr);
17        memcpy(ptr, this, sizeof(MMKVMetaInfo));
18    }
19
20    void writeCRCAndActualSizeOnly(void *ptr) {
21        MMKV_ASSERT(ptr);
22        auto other = (MMKVMetaInfo *) ptr;
23        other->m_crcDigest = m_crcDigest;
24        other->m_actualSize = m_actualSize;
25    }
26
27    void read(const void *ptr) {
28        MMKV_ASSERT(ptr);
29        memcpy(this, ptr, sizeof(MMKVMetaInfo));
30    }
31};

因此,MMKV 在加载 m_file 前要将 crc 的校验值载入 m_metaInfo,载入前会确认 crc 完成映射:

1if (m_metaFile->isFileValid()) {
2    m_metaInfo->read(m_metaFile->getMemory());
3}

注意 m_version 表示当前缓存的内容数据的状态,初始值为 MMKVVersionSequence。有以下几种:

1enum MMKVVersion : uint32_t {
2    MMKVVersionDefault = 0,
3    // 记录了完全回写的次数
4    MMKVVersionSequence = 1,
5    // 存储了加密的随机 iv 
6    MMKVVersionRandomIV = 2,
7    // 存储了 actual size、crc checksum, 用于减少文件损坏的情况
8    MMKVVersionActualSize = 3,
9};

AESCrypter

1if (m_crypter) {
2    if (m_metaInfo->m_version >= MMKVVersionRandomIV) {
3        m_crypter->resetIV(m_metaInfo->m_vector, sizeof(m_metaInfo->m_vector));
4    }
5}

MMKV 初始化时,用户如果传入 AES Key,会通过 resetIV 来初始化 AES。

AES 属于块加密且存在多种加密模式,MMKV 中使用的是 CFB-128 模式。该模式需要同时使用 KEY 和 IV 来完成对数据的加密。

关于 AES 的介绍可以看 WiKi,这里只介绍一下 IV 向量的作用。

IV称为初始向量,不同的IV加密后的字符串是不同的,加密和解密需要相同的IV,既然IV看起来和key一样,却还要多一个IV的目的,对于每个块来说,key是不变的,但是只有第一个块的IV是用户提供的,其他块IV都是自动生成。 IV的长度为16字节。超过或者不足,可能实现的库都会进行补齐或截断。但是由于块的长度是16字节,所以一般可以认为需要的IV是16字节。

所以 metaInfo->m_vector 记录的就是 AES 的 IV 向量,其长度 AES_KEY_LEN 为 16。

接着就是 m_file 有效性检查 isFileValid。通过就进入下一阶段,否则尝试 reloadFromFile

数据有效性

整个数据有效性是在 checkDataValid 中完成的,首先是读取 m_actualSize

readActualSize

 1size_t MMKV::readActualSize() {
 2    MMKV_ASSERT(m_file->getMemory());
 3    MMKV_ASSERT(m_metaFile->isFileValid());
 4
 5    uint32_t actualSize = 0;
 6    memcpy(&actualSize, m_file->getMemory(), Fixed32Size);
 7
 8    if (m_metaInfo->m_version >= MMKVVersionActualSize) {
 9        if (m_metaInfo->m_actualSize != actualSize) {
10            MMKVWarning("[%s] actual size %u, meta actual size %u",...);
11        }
12        return m_metaInfo->m_actualSize;
13    } else {
14        return actualSize;
15    }
16}

如果 m_metaInfo 记录了 m_actualSize 将其优先返回。否则以文件记录值为准。这里 actualSize 通过读取 m_file 头部的固定长度 Fixed32Size 的数据。

1constexpr uint32_t LittleEdian32Size = 4;
2
3constexpr uint32_t pbFixed32Size() {
4    return LittleEdian32Size;
5}
6
7constexpr uint32_t Fixed32Size = pbFixed32Size();

其次,确认当前文件所剩余空间是否足够使用。前面提过对于未存储数据的部分默认是以 \0 填充的,因此这里需要将文件大小和真实数据大小进行比较。

 1void MMKV::checkDataValid(bool &loadFromFile, bool &needFullWriteback) {
 2    // try auto recover from last confirmed location
 3    auto fileSize = m_file->getFileSize();
 4    auto checkLastConfirmedInfo = [&] { ... }
 5
 6    m_actualSize = readActualSize();
 7
 8    if (m_actualSize < fileSize && (m_actualSize + Fixed32Size) <= fileSize) {
 9        if (checkFileCRCValid(m_actualSize, m_metaInfo->m_crcDigest)) {
10            loadFromFile = true; /// 数据正确且剩余空间足够
11        } else {
12            checkLastConfirmedInfo();
13
14           if (!loadFromFile) {
15                ⚠️ Handler 3: 数据异常
16            }
17    } else {
18        checkLastConfirmedInfo();
19
20        if (!loadFromFile) {
21            ⚠️ Handler 4: 空间不足
22        }
23    }
24}

如果空间足够,则计算出当前 m_file 真实数据的 crc digest,并与 m_metaInfo 的 m_crcDigest 对比。

 1bool MMKV::checkFileCRCValid(size_t actualSize, uint32_t crcDigest) {
 2    auto ptr = (uint8_t *) m_file->getMemory();
 3    if (ptr) {
 4        m_crcDigest = (uint32_t) CRC32(0, (const uint8_t *) ptr + Fixed32Size, (uint32_t) actualSize);
 5
 6        if (m_crcDigest == crcDigest) {
 7            return true;
 8        }
 9        MMKVError("check crc [%s] fail, crc32:%u, m_crcDigest:%u", ...);
10    }
11    return false;
12}

另,关于 CRC 差错检测能力,移步百科

校验通过就开始 m_file 内容的加载。

checkLastConfirmedInfo

如果数据异常或者空间不足,都会调用 checkLastConfirmedInfo 重新确认 loadFromFile 状态。checkLastConfirmedInfo 为 C++ 中的 lambda 函数,其声明在 checkDataValid 中,具体逻辑如下:

 1if (m_metaInfo->m_version >= MMKVVersionActualSize) {
 2    // downgrade & upgrade support
 3    uint32_t oldStyleActualSize = 0;
 4    memcpy(&oldStyleActualSize, m_file->getMemory(), Fixed32Size);
 5    if (oldStyleActualSize != m_actualSize) {
 6        MMKVWarning("oldStyleActualSize not equal to meta actual size" ...);
 7        if (oldStyleActualSize < fileSize && (oldStyleActualSize + Fixed32Size) <= fileSize) {
 8            if (checkFileCRCValid(oldStyleActualSize, m_metaInfo->m_crcDigest)) { ⚠️ Handler 1
 9                MMKVInfo("looks like [%s] been downgrade & upgrade again" ...);
10                loadFromFile = true;
11                writeActualSize(oldStyleActualSize, m_metaInfo->m_crcDigest, nullptr, KeepSequence);
12                return;
13            }
14        } else {
15            MMKVWarning("oldStyleActualSize greater than file size" ...);
16        }
17    }
18
19    auto lastActualSize = m_metaInfo->m_lastConfirmedMetaInfo.lastActualSize;
20    if (lastActualSize < fileSize && (lastActualSize + Fixed32Size) <= fileSize) {
21        auto lastCRCDigest = m_metaInfo->m_lastConfirmedMetaInfo.lastCRCDigest;
22        if (checkFileCRCValid(lastActualSize, lastCRCDigest)) { ⚠️ Handler 2
23            loadFromFile = true;
24            writeActualSize(lastActualSize, lastCRCDigest, nullptr, KeepSequence);
25        } else {
26            MMKVError("check lastActualSize, lastActualCRC error" ...);
27        }
28    } else {
29        MMKVError("check lastActualSize, file size error" ...);
30    }
31}

在 MMKVMetaInfo 中的 m_lastConfirmedMetaInfo 可能记录了上一次校验过的 metaInfo,而只在 m_version 为 MMKVVersionActualSize 时,m_lastConfirmedMetaInfo 才有数据。故而 check 的前置条件为 >= MMKVVersionActualSize。

检查中有两次恢复正确 metaInfo 的机会:

Handler 1

oldStyleActualSize 记录值为 m_file 的内容数据大小,当其值不等于 m_metaInfo->m_actualSize 时,尝试以 oldStyleActualSize 为准更新 metaInfo 的信息。更新仍然要进行 CRC 校验,通过后将 loadFromFile 标记为 true,调用 writeActualSize 完成 metaInfo 的恢复。

Handler 2

最后一根救命稻草为 m_metaInfo->m_lastConfirmedMetaInfo.lastActualSize。用它再进行一次 Handler 1 的检查。

writeActualSize

用于更新 m_metaInfo 信息,包括 actualSize、crcDigest、IV、lastConfrimInfo。

 1bool MMKV::writeActualSize(size_t size, uint32_t crcDigest, const void *iv, bool increaseSequence) {
 2   // backward compatibility
 3   oldStyleWriteActualSize(size);
 4
 5   if (!m_metaFile->isFileValid()) {
 6       return false;
 7   }
 8
 9   bool needsFullWrite = false;
10   m_actualSize = size;
11   m_metaInfo->m_actualSize = static_cast<uint32_t>(size);
12   m_crcDigest = crcDigest;
13   m_metaInfo->m_crcDigest = crcDigest;
14   if (m_metaInfo->m_version < MMKVVersionSequence) {
15       m_metaInfo->m_version = MMKVVersionSequence;
16       needsFullWrite = true;
17   }
18   if (unlikely(iv)) {
19       memcpy(m_metaInfo->m_vector, iv, sizeof(m_metaInfo->m_vector));
20       if (m_metaInfo->m_version < MMKVVersionRandomIV) {
21           m_metaInfo->m_version = MMKVVersionRandomIV;
22       }
23       needsFullWrite = true;
24   }
25   if (unlikely(increaseSequence)) {
26       m_metaInfo->m_sequence++;
27       m_metaInfo->m_lastConfirmedMetaInfo.lastActualSize = static_cast<uint32_t>(size);
28       m_metaInfo->m_lastConfirmedMetaInfo.lastCRCDigest = crcDigest;
29       if (m_metaInfo->m_version < MMKVVersionActualSize) {
30           m_metaInfo->m_version = MMKVVersionActualSize;
31       }
32       needsFullWrite = true;
33   }
34#ifdef MMKV_IOS
35   return protectFromBackgroundWriting(m_metaFile->getMemory(), sizeof(MMKVMetaInfo), ^{
36     if (unlikely(needsFullWrite)) {
37         m_metaInfo->write(m_metaFile->getMemory());
38     } else {
39         m_metaInfo->writeCRCAndActualSizeOnly(m_metaFile->getMemory());
40     }
41   });
42#else
43   ...
44#endif

前三个参数就不用说了,看最后参数 increaseSequence,类型如下:

1enum : bool {
2    KeepSequence = false,
3    IncreaseSequence = true,
4};

它用于控制是否更新文件的 full write-back count 及 needsFullWrite。needsFullWrite 相当于 dirty bit 的作用,每当 m_version 有更新,都会将 needsFullWrite 标记为 dirty 用于之后的写回更新。

write-back 概念后面会介绍。

checkDataValid

到这里,数据校验的主流程算是介绍完了,我们回到 checkDataValid,补上 checkLastConfirmedInfo 后数据状态依旧错误,loadlFromFile 为 false 的情况。

Handler 3 (标记在👆代码中)

1auto strategic = onMMKVCRCCheckFail(m_mmapID);
2if (strategic == OnErrorRecover) {
3    loadFromFile = true;
4    needFullWriteback = true;
5}
6MMKVInfo("recover strategic for [%s] is %d", m_mmapID.c_str(), strategic);

Handler 4

1auto strategic = onMMKVFileLengthError(m_mmapID);
2if (strategic == OnErrorRecover) {
3    // make sure we don't over read the file
4    m_actualSize = fileSize - Fixed32Size;
5    loadFromFile = true;
6    needFullWriteback = true;
7}
8MMKVInfo("recover strategic for [%s] is %d", m_mmapID.c_str(), strategic);

对于异常的处理策略,MMKV 为我们提供了修改的回调。策略有两种:

1enum MMKVRecoverStrategic : int {
2    OnErrorDiscard = 0,
3    OnErrorRecover,
4};

默认 MMKV 会丢弃当前数据、清空文件和 metaInfo。此时可通过 g_errorHandler 修改:

 1static MMKVRecoverStrategic onMMKVCRCCheckFail(const string &mmapID) {
 2    if (g_errorHandler) {
 3        return g_errorHandler(mmapID, MMKVErrorType::MMKVCRCCheckFail);
 4    }
 5    return OnErrorDiscard;
 6}
 7
 8static MMKVRecoverStrategic onMMKVFileLengthError(const string &mmapID) {
 9    if (g_errorHandler) {
10        return g_errorHandler(mmapID, MMKVErrorType::MMKVFileLength);
11    }
12    return OnErrorDiscard;
13}

数据处理

校验完有效性,依据其结果 loadFromFileneedFullWriteback 值来判定后续操作。简化后的 loadFromFile:

 1void MMKV::loadFromFile() {
 2    /// 1. 文件有效性
 3    /// 2. 数据有效性
 4    ...
 5    bool loadFromFile = false, needFullWriteback = false;
 6    checkDataValid(loadFromFile, needFullWriteback);
 7    ...
 8    auto ptr = (uint8_t *) m_file->getMemory();
 9
10    if (loadFromFile && m_actualSize > 0) {
11       MMKVInfo("loading [%s] with crc %u sequence %u version" ...);
12       // loading    
13    } else {
14       // file not valid or empty, discard everything
15       SCOPED_LOCK(m_exclusiveProcessLock);
16
17       m_output = new CodedOutputData(ptr + Fixed32Size, m_file->getFileSize() - Fixed32Size);
18       if (m_actualSize > 0) {
19           writeActualSize(0, 0, nullptr, IncreaseSequence);
20           sync(MMKV_SYNC);
21       } else {
22           writeActualSize(0, 0, nullptr, KeepSequence);
23       }
24   }
25};

先看异常处理。

当校验失败或文件为空,直接调用 writeActualSize 清理 metaInfo 缓存。

如果文件异常,传入 IncreaseSequence 来设置 dirt bit,以待下次重载 m_file。

Loading

当 loadFromFile 为 true 且文件内容不为空,将数据从内存读入 MMBuffer,进行 AES 解密、清空 m_dic、准备 buffer 数据写入。

 1// loading
 2MMBuffer inputBuffer(ptr + Fixed32Size, m_actualSize, MMBufferNoCopy);
 3if (m_crypter) {
 4    decryptBuffer(*m_crypter, inputBuffer);
 5}
 6clearDictionary(m_dic);
 7if (needFullWriteback) {
 8    MiniPBCoder::greedyDecodeMap(m_dic, inputBuffer);
 9} else {
10    MiniPBCoder::decodeMap(m_dic, inputBuffer);
11}
12m_output = new CodedOutputData(ptr + Fixed32Size, m_file->getFileSize() - Fixed32Size);
13m_output->seek(m_actualSize);
14if (needFullWriteback) {
15    fullWriteback();
16}

数据写入 m_dic 后,创建 CodedOutputData 对象来记录当前映射的内存指针和文件大小,通过 seek 来记录读取的文件位置。

最后,当 needFullWriteback 为 true 时进行文件写回 fullWriteback

写入策略分为贪婪模式和普通两种:

1void MiniPBCoder::decodeMap(MMKVMap &dic, const MMBuffer &oData, size_t size) {
2    MiniPBCoder oCoder(&oData);
3    oCoder.decodeOneMap(dic, size, false);
4}
5
6void MiniPBCoder::greedyDecodeMap(MMKVMap &dic, const MMBuffer &oData, size_t size) {
7    MiniPBCoder oCoder(&oData);
8    oCoder.decodeOneMap(dic, size, true);
9}

区别在于 greed 会将所有 buffer 转成 k-v 保存在 m_dic 中。

在前面的数据校验中可知,仅当校验失败且恢复策略为 OnErrorRecover 会将 needFullWriteback 标记为 ture。就是说,当数据异常或空间不足时,会采用贪婪策略尽可能的将数据优先读入内存。

 1void MiniPBCoder::decodeOneMap(MMKVMap &dic, size_t size, bool greedy) {
 2    auto block = [size, this](MMKVMap &dictionary) {
 3        if (size == 0) {
 4            [[maybe_unused]] auto length = m_inputData->readInt32();
 5        }
 6        while (!m_inputData->isAtEnd()) {
 7            const auto &key = m_inputData->readString();
 8            if (key.length > 0) {
 9                auto value = m_inputData->readData();
10                if (value.length() > 0) {
11                    dictionary[key] = move(value);
12                    [key retain];
13                } else {
14                    auto itr = dictionary.find(key);
15                    if (itr != dictionary.end()) {
16                        dictionary.erase(itr);
17                        [itr->first release];
18                    }
19                }
20            }
21        }
22    };
23
24    if (greedy) {
25        try {
26            block(dic);
27        } catch (std::exception &exception) {
28            MMKVError("%s", exception.what());
29        }
30    } else {
31        try {
32            MMKVMap tmpDic;
33            block(tmpDic);
34            dic.swap(tmpDic);
35            for (auto &pair : tmpDic) {
36                [pair.first release];
37            }
38        } catch (std::exception &exception) {
39            MMKVError("%s", exception.what());
40        }
41    }
42}

fullWriteback

写回 (write-back) 作为缓存策略中的一种,其概念可以查看 wiki,简单描述如下:

仅当一个缓存块需要被替换回内存时,才将其内容写入内存。而为了减少内存写操作,通过脏位标识该块在被载入之后是否发生过更新。如果一个缓存块在被置换回内存之前从未被写入过,则可以免去回写操作。

MMKV 的写回操作就是将内存数据 m_dic 序列化后写回文件。

 1bool MMKV::fullWriteback() {
 2    ...
 3    auto allData = MiniPBCoder::encodeDataWithObject(m_dic);
 4    SCOPED_LOCK(m_exclusiveProcessLock);
 5    if (allData.length() > 0) {
 6        auto fileSize = m_file->getFileSize();
 7        if (allData.length() + Fixed32Size <= fileSize) {
 8            return doFullWriteBack(std::move(allData));
 9        } else {
10            // ensureMemorySize will extend file & full rewrite, no need to write back again
11            return ensureMemorySize(allData.length() + Fixed32Size - fileSize);
12        }
13    }
14    return false;
15}

操作前会检查几个状态:

  • m_hasFullWriteback:直接 return true
  • m_needLoadFromFile:直接 return true
  • isFileValid() 为 false:直接 return false
  • m_dic.empty() :clearAll() 后 return true

既然是数据读取,如果 m_dic 为空,认为数据可能出现异常。将会清理临时数据和内存缓存、重置相关标记位、重新加载文件。

 1void MMKV::clearAll() {
 2    MMKVInfo("cleaning all key-values from [%s]", m_mmapID.c_str());
 3    SCOPED_LOCK(m_lock);
 4    SCOPED_LOCK(m_exclusiveProcessLock);
 5
 6    if (m_needLoadFromFile) {
 7        m_file->reloadFromFile();
 8    }
 9
10    m_file->truncate(DEFAULT_MMAP_SIZE);
11    auto ptr = m_file->getMemory();
12    if (ptr) {
13        memset(ptr, 0, m_file->getFileSize());
14    }
15    m_file->msync(MMKV_SYNC);
16
17    unsigned char newIV[AES_KEY_LEN];
18    AESCrypt::fillRandomIV(newIV);
19    if (m_crypter) {
20        m_crypter->resetIV(newIV, sizeof(newIV));
21    }
22    writeActualSize(0, 0, newIV, IncreaseSequence);
23    m_metaFile->msync(MMKV_SYNC);
24
25    clearMemoryCache();
26    loadFromFile();
27}

检查通过后,将 m_dic 转换为 MiniPBCoder 即 binary data,写入前会确认当前文件 size 是否足够满足当前数据的写入,否则进行扩容。

doFullWriteBack

首先,生成 AES 随机 IV 对 allData 进行加密,接着通过 CodedOutputData 把 MMBuffer 写入 m_file,最后更新 crc 校验值。

 1bool MMKV::doFullWriteBack(MMBuffer &&allData) {
 2#ifdef MMKV_IOS
 3    unsigned char oldIV[AES_KEY_LEN];
 4    unsigned char newIV[AES_KEY_LEN];
 5    if (m_crypter) {
 6        memcpy(oldIV, m_crypter->m_vector, sizeof(oldIV));
 7#else
 8    unsigned char newIV[AES_KEY_LEN];
 9    if (m_crypter) {
10#endif
11        AESCrypt::fillRandomIV(newIV);
12        m_crypter->resetIV(newIV, sizeof(newIV));
13        auto ptr = allData.getPtr();
14        m_crypter->encrypt(ptr, ptr, allData.length());
15    }
16
17    auto ptr = (uint8_t *) m_file->getMemory();
18    delete m_output;
19    m_output = new CodedOutputData(ptr + Fixed32Size, m_file->getFileSize() - Fixed32Size);
20#ifdef MMKV_IOS
21    auto ret = protectFromBackgroundWriting(m_output->curWritePointer(), allData.length(), ^{
22      m_output->writeRawData(allData); // note: don't write size of data
23    });
24    if (!ret) {
25        // revert everything
26        if (m_crypter) {
27            m_crypter->resetIV(oldIV);
28        }
29        delete m_output;
30        m_output = new CodedOutputData(ptr + Fixed32Size, m_file->getFileSize() - Fixed32Size);
31        m_output->seek(m_actualSize);
32        return false;
33    }
34#else
35    m_output->writeRawData(allData); // note: don't write size of data
36#endif
37
38    m_actualSize = allData.length();
39    if (m_crypter) {
40        recaculateCRCDigestWithIV(newIV);
41    } else {
42        recaculateCRCDigestWithIV(nullptr);
43    }
44    m_hasFullWriteback = true;
45    // make sure lastConfirmedMetaInfo is saved
46    sync(MMKV_SYNC);
47    return true;
48}

recaculateCRCDigestWithIV

1void MMKV::recaculateCRCDigestWithIV(const void *iv) {
2auto ptr = (const uint8_t *) m_file->getMemory();
3if (ptr) {
4    m_crcDigest = 0;
5    m_crcDigest = (uint32_t) CRC32(0, ptr + Fixed32Size, (uint32_t) m_actualSize);
6    writeActualSize(m_actualSize, m_crcDigest, iv, IncreaseSequence);
7}

注意,重新生成 crc digest 这一行为只有在 full write-back 中被调用。尽管这里调用 writeActualSize 更新 m_metaInfo 并增加了 m_sequence,但是 actualSize 并没有变化

ensureMemorySize

除了完全写回的情况,当 append 的数据超出 fileSize 也会进行扩容。扩容策略以 2 倍于原来的 fileSize,不断扩充,直到比扩充的额外容量大为止。最后通过 truncate 裁剪至 DEFAULT_MMAP_SIZE 的整数倍。

核心逻辑如下:

 1constexpr size_t ItemSizeHolderSize = 4;
 2if (m_dic.empty()) {
 3    newSize += ItemSizeHolderSize;
 4}
 5if (newSize >= m_output->spaceLeft() || m_dic.empty()) {
 6    auto fileSize = m_file->getFileSize();
 7    MMBuffer data = MiniPBCoder::encodeDataWithObject(m_dic);
 8    size_t lenNeeded = data.length() + Fixed32Size + newSize;
 9    size_t avgItemSize = lenNeeded / std::max<size_t>(1, m_dic.size());
10    size_t futureUsage = avgItemSize * std::max<size_t>(8, (m_dic.size() + 1) / 2);
11	// 所需空间 >= 当前文件大小 || 所需空间的 1.5 倍于当前文件大小
12    if (lenNeeded >= fileSize || (lenNeeded + futureUsage) >= fileSize) {
13        size_t oldSize = fileSize;
14        do {
15            fileSize *= 2;
16        } while (lenNeeded + futureUsage >= fileSize);
17
18        if (!m_file->truncate(fileSize)) {
19            return false;
20        }
21
22        if (!isFileValid()) {
23            MMKVWarning("[%s] file not valid", m_mmapID.c_str());
24            return false;
25        }
26    }
27    return doFullWriteBack(std::move(data));
28}

Setter

改版后 iOS 端的 setter 则直接在 C++ API 上套了一层。

1bool set(bool value, MMKVKey_t key);
2...
3   
4// avoid unexpected type conversion (pointer to bool, etc)
5template <typename T>
6bool set(T value, MMKVKey_t key) = delete;
7bool set(NSObject<NSCoding> *__unsafe_unretained obj, MMKVKey_t key);

先以 bool 为例:

 1bool MMKV::set(bool value, MMKVKey_t key) {
 2    if (isKeyEmpty(key)) {
 3        return false;
 4    }
 5    size_t size = pbBoolSize();
 6    MMBuffer data(size);
 7    CodedOutputData output(data.getPtr(), size);
 8    output.writeBool(value);
 9
10    return setDataForKey(std::move(data), key);
11}

value 通过 CodedOutputData 写入 MMBuffer,最后走向了 setDataForKey。其他数据类型也是一样套路。

setDataForKey

更新 k-v 的核心方法,承接了全部数据更新的入口,做了三件事情:

  1. 数据校验,确认是否需要刷新缓存,重新加载文件;
  2. 将 buffer 数据写入文件;
  3. 更新 m_dic;
 1bool MMKV::setDataForKey(MMBuffer &&data, MMKVKey_t key) {
 2    if (data.length() == 0 || isKeyEmpty(key)) {
 3        return false;
 4    }
 5    SCOPED_LOCK(m_lock);
 6    SCOPED_LOCK(m_exclusiveProcessLock);
 7    checkLoadData();
 8
 9    auto ret = appendDataWithKey(data, key);
10    if (ret) {
11        m_dic[key] = std::move(data);
12        m_hasFullWriteback = false;
13#ifdef MMKV_APPLE
14        [key retain];
15#endif
16    }
17    return ret;
18}

整个 MMKV.cpp 文件中就这方法里冒出来一行 [key retain],这也是为啥这里 MMKV.cpp 采用 MRC 的原因。至于为啥要 retain 大家可以 🤔 一下。

checkLoadData

数据校验,第一步是确认 m_needLoadFromFile 为 true,是则加锁执行 loadFromFile。

接下来的检查是防止文件被其他进程篡改,对于单进程则无需考虑该 case,直接 return。

 1void MMKV::checkLoadData() {
 2    if (m_needLoadFromFile) {
 3        SCOPED_LOCK(m_sharedProcessLock);
 4
 5        m_needLoadFromFile = false;
 6        loadFromFile();
 7        return;
 8    }
 9    if (!m_isInterProcess) { // single process
10        return;
11    }
12
13    if (!m_metaFile->isFileValid()) {
14        return;
15    }
16    // TODO: atomic lock m_metaFile?
17    MMKVMetaInfo metaInfo;
18    metaInfo.read(m_metaFile->getMemory());
19    if (m_metaInfo->m_sequence != metaInfo.m_sequence) {
20        MMKVInfo("[%s] oldSeq %u, newSeq %u", ...);
21        SCOPED_LOCK(m_sharedProcessLock);
22
23        clearMemoryCache();
24        loadFromFile();
25        notifyContentChanged();
26    } else if (m_metaInfo->m_crcDigest != metaInfo.m_crcDigest) {
27        MMKVDebug("[%s] oldCrc %u, newCrc %u, new actualSize" ...);
28        SCOPED_LOCK(m_sharedProcessLock);
29
30        size_t fileSize = m_file->getActualFileSize();
31        if (m_file->getFileSize() != fileSize) {
32            MMKVInfo("file size has changed [%s] from %zu to %zu" ...);
33            clearMemoryCache();
34            loadFromFile();
35        } else {
36            partialLoadFromFile();
37        }
38        notifyContentChanged();
39    }
40}

防止文件的多进程篡改,会先读取 crc 文件中记录的 metaInfo 与当前内存的 m_metaInfo 对比。metaInfo 中的数据更新都在 writeActualSize 中完成。而当文件读取异常、空间不足或 crc 校验失败,这些情况发生时,会触发 meta_info 的变更。具体处理:

  1. m_sequence 代表了脏位数据 dirt bit 存在,此时需要 重新加载 m_file。
  2. m_crcDigest 不同且 fileSize 不同,说明进行了扩容,也需要重新加载 m_file。
  3. m_crcDigest 不同且 fileSize 相同,说明进行了 full write-back,之后会通过 partialLoadFromFile 完成相关内存数据的更新。

appendData

官方说明

标准 protobuf 不提供增量更新的能力,每次写入都必须全量写入。考虑到主要使用场景是频繁地进行写入更新,我们需要有增量更新的能力:将增量 kv 对象序列化后,直接 append 到内存末尾;这样同一个 key 会有新旧若干份数据,最新的数据在最后;那么只需在程序启动第一次打开 mmkv 时,不断用后读入的 value 替换之前的值,就可以保证数据是最新有效的。

 1bool MMKV::appendDataWithKey(const MMBuffer &data, MMKVKey_t key) {
 2#ifdef MMKV_APPLE
 3    auto keyData = [key dataUsingEncoding:NSUTF8StringEncoding];
 4    size_t keyLength = keyData.length;
 5#else
 6    size_t keyLength = key.length();
 7#endif
 8    // size needed to encode the key
 9    size_t size = keyLength + pbRawVarint32Size((int32_t) keyLength);
10    // size needed to encode the value
11    size += data.length() + pbRawVarint32Size((int32_t) data.length());
12
13    SCOPED_LOCK(m_exclusiveProcessLock);
14
15    bool hasEnoughSize = ensureMemorySize(size);
16    if (!hasEnoughSize || !isFileValid()) {
17        return false;
18    }
19
20#ifdef MMKV_IOS
21    auto ret = protectFromBackgroundWriting(m_output->curWritePointer(), size, ^{
22      m_output->writeData(MMBuffer(keyData, MMBufferNoCopy));
23      m_output->writeData(data); // note: write size of data
24    });
25    if (!ret) {
26        return false;
27    }
28#else
29    ... /// 除了 iOS 需要判断 background mode,其余均直接 m_output->writeData(data);
30#endif
31    ... // encrypt 数据,更新 m_actualSize、crcDigest
32    return true;
33}

追加逻辑比较简单,就是将存储 Key、Data 的 MMBuffer 经过 pb 压缩后写入 m_file。直接追加到 m_file 末尾带来的问题就是空间快速增长,导致文件大小不可控。因此,每次写入需要检查剩余文件空间。

Set Object

再来看看 Objc 中的 NSObject 是如何存取的。

 1bool MMKV::set(NSObject<NSCoding> *__unsafe_unretained obj, MMKVKey_t key) {
 2    if (isKeyEmpty(key)) {
 3        return false;
 4    }
 5    if (!obj) {
 6        removeValueForKey(key);
 7        return true;
 8    }
 9    MMBuffer data;
10    if (MiniPBCoder::isCompatibleObject(obj)) {
11        data = MiniPBCoder::encodeDataWithObject(obj);
12    } else {
13        /*if ([object conformsToProtocol:@protocol(NSCoding)])*/ {
14            auto tmp = [NSKeyedArchiver archivedDataWithRootObject:obj];
15            if (tmp.length > 0) {
16                data = MMBuffer(tmp);
17            }
18        }
19    }
20
21    return setDataForKey(std::move(data), key);
22}

对 Objc 而言 MiniPBCoder 仅支持了基本数据类型和 NSString、NSData、NSDate 这三种:

 1bool MiniPBCoder::isCompatibleObject(NSObject *obj) {
 2    if ([obj isKindOfClass:[NSString class]]) {
 3        return true;
 4    }
 5    if ([obj isKindOfClass:[NSData class]]) {
 6        return true;
 7    }
 8    if ([obj isKindOfClass:[NSDate class]]) {
 9        return true;
10    }
11
12    return false;
13}

其余 NSObject 对象就需要走 NSCoding 协议通过 NSArchive 方式编码为 NSData 存入。

Getter

1bool getBool(MMKVKey_t key, bool defaultValue = false);
2...
3
4#ifdef MMKV_APPLE
5    NSObject *getObject(MMKVKey_t key, Class cls);
6#else  // !defined(MMKV_APPLE)
7    mmkv::MMBuffer getBytes(MMKVKey_t key);
8    bool getVector(MMKVKey_t key, std::vector<std::string> &result);
9#endif // MMKV_APPLE

以 bool 为例:

 1bool MMKV::getBool(MMKVKey_t key, bool defaultValue) {
 2    if (isKeyEmpty(key)) {
 3        return defaultValue;
 4    }
 5    SCOPED_LOCK(m_lock);
 6    auto &data = getDataForKey(key);
 7    if (data.length() > 0) {
 8        try {
 9            CodedInputData input(data.getPtr(), data.length());
10            return input.readBool();
11        } catch (std::exception &exception) {
12            MMKVError("%s", exception.what());
13        }
14    }
15    return defaultValue;
16}

数据读取就更简单了,直接从 getDataForKey 中取出 MMBuffer,经过 CodedOutputData 转换得到 bool。

getDataForKey

1const MMBuffer &MMKV::getDataForKey(MMKVKey_t key) {
2    checkLoadData();
3    auto itr = m_dic.find(key);
4    if (itr != m_dic.end()) {
5        return itr->second;
6    }
7    static MMBuffer nan;
8    return nan;
9}

Get Object

 1NSObject *MMKV::getObject(MMKVKey_t key, Class cls) {
 2    if (isKeyEmpty(key) || !cls) {
 3        return nil;
 4    }
 5    SCOPED_LOCK(m_lock);
 6    auto &data = getDataForKey(key);
 7    if (data.length() > 0) {
 8        if (MiniPBCoder::isCompatibleClass(cls)) {
 9            try {
10                auto result = MiniPBCoder::decodeObject(data, cls);
11                return result;
12            } catch (std::exception &exception) {
13                MMKVError("%s", exception.what());
14            }
15        } else {
16            if ([cls conformsToProtocol:@protocol(NSCoding)]) {
17                auto tmp = [NSData dataWithBytesNoCopy:data.getPtr() length:data.length() freeWhenDone:NO];
18                return [NSKeyedUnarchiver unarchiveObjectWithData:tmp];
19            }
20        }
21    }
22    return nil;
23}

这个也比较简单就不展开了。

总结

宁可错杀一千,也绝不放过一个。

这是整体读完 MMKV 核心逻辑的第一感受。为什么呢?

MMKV 作为多进程读写的框架。细心的同学可以发现,在它的每一个方法的真正逻辑执行前都进行了大量的异常校验,同时对于脏数据的保护和容错也比较绕。感觉你不把所有方法看过一遍,比较难 get 到其中的用意。相比这一点,CocoaLumberjack 的代码就非常友好了,每个关键字段的作用,核心逻辑的解释,以及背后的一些原理都有很详细的注释。

本文忽略了 MiniPB 的编解码逻辑和读写锁保护,以核心逻辑文件读写为主。MMKV 对于只要异常就是各种标记,然后重载。整个框架也是围绕 loadFromFile 不断的添加保护,文件锁,crc 校验,脏数据写回。

如果你看到这里,应该能发现,本文是按照调用逻辑一层层深入,尽可能地让各个方法的上下文是衔接有序。希望能帮助各位大致了解 MMKV 的核心逻辑。