0
# Instance Management
1

2
MMKV instance creation and management with various configuration options including encryption, multi-process modes, and custom storage locations. Instances can be created with unique IDs for logical separation of data.
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 in customize process mode, with an encryption key.
20
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
21
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
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
// Simple default instance
32
MMKV kv = MMKV.defaultMMKV();
33
kv.encode("user_id", 12345);
34

35
// Default instance with encryption
36
MMKV encryptedKv = MMKV.defaultMMKV(MMKV.SINGLE_PROCESS_MODE, "my_secret_key");
37
encryptedKv.encode("sensitive_data", "confidential_info");
38

39
// Default instance with multi-process support
40
MMKV multiProcessKv = MMKV.defaultMMKV(MMKV.MULTI_PROCESS_MODE, null);
41
multiProcessKv.encode("shared_config", "value");
42
```
43

44
### Named Instances
45

46
Create MMKV instances with unique IDs for logical data separation.
47

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

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

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

77
**Usage Example:**
78

79
```java
80
// Separate instances for different data types
81
MMKV userPrefs = MMKV.mmkvWithID("user_preferences");
82
MMKV gameData = MMKV.mmkvWithID("game_data");
83
MMKV cacheData = MMKV.mmkvWithID("cache_data");
84

85
userPrefs.encode("theme", "dark");
86
gameData.encode("high_score", 15000);
87
cacheData.encode("last_sync", System.currentTimeMillis());
88

89
// Multi-process instance for shared data
90
MMKV sharedData = MMKV.mmkvWithID("shared_config", MMKV.MULTI_PROCESS_MODE);
91
sharedData.encode("app_version", "2.1.0");
92

93
// Pre-allocate file size for performance
94
MMKV largeDataset = MMKV.mmkvWithID("large_data", MMKV.SINGLE_PROCESS_MODE, 10 * 1024 * 1024); // 10MB
95
```
96

97
### Encrypted Instances
98

99
Create MMKV instances with encryption for sensitive data protection.
100

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

112
/**
113
 * Create an MMKV instance with customize settings all in one.
114
 * @param mmapID The unique ID of the MMKV instance
115
 * @param mode The process mode of the MMKV instance
116
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
117
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
118
 * @param expectedCapacity The file size you expected when opening or creating file
119
 * @return MMKV instance
120
 * @throws RuntimeException if there's a runtime error
121
 */
122
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, String rootPath, long expectedCapacity);
123
```
124

125
**Usage Example:**
126

127
```java
128
// Encrypted user credentials
129
MMKV credentials = MMKV.mmkvWithID("user_credentials", MMKV.SINGLE_PROCESS_MODE, "encryption_key");
130
credentials.encode("username", "alice");
131
credentials.encode("auth_token", "secret_token_12345");
132

133
// Encrypted multi-process instance
134
MMKV secureShared = MMKV.mmkvWithID("secure_shared", MMKV.MULTI_PROCESS_MODE, "shared_secret");
135
secureShared.encode("api_key", "confidential_api_key");
136

137
// Full customization with encryption
138
File customDir = new File(getFilesDir(), "secure_storage");
139
MMKV fullyCustom = MMKV.mmkvWithID(
140
    "custom_encrypted",
141
    MMKV.SINGLE_PROCESS_MODE,
142
    "my_encrypt_key",
143
    customDir.getAbsolutePath(),
144
    5 * 1024 * 1024 // 5MB capacity
145
);
146
```
147

148
### Custom Root Path Instances
149

150
Create MMKV instances with custom storage locations.
151

152
```java { .api }
153
/**
154
 * Create an MMKV instance in customize folder.
155
 * @param mmapID The unique ID of the MMKV instance
156
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
157
 * @return MMKV instance
158
 * @throws RuntimeException if there's a runtime error
159
 */
160
public static MMKV mmkvWithID(String mmapID, String rootPath);
161

162
/**
163
 * Create an MMKV instance in customize folder with expected capacity.
164
 * @param mmapID The unique ID of the MMKV instance
165
 * @param rootPath The folder of the MMKV instance
166
 * @param expectedCapacity The file size you expected when opening or creating file
167
 * @return MMKV instance
168
 * @throws RuntimeException if there's a runtime error
169
 */
170
public static MMKV mmkvWithID(String mmapID, String rootPath, long expectedCapacity);
171
```
172

173
**Usage Example:**
174

175
```java
176
// Store cache data on external storage
177
File externalDir = new File(getExternalFilesDir(null), "mmkv_cache");
178
MMKV cacheStorage = MMKV.mmkvWithID("image_cache", externalDir.getAbsolutePath());
179

180
// Temporary data with custom location and capacity
181
File tempDir = new File(getCacheDir(), "temp_mmkv");
182
MMKV tempStorage = MMKV.mmkvWithID("temp_data", tempDir.getAbsolutePath(), 2 * 1024 * 1024);
183
```
184

185
### Backup and Restore Instances
186

187
Create instances specifically designed for backup scenarios.
188

