0
# MMKV Static
1

2
MMKV is an efficient, cross-platform key-value storage framework used in the WeChat application. This static C++ variant for Android provides high-performance memory-mapped file storage with Protocol Buffer serialization, offering immediate persistence without explicit sync calls while maintaining a small footprint (~50KB per architecture).
3

4
## Package Information
5

6
- **Package Name**: mmkv-static
7
- **Package Type**: maven
8
- **Language**: Java/Kotlin (with C++ native library)
9
- **Installation**: `implementation 'com.tencent:mmkv-static:2.2.2'`
10
- **Architecture Support**: 64-bit only (ARM64, x86_64)
11

12
## Core Imports
13

14
```java
15
import com.tencent.mmkv.MMKV;
16
import com.tencent.mmkv.MMKVLogLevel;
17
```
18

19
## Basic Usage
20

21
```java
22
// Initialize MMKV (required before use)
23
String rootDir = MMKV.initialize(getApplicationContext());
24

25
// Get default instance
26
MMKV kv = MMKV.defaultMMKV();
27

28
// Store values
29
kv.encode("username", "john_doe");
30
kv.encode("user_id", 12345);
31
kv.encode("settings", settingsObject); // Parcelable support
32

33
// Retrieve values
34
String username = kv.decodeString("username");
35
int userId = kv.decodeInt("user_id");
36
MySettings settings = kv.decodeParcelable("settings", MySettings.class);
37

38
// Check if key exists
39
if (kv.containsKey("username")) {
40
    // Use the value
41
}
42
```
43

44
## Architecture
45

46
MMKV is built around several key components:
47

48
- **Memory-Mapped Files**: Uses mmap for efficient file I/O with immediate persistence
49
- **Protocol Buffer Serialization**: High-performance data serialization optimized for mobile
50
- **Multi-Process Support**: Safe concurrent access across Android processes with file locking
51
- **SharedPreferences Compatibility**: Drop-in replacement for Android's SharedPreferences API
52
- **Encryption**: Optional AES encryption with custom keys up to 16 bytes
53
- **Key Expiration**: Automatic key expiration with configurable durations
54
- **Native Bridge**: JNI bridge to high-performance C++ implementation
55

56
## Capabilities
57

58
### Initialization and Setup
59

60
Essential initialization methods required before using MMKV instances. Supports custom root directories, log levels, and library loaders.
61

62
```java { .api }
63
// Basic initialization with default settings
64
static String initialize(Context context);
65

66
// Initialize with custom log level
67
static String initialize(Context context, MMKVLogLevel logLevel);
68

69
// Initialize with custom library loader (e.g., ReLinker)
70
static String initialize(Context context, LibLoader loader);
71
```
72

73
[Initialization](./initialization.md)
74

75
### Instance Creation and Management
76

77
Create MMKV instances with various configurations including single/multi-process modes, encryption, and custom storage locations.
78

79
```java { .api }
80
// Get default MMKV instance
81
static MMKV defaultMMKV();
82

83
// Create named instance with unique identifier
84
static MMKV mmkvWithID(String mmapID);
85

86
// Create instance with process mode and encryption
87
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);
88
```
89

90
[Instance Management](./instance-management.md)
91

92
### Data Storage and Retrieval
93

94
High-performance key-value storage supporting Java primitives, strings, byte arrays, Parcelable objects, and string sets with optional expiration.
95

96
```java { .api }
97
// Store primitive values
98
boolean encode(String key, boolean value);
99
boolean encode(String key, int value);
100
boolean encode(String key, String value);
101

102
// Retrieve with default values
103
boolean decodeBool(String key, boolean defaultValue);
104
int decodeInt(String key, int defaultValue);
105
String decodeString(String key, String defaultValue);
106
```
107

108
[Data Operations](./data-operations.md)
109

110
### SharedPreferences Compatibility
111

112
Full compatibility with Android's SharedPreferences interface, providing a drop-in replacement with significantly better performance.
113

114
```java { .api }
115
// SharedPreferences interface methods
116
String getString(String key, String defValue);
117
SharedPreferences.Editor putString(String key, String value);
118
SharedPreferences.Editor edit();
119
boolean commit();
120
void apply();
121
```
122

123
[SharedPreferences API](./shared-preferences.md)
124

125
### Advanced Features
126

127
Advanced functionality including encryption, key expiration, backup/restore, and inter-process notifications.
128

129
```java { .api }
130
// Encryption management
131
String cryptKey();
132
boolean reKey(String cryptKey);
133

134
// Key expiration
135
boolean enableAutoKeyExpire(int expireDurationInSecond);
136
boolean encode(String key, String value, int expireDurationInSecond);
137

138
// Backup and restore
139
static boolean backupOneToDirectory(String mmapID, String dstDir, String rootPath);
140
static boolean restoreOneMMKVFromDirectory(String mmapID, String srcDir, String rootPath);
141
```
142

143
[Advanced Features](./advanced-features.md)
144

145
### Process Management and Synchronization
146

147
Multi-process synchronization, locking mechanisms, and content change notifications for safe concurrent access.
148

149
```java { .api }
150
// Inter-process locking
151
void lock();
152
void unlock();
153
boolean tryLock();
154

155
// Synchronization
156
void sync();   // Synchronous save
157
void async();  // Asynchronous save
158

159
// Process mode checking
160
boolean isMultiProcess();
161
```
162

163
[Process Management](./process-management.md)
164

165
### NameSpace Management
166

167
Manage MMKV instances within custom root directories for isolated storage environments.
168

169
```java { .api }
170
// Create custom NameSpace
171
static NameSpace nameSpace(String dir);
172

173
// Get default NameSpace
174
static NameSpace defaultNameSpace();
175
```
176

177
[NameSpace Management](./namespace.md)
178

179
### Utility Types and Interfaces
180

181
Supporting interfaces, exceptions, and utility classes for advanced functionality.
182

183
```java { .api }
184
// Content change notifications
185
interface MMKVContentChangeNotification;
186

187
// Native memory buffer for direct JNI access
188
class NativeBuffer;
189

190
// Error handling and log redirection
191
interface MMKVHandler;
192
```
193

194
[Utility Types](./utility-types.md)
195

196
## Constants
197

198
```java { .api }
199
// Process modes
200
static final int SINGLE_PROCESS_MODE = 1;
201
static final int MULTI_PROCESS_MODE = 2;
202
static final int READ_ONLY_MODE = 32;
203

204
// Internal mode flags (for advanced usage)
205
static final int ASHMEM_MODE = 8;        // Anonymous shared memory mode
206
static final int BACKUP_MODE = 16;       // Backup mode flag
207

208
// Expiration constants (in seconds)
209
static final int ExpireNever = 0;
210
static final int ExpireInMinute = 60;
211
static final int ExpireInHour = 3600;
212
static final int ExpireInDay = 86400;
213
static final int ExpireInMonth = 2592000;
214
static final int ExpireInYear = 31536000;
215
```
216

217
## Core Types
218

219
```java { .api }
220
// Log levels
221
enum MMKVLogLevel {
222
    LevelDebug,    // Debug level (not available in release)
223
    LevelInfo,     // Info level (default)  
224
    LevelWarning,  // Warning level
225
    LevelError,    // Error level
226
    LevelNone      // Disable all logging
227
}
228

229
// Recovery strategies for error handling
230
enum MMKVRecoverStrategic {
231
    OnErrorDiscard,  // Discard data on errors (default)
232
    OnErrorRecover   // Try to recover data on errors
233
}
234

235
// Custom library loader interface
236
interface LibLoader {
237
    void loadLibrary(String libName);
238
}
239
```