0
# Instance Management
1

2
Methods for creating and managing MMKV instances with different configurations including single/multi-process modes, encryption, custom directories, and ashmem-based instances.
3

4
## Capabilities
5

6
### Default Instance
7

8
Get the default MMKV instance for simple use cases.
9

10
```java { .api }
11
/**
12
 * Create the default MMKV instance in single-process mode.
13
 * @return The default MMKV instance
14
 * @throws RuntimeException if there's a runtime error
15
 */
16
public static MMKV defaultMMKV();
17

18
/**
19
 * Create the default MMKV instance with customize process mode and encryption.
20
 * @param mode The process mode (SINGLE_PROCESS_MODE or MULTI_PROCESS_MODE)
21
 * @param cryptKey The encryption key (no more than 16 bytes), null for no encryption
22
 * @return The default MMKV instance
23
 * @throws RuntimeException if there's a runtime error
24
 */
25
public static MMKV defaultMMKV(int mode, String cryptKey);
26
```
27

28
**Usage Example:**
29

30
```java
31
import com.tencent.mmkv.MMKV;
32

33
// Get default instance (single-process, no encryption)
34
MMKV kv = MMKV.defaultMMKV();
35

36
// Get default instance with multi-process support
37
MMKV multiProcessKv = MMKV.defaultMMKV(MMKV.MULTI_PROCESS_MODE, null);
38

39
// Get default instance with encryption
40
MMKV encryptedKv = MMKV.defaultMMKV(MMKV.SINGLE_PROCESS_MODE, "my-secret-key");
41
```
42

43
### Named Instances
44

45
Create MMKV instances with unique IDs for data separation.
46

47
```java { .api }
48
/**
49
 * Create an MMKV instance with a unique ID (in single-process mode).
50
 * @param mmapID The unique ID of the MMKV instance
51
 * @return The MMKV instance
52
 * @throws RuntimeException if there's a runtime error
53
 */
54
public static MMKV mmkvWithID(String mmapID);
55

56
/**
57
 * Create an MMKV instance in single-process or multi-process mode.
58
 * @param mmapID The unique ID of the MMKV instance
59
 * @param mode The process mode (SINGLE_PROCESS_MODE or MULTI_PROCESS_MODE)
60
 * @return The MMKV instance
61
 * @throws RuntimeException if there's a runtime error
62
 */
63
public static MMKV mmkvWithID(String mmapID, int mode);
64

65
/**
66
 * Create an MMKV instance with expected capacity.
67
 * @param mmapID The unique ID of the MMKV instance
68
 * @param mode The process mode
69
 * @param expectedCapacity The file size expected when opening or creating file
70
 * @return The MMKV instance
71
 * @throws RuntimeException if there's a runtime error
72
 */
73
public static MMKV mmkvWithID(String mmapID, int mode, long expectedCapacity);
74
```
75

76
**Usage Example:**
77

78
```java
79
// Create separate instances for different data types
80
MMKV userPrefs = MMKV.mmkvWithID("user_preferences");
81
MMKV gameData = MMKV.mmkvWithID("game_data");
82
MMKV cache = MMKV.mmkvWithID("cache_data");
83

84
// Multi-process instance for sharing between processes
85
MMKV sharedData = MMKV.mmkvWithID("shared_data", MMKV.MULTI_PROCESS_MODE);
86

87
// Instance with pre-allocated capacity for performance
88
MMKV largeDr = MMKV.mmkvWithID("large_data", MMKV.SINGLE_PROCESS_MODE, 1024 * 1024); // 1MB
89
```
90

91
### Encrypted Instances
92

93
Create MMKV instances with encryption for sensitive data.
94

95
```java { .api }
96
/**
97
 * Create an MMKV instance with encryption key.
98
 * @param mmapID The unique ID of the MMKV instance
99
 * @param mode The process mode
100
 * @param cryptKey The encryption key (no more than 16 bytes)
101
 * @return The MMKV instance
102
 * @throws RuntimeException if there's a runtime error
103
 */
104
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);
105
```
106

107
**Usage Example:**
108

109
```java
110
// Create encrypted instance for sensitive data
111
MMKV secureStorage = MMKV.mmkvWithID("secure_data", 
112
                                     MMKV.SINGLE_PROCESS_MODE, 
113
                                     "encryption-key");
114

115
// Store sensitive information
116
secureStorage.encode("access_token", "secret-token-value");
117
secureStorage.encode("user_password", "hashed-password");
118
```
119

