or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mddata-operations.mdindex.mdinitialization.mdinstance-management.mdnamespace.mdprocess-management.mdshared-preferences.mdutility-types.md
tile.json

tessl/maven-com-tencent--mmkv-static

High-performance, cross-platform key-value storage framework with static C++ linking for Android applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.tencent/mmkv-static@2.2.x

To install, run

npx @tessl/cli install tessl/maven-com-tencent--mmkv-static@2.2.0

index.mddocs/

MMKV Static

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).

Package Information

  • Package Name: mmkv-static
  • Package Type: maven
  • Language: Java/Kotlin (with C++ native library)
  • Installation: implementation 'com.tencent:mmkv-static:2.2.2'
  • Architecture Support: 64-bit only (ARM64, x86_64)

Core Imports

import com.tencent.mmkv.MMKV;
import com.tencent.mmkv.MMKVLogLevel;

Basic Usage

// Initialize MMKV (required before use)
String rootDir = MMKV.initialize(getApplicationContext());

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

// Store values
kv.encode("username", "john_doe");
kv.encode("user_id", 12345);
kv.encode("settings", settingsObject); // Parcelable support

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

// Check if key exists
if (kv.containsKey("username")) {
    // Use the value
}

Architecture

MMKV is built around several key components:

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

Capabilities

Initialization and Setup

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

// Basic initialization with default settings
static String initialize(Context context);

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

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

Initialization

Instance Creation and Management

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

// Get default MMKV instance
static MMKV defaultMMKV();

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

// Create instance with process mode and encryption
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);

Instance Management

Data Storage and Retrieval

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

// Store primitive values
boolean encode(String key, boolean value);
boolean encode(String key, int value);
boolean encode(String key, String value);

// Retrieve with default values
boolean decodeBool(String key, boolean defaultValue);
int decodeInt(String key, int defaultValue);
String decodeString(String key, String defaultValue);

Data Operations

SharedPreferences Compatibility

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

// SharedPreferences interface methods
String getString(String key, String defValue);
SharedPreferences.Editor putString(String key, String value);
SharedPreferences.Editor edit();
boolean commit();
void apply();

SharedPreferences API

Advanced Features

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

// Encryption management
String cryptKey();
boolean reKey(String cryptKey);

// Key expiration
boolean enableAutoKeyExpire(int expireDurationInSecond);
boolean encode(String key, String value, int expireDurationInSecond);

// Backup and restore
static boolean backupOneToDirectory(String mmapID, String dstDir, String rootPath);
static boolean restoreOneMMKVFromDirectory(String mmapID, String srcDir, String rootPath);

Advanced Features

Process Management and Synchronization

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

// Inter-process locking
void lock();
void unlock();
boolean tryLock();

// Synchronization
void sync();   // Synchronous save
void async();  // Asynchronous save

// Process mode checking
boolean isMultiProcess();

Process Management

NameSpace Management

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

// Create custom NameSpace
static NameSpace nameSpace(String dir);

// Get default NameSpace
static NameSpace defaultNameSpace();

NameSpace Management

Utility Types and Interfaces

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

// Content change notifications
interface MMKVContentChangeNotification;

// Native memory buffer for direct JNI access
class NativeBuffer;

// Error handling and log redirection
interface MMKVHandler;

Utility Types

Constants

// Process modes
static final int SINGLE_PROCESS_MODE = 1;
static final int MULTI_PROCESS_MODE = 2;
static final int READ_ONLY_MODE = 32;

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

// Expiration constants (in seconds)
static final int ExpireNever = 0;
static final int ExpireInMinute = 60;
static final int ExpireInHour = 3600;
static final int ExpireInDay = 86400;
static final int ExpireInMonth = 2592000;
static final int ExpireInYear = 31536000;

Core Types

// Log levels
enum MMKVLogLevel {
    LevelDebug,    // Debug level (not available in release)
    LevelInfo,     // Info level (default)  
    LevelWarning,  // Warning level
    LevelError,    // Error level
    LevelNone      // Disable all logging
}

// Recovery strategies for error handling
enum MMKVRecoverStrategic {
    OnErrorDiscard,  // Discard data on errors (default)
    OnErrorRecover   // Try to recover data on errors
}

// Custom library loader interface
interface LibLoader {
    void loadLibrary(String libName);
}