189
```java { .api }
190
/**
191
 * Get a backed-up MMKV instance with customize settings all in one.
192
 * @param mmapID The unique ID of the MMKV instance
193
 * @param mode The process mode of the MMKV instance
194
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
195
 * @param rootPath The backup folder of the MMKV instance
196
 * @return MMKV instance
197
 * @throws RuntimeException if there's a runtime error
198
 */
199
public static MMKV backedUpMMKVWithID(String mmapID, int mode, String cryptKey, String rootPath);
200
```
201

202
**Usage Example:**
203

204
```java
205
// Create backup instance
206
File backupDir = new File(getExternalFilesDir(null), "mmkv_backup");
207
MMKV backupInstance = MMKV.backedUpMMKVWithID(
208
    "user_data_backup",
209
    MMKV.SINGLE_PROCESS_MODE,
210
    "backup_key",
211
    backupDir.getAbsolutePath()
212
);
213
```
214

215
### Anonymous Shared Memory Instances
216

217
Create MMKV instances using Anonymous Shared Memory for inter-process communication without persistent storage.
218

219
```java { .api }
220
/**
221
 * Create an MMKV instance base on Anonymous Shared Memory, aka not synced to any disk files.
222
 * @param context The context of Android App, usually from Application
223
 * @param mmapID The unique ID of the MMKV instance
224
 * @param size The maximum size of the underlying Anonymous Shared Memory
225
 * @param mode The process mode of the MMKV instance
226
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
227
 * @return MMKV instance
228
 * @throws RuntimeException if there's a runtime error
229
 */
230
public static MMKV mmkvWithAshmemID(Context context, String mmapID, int size, int mode, String cryptKey);
231

232
/**
233
 * Get an ashmem MMKV instance that has been initiated by another process.
234
 * @param mmapID The unique ID of the MMKV instance
235
 * @param fd The file descriptor of the ashmem of the MMKV file
236
 * @param metaFD The file descriptor of the ashmem of the MMKV crc file
237
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
238
 * @return MMKV instance
239
 * @throws RuntimeException if there's a runtime error
240
 */
241
public static MMKV mmkvWithAshmemFD(String mmapID, int fd, int metaFD, String cryptKey);
242
```
243

244
**Usage Example:**
245

246
```java
247
// Create ashmem instance for temporary inter-process data
248
MMKV ashmemKv = MMKV.mmkvWithAshmemID(
249
    this,
250
    "temp_shared_data",
251
    1024 * 1024, // 1MB size limit
252
    MMKV.MULTI_PROCESS_MODE,
253
    null
254
);
255

256
// Use for temporary data sharing between processes
257
ashmemKv.encode("current_state", "processing");
258
ashmemKv.encode("progress", 45);
259
```
260

261
### Instance Information
262

263
Get information about MMKV instances.
264

265
```java { .api }
266
/**
267
 * Get the unique ID of the MMKV instance.
268
 * @return The unique ID of the MMKV instance
269
 */
270
public String mmapID();
271

272
/**
273
 * Check if this instance is in multi-process mode.
274
 * @return true if multi-process mode, false otherwise
275
 */
276
public boolean isMultiProcess();
277

278
/**
279
 * Check if this instance is in read-only mode.
280
 * @return true if read-only mode, false otherwise
281
 */
282
public boolean isReadOnly();
283
```
284

285
**Usage Example:**
286

287
```java
288
MMKV kv = MMKV.mmkvWithID("test_instance", MMKV.MULTI_PROCESS_MODE);
289

290
String instanceId = kv.mmapID(); // Returns "test_instance"
291
boolean isMultiProcess = kv.isMultiProcess(); // Returns true
292
boolean isReadOnly = kv.isReadOnly(); // Returns false
293

294
Log.d("MMKV", "Instance: " + instanceId + ", Multi-process: " + isMultiProcess);
295
```
296

297
### Instance Lifecycle
298

299
Manage MMKV instance lifecycle and cleanup.
300

301
```java { .api }
302
/**
303
 * Call this method if the MMKV instance is no longer needed in the near future.
304
 * Any subsequent call to any MMKV instances with the same ID is undefined behavior.
305
 */
306
public void close();
307

308
/**
309
 * Clear memory cache of the MMKV instance.
310
 * You can call it on memory warning.
311
 * Any subsequent call to the MMKV instance will trigger all key-values loading from the file again.
312
 */
313
public void clearMemoryCache();
314
```
315

316
**Usage Example:**
317

318
```java
319
MMKV tempKv = MMKV.mmkvWithID("temporary_data");
320
// Use instance...
321

322
// Clear memory cache on memory pressure
323
@Override
324
public void onTrimMemory(int level) {
325
    super.onTrimMemory(level);
326
    if (level >= TRIM_MEMORY_MODERATE) {
327
        tempKv.clearMemoryCache();
328
    }
329
}
330

331
// Close instance when no longer needed
332
@Override
333
protected void onDestroy() {
334
    super.onDestroy();
335
    tempKv.close();
336
}
337
```
338

339
## Constants
340

341
```java { .api }
342
// Process modes
343
public static final int SINGLE_PROCESS_MODE = 1 << 0;  // Single-process mode. The default mode
344
public static final int MULTI_PROCESS_MODE = 1 << 1;   // Multi-process mode
345
public static final int READ_ONLY_MODE = 1 << 5;       // Read-only mode
346
```