120
### Custom Directory Instances
121

122
Create MMKV instances in custom directories for data organization.
123

124
```java { .api }
125
/**
126
 * Create an MMKV instance in customize folder.
127
 * @param mmapID The unique ID of the MMKV instance
128
 * @param rootPath The folder of the MMKV instance
129
 * @return The MMKV instance
130
 * @throws RuntimeException if there's a runtime error
131
 */
132
public static MMKV mmkvWithID(String mmapID, String rootPath);
133

134
/**
135
 * Create an MMKV instance in customize folder with capacity.
136
 * @param mmapID The unique ID of the MMKV instance
137
 * @param rootPath The folder of the MMKV instance
138
 * @param expectedCapacity The file size expected
139
 * @return The MMKV instance
140
 * @throws RuntimeException if there's a runtime error
141
 */
142
public static MMKV mmkvWithID(String mmapID, String rootPath, long expectedCapacity);
143
```
144

145
**Usage Example:**
146

147
```java
148
// Create instance in custom directory
149
File customDir = new File(getExternalFilesDir(null), "app_data");
150
MMKV customKv = MMKV.mmkvWithID("custom_data", customDir.getAbsolutePath());
151

152
// Separate user data by user ID
153
String userDir = getFilesDir().getAbsolutePath() + "/users/" + userId;
154
MMKV userKv = MMKV.mmkvWithID("user_" + userId, userDir);
155
```
156

157
### Complete Configuration
158

159
Create MMKV instances with all customization options.
160

161
```java { .api }
162
/**
163
 * Create an MMKV instance with all customize settings.
164
 * @param mmapID The unique ID of the MMKV instance
165
 * @param mode The process mode
166
 * @param cryptKey The encryption key (null for no encryption)
167
 * @param rootPath The folder of the MMKV instance
168
 * @param expectedCapacity The file size expected
169
 * @return The MMKV instance
170
 * @throws RuntimeException if there's a runtime error
171
 */
172
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, 
173
                             String rootPath, long expectedCapacity);
174

175
/**
176
 * Create an MMKV instance with all settings except capacity.
177
 * @param mmapID The unique ID of the MMKV instance
178
 * @param mode The process mode
179
 * @param cryptKey The encryption key
180
 * @param rootPath The folder of the MMKV instance
181
 * @return The MMKV instance
182
 * @throws RuntimeException if there's a runtime error
183
 */
184
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, String rootPath);
185
```
186

187
**Usage Example:**
188

189
```java
190
// Full configuration example
191
MMKV fullyConfigured = MMKV.mmkvWithID(
192
    "app_config",                    // Unique ID
193
    MMKV.MULTI_PROCESS_MODE,        // Multi-process support
194
    "config-encryption-key",         // Encryption key
195
    getFilesDir() + "/config",       // Custom directory
196
    512 * 1024                       // 512KB expected capacity
197
);
198
```
199

200
### Backup Instance
201

202
Create backed-up MMKV instances for data resilience.
203

204
```java { .api }
205
/**
206
 * Get a backed-up MMKV instance with customize settings.
207
 * @param mmapID The unique ID of the MMKV instance
208
 * @param mode The process mode
209
 * @param cryptKey The encryption key
210
 * @param rootPath The backup folder of the MMKV instance
211
 * @return The backed-up MMKV instance
212
 * @throws RuntimeException if there's a runtime error
213
 */
214
public static MMKV backedUpMMKVWithID(String mmapID, int mode, String cryptKey, String rootPath);
215
```
216

217
**Usage Example:**
218

219
```java
220
// Create backup instance in separate directory
221
File backupDir = new File(getExternalFilesDir(null), "backup");
222
MMKV backupKv = MMKV.backedUpMMKVWithID("main_backup", 
223
                                        MMKV.SINGLE_PROCESS_MODE,
224
                                        null,
225
                                        backupDir.getAbsolutePath());
226
```
227

228
### Anonymous Shared Memory Instances
229

230
Create MMKV instances based on anonymous shared memory for inter-process communication without disk files.
231

232
```java { .api }
233
/**
234
 * Create an MMKV instance base on Anonymous Shared Memory.
235
 * Not synced to any disk files.
236
 * @param context The Android app context
237
 * @param mmapID The unique ID of the MMKV instance
238
 * @param size The maximum size of the underlying Anonymous Shared Memory
239
 * @param mode The process mode
240
 * @param cryptKey The encryption key
241
 * @return The ashmem-based MMKV instance
242
 * @throws RuntimeException if there's a runtime error
243
 */
244
public static MMKV mmkvWithAshmemID(Context context, String mmapID, int size, 
245
                                   int mode, String cryptKey);
246

247
/**
248
 * Get an ashmem MMKV instance from file descriptors.
249
 * @param mmapID The unique ID of the MMKV instance
250
 * @param fd The file descriptor of the ashmem MMKV file
251
 * @param metaFD The file descriptor of the ashmem MMKV crc file
252
 * @param cryptKey The encryption key
253
 * @return The ashmem-based MMKV instance
254
 * @throws RuntimeException if there's a runtime error
255
 */
256
public static MMKV mmkvWithAshmemFD(String mmapID, int fd, int metaFD, String cryptKey);
257
```
258

259
**Usage Example:**
260

261
```java
262
// Create ashmem instance for inter-process sharing (main process)
263
MMKV ashmemKv = MMKV.mmkvWithAshmemID(this, 
264
                                      "shared_memory", 
265
                                      1024 * 1024,  // 1MB size
266
                                      MMKV.MULTI_PROCESS_MODE,
267
                                      null);
268

269
// In another process, get the same instance via ContentProvider
270
// (handled automatically by MMKV's ContentProvider)
271
```
272

273
### Instance Information
274

275
Get information about MMKV instances.
276

277
```java { .api }
278
/**
279
 * Get the unique ID of the MMKV instance.
280
 * @return The instance ID
281
 */
282
public String mmapID();
283

284
/**
285
 * Check if this instance is in multi-process mode.
286
 * @return True if multi-process, false otherwise
287
 */
288
public boolean isMultiProcess();
289

290
/**
291
 * Check if this instance is in read-only mode.
292
 * @return True if read-only, false otherwise
293
 */
294
public boolean isReadOnly();
295
```
296

297
**Usage Example:**
298

299
```java
300
MMKV kv = MMKV.mmkvWithID("example", MMKV.MULTI_PROCESS_MODE);
301

302
String id = kv.mmapID();                    // "example"
303
boolean isMultiProcess = kv.isMultiProcess(); // true
304
boolean isReadOnly = kv.isReadOnly();        // false
305

306
Log.d("MMKV", String.format("Instance %s: multiProcess=%b, readOnly=%b", 
307
                            id, isMultiProcess, isReadOnly));
308
```
309

310
### File Validation and Existence
311

312
Static methods for checking MMKV file status.
313

314
```java { .api }
315
/**
316
 * Check whether the MMKV file is valid or not.
317
 * @param mmapID The unique ID of the MMKV instance
318
 * @return True if valid, false otherwise
319
 */
320
public static boolean isFileValid(String mmapID);
321

322
/**
323
 * Check whether the MMKV file is valid in customize folder.
324
 * @param mmapID The unique ID of the MMKV instance
325
 * @param rootPath The folder of the MMKV instance
326
 * @return True if valid, false otherwise
327
 */
328
public static boolean isFileValid(String mmapID, String rootPath);
329

330
/**
331
 * Check existence of the MMKV file.
332
 * @param mmapID The unique ID of the MMKV instance
333
 * @return True if exists, false otherwise
334
 */
335
public static boolean checkExist(String mmapID);
336

337
/**
338
 * Check existence of the MMKV file in customize folder.
339
 * @param mmapID The unique ID of the MMKV instance
340
 * @param rootPath The folder of the MMKV instance
341
 * @return True if exists, false otherwise
342
 */
343
public static boolean checkExist(String mmapID, String rootPath);
344
```
345

346
**Usage Example:**
347

348
```java
349
// Check if MMKV files exist and are valid before creating instances
350
if (MMKV.checkExist("user_data")) {
351
    if (MMKV.isFileValid("user_data")) {
352
        MMKV userKv = MMKV.mmkvWithID("user_data");
353
        // File exists and is valid, safe to use
354
    } else {
355
        Log.w("MMKV", "User data file exists but is corrupted");
356
        // Handle corruption - maybe delete and recreate
357
    }
358
} else {
359
    Log.i("MMKV", "User data file doesn't exist, will be created");
360
    MMKV userKv = MMKV.mmkvWithID("user_data");
361
}
362
```
363

364
## Constants
365

366
```java { .api }
367
// Process mode constants
368
public static final int SINGLE_PROCESS_MODE = 1 << 0;
369
public static final int MULTI_PROCESS_MODE = 1 << 1;
370
public static final int READ_ONLY_MODE = 1 << 5;
371
```