一、模塊加載方法
1、在配置文件或者啟動參數里面通過<loadmodule /path/to/mymodule.so args>指令加載
2、Redis啟動后，通過<module load /path/to/mymodule.so args>指令加載，另外<module list>可以查詢當前所有已加載模塊。<module unload name>可以卸載已經加載的模塊，注意name為模塊的注冊名字，不一定和模塊文件名相同。
二、介紹
Redis模塊是一種動態庫，可以用與Redis內核相似的運行速度和特性來擴展Redis內核的功能。作者認為lua腳本只是組合Redis內核的現有功能，但是Redis模塊則可以擴展Redis內核的功能。主要提供以下幾個方面的擴展
1、可以如lua腳本或者client一樣，通過RedisModule_Call接口直接執行redis命令並獲取執行結果。Redis稱呼這種API為高層API。
2、可以通過RedisModule_OpenKey接口，獲取底層鍵，並根據鍵的類型以及各類型提供的模塊操作接口進行底層操作。
3、自動內存管理(Automatic memory management)，可以在回調函數中，調用RedisModule_AutoMemory打開自動內存管理功能，這樣隨后分配的RedisModuleString對象、open key等，redis會記錄下來，當回調函數返回的時候，redis會把這些資源自動釋放調。這意味着不能在自動內存管理打開的情況下，創建RedisModuleString等對象來初始化全局變量。
4、redis本地類型(native types support)創建。通過提供RDB保存、RDB加載、AOF重寫等回調函數，在Redis模塊中可以創建類似redis內部dict、list之類的數據類型。例如可以在模塊中創建一個鏈表，並提供對應的回調函數，這樣redis在保存RDB文件的時候，就可以把模塊中的數據保存在RDB中，在redis啟動從rdb中加載數據的時候，進而可以恢復模塊數據狀態。
5、阻塞命令。在redis模塊中可以將client阻塞，並設置超時時間。以實現類似BLPOP的阻塞命令。
三、一個redis模塊示例
如下代碼一個簡單的redis模塊示例，添加了一個hello.rand命令。在模塊加載的時候，打印出傳入的參數，當執行hello.rand命令的時候，同樣會打印出傳入的命令參數，並返回生成的一個隨機數。關於下面的代碼，有兩個點需要說明
1、RedisModule_OnLoad是每個Redis模塊的入口函數，在加載模塊的時候，就是通過查找這個函數的入口地址來開始執行redis模塊代碼的。
2、RedisModule_Init是在調用redis模塊API之前必須調用的初始化函數。一般應放在RedisModule_OnLoad的最開始位置。如果沒有執行RedisModule_Init，就調用redis模塊的API，則會產生空指針異常。
后面介紹redis實現的時候會進一步介紹上面的兩點
#include "../../src/redismodule.h"#include <stdlib.h>#include <string.h>void HelloRedis_LogArgs(RedisModuleString **argv, int argc){ for (int j = 0; j < argc; j++) { const char *s = RedisModule_StringPtrLen(argv[j],NULL); printf("ARGV[%d] = %s\n", j, s); }}int HelloRedis_RandCommand(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) { HelloRedis_LogArgs(argv,argc); RedisModule_ReplyWithLongLong(ctx,rand()); return REDISMODULE_OK;}int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) { if (RedisModule_Init(ctx,"hello",1,REDISMODULE_APIVER_1) == REDISMODULE_ERR) return REDISMODULE_ERR; HelloRedis_LogArgs(argv,argc); if (RedisModule_CreateCommand(ctx,"hello.rand", HelloRedis_RandCommand,"readonly",0,0,0)== REDISMODULE_ERR) return REDISMODULE_ERR; return REDISMODULE_OK;}
上面的模塊編譯執行后，client側執行如下命令來進行測試。
127.0.0.1:6379> module load modules/hellomodule/helloRedis.so helloarg1 helloarg2 OK127.0.0.1:6379> module list1) 1) "name" 2) "hello" 3) "ver" 4) (integer) 1127.0.0.1:6379> hello.rand(integer) 1315916238127.0.0.1:6379> hello.rand(integer) 1420937835127.0.0.1:6379> hello.rand arg test(integer) 543546598127.0.0.1:6379> module unload helloOK
redis server端顯示的如下內容。
ARGV[0] = helloarg1ARGV[1] = helloarg27779:M 19 Dec 14:33:17.032 * Module 'hello' loaded from modules/hellomodule/helloRedis.soARGV[0] = hello.randARGV[0] = hello.randARGV[0] = hello.randARGV[1] = argARGV[2] = test7779:M 19 Dec 14:34:13.604 * Module hello unloaded
四、redis模塊管理相關數據結構
Redis模塊管理涉及到的相關數據結構如下
struct RedisModule { void *handle; /* dlopen() 返回的handle. */ char *name; /* 模塊名字 */ int ver; /* 模塊版本*/ int apiver; /* 模塊API版本*/ list *types; /* 用來保存模塊的數據類型信息 */};typedef struct RedisModule RedisModule;static dict *modules; /* 全局變量 用來進行module_name(SDS) -> RedisModule ptr的hash查找*/struct moduleLoadQueueEntry { sds path; int argc; robj **argv;};struct redisServer { .... list *loadmodule_queue; //在redis啟動的時候，用來保存命令行或者配置文件中的模塊相關配置，每個節點是一個struct moduleLoadQueueEntry dict *moduleapi; /* 導出的模塊API名字與API地址的映射 后面介紹*/ ....};struct redisServer server; static list *moduleUnblockedClients; //當模塊中阻塞的client被RedisModule_UnblockClient接口解除阻塞的時候，會放入這個鏈表，后面統一處理
其中有幾個需要額外說明一下
1、RedisModule中的types成員用來保存Redis模塊中定義的native types，每個數據類型對應一個節點。每個節點的類型為struct RedisModuleType，里面包含了rdb_load、rdb_save、aof_rewrite等回調函數，這里沒有給出struct RedisModuleType。
2、server.loadmodule_queue這個隊列里面保存了redis通過命令行或者配置文件傳入的模塊加載信息，每個節點類型為struct moduleLoadQueueEntry。如配置文件指定"module load /path/to/mymodule.so arg1 arg2"，則會構建一個struct moduleLoadQueueEntry，其中path成員為包含/path/to/mymodule.so的SDS，argc=2，argv則包含兩個robj對象指針，robj對象分別包含着"arg1"和"arg2"。
為什么沒有在加載配置的時候，直接加載模塊，而是先保存到隊列中呢？原因是在加載配置的時候，redis server還沒有完成初始化，加載模塊的時候，會調用模塊中的RedisModule_OnLoad函數，如果此時模塊訪問Redis內部數據，那么可能會訪問到無效的數據。因此需要加載的模塊需要先保存在隊列中，等redis初始化完畢后，在從隊列中依次加載對應的模塊。
3、關於moduleUnblockedClients，當模塊調用RedisModule_UnblockClient的時候，會先把要解除阻塞的client加入到這個鏈表中，等待當前redis的文件事件和時間事件處理完畢后，等待下一次事件前(beforeSleep->moduleHandleBlockedClients)，來集中處理(例如調用模塊注冊的reply_callback函數等)。
這里為什么沒有直接在RedisModule_UnblockClient中處理，而是先添加到一個鏈表中，后面由redis內核處理呢？原因是RedisModule_UnblockClient在模塊中支持線程調用，而redis內核事件處理是單線程的，因此為了避免線程競爭會先把待解除阻塞的client放入到moduleUnblockedClients鏈表中，后續交由redis內核處理。
五、module命令實現
接着說一下module命令中load、unload、list等實現
首先通過配置文件、命令行或者module load命令加載模塊的時候，如下執行
/* 加載一個模塊並初始化. 成功返回 C_OK , 失敗返回C_ERR */int moduleLoad(const char *path, void **module_argv, int module_argc) { int (*onload)(void *, void **, int); void *handle; RedisModuleCtx ctx = REDISMODULE_CTX_INIT; //加載動態庫 handle = dlopen(path,RTLD_NOW|RTLD_LOCAL); if (handle == NULL) { return C_ERR; } //查找動態庫中入口函數RedisModule_OnLoad的地址 onload = (int (*)(void *, void **, int))(unsigned long) dlsym(handle,"RedisModule_OnLoad"); if (onload == NULL) { return C_ERR; } //執行模塊中的RedisModule_OnLoad入口函數 if (onload((void*)&ctx,module_argv,module_argc) == REDISMODULE_ERR) { if (ctx.module) moduleFreeModuleStructure(ctx.module); dlclose(handle); return C_ERR; } /* Redis module 加載成功，注冊到modules全局字典中 */ dictAdd(modules,ctx.module->name,ctx.module); ctx.module->handle = handle; /*注意這里會把ctx釋放掉，后面需要的時候，會根據modules字典中的查找到的模塊信息，構造一個ctx *這意味着在模塊函數中的ctx入參是一個堆棧上的變量， *例如通過RedisModule_AutoMemory設置ctx自動內存管理的時候，只是當次有效*/ moduleFreeContext(&ctx); return C_OK;}
module unload命令卸載一個模塊時候，執行如下簡化代碼
/* 卸載一個模塊，成功返回C_OK,失敗返回C_ERR */int moduleUnload(sds name) { struct RedisModule *module = dictFetchValue(modules,name); if (module == NULL) { return REDISMODULE_ERR; } //如果模塊導入了本地數據類型，則不允許卸載 if (listLength(module->types)) { return REDISMODULE_ERR; } /* 模塊可以向Redis服務器注冊新的Redis命令，卸載模塊的時候，需要取消之前注冊的命令 */ unregister_cmds_of_module(module); /* 卸載動態庫 */ if (dlclose(module->handle) == -1) { char *error = dlerror(); if (error == NULL) error = "Unknown error"; } /* 從全局modules字典中刪除模塊 同時釋放module->name*/ dictDelete(modules,module->name); module->name = NULL; //釋放module占用的內存 moduleFreeModuleStructure(module); return REDISMODULE_OK;}
module list命令執行如下簡化代碼
/* modules list簡化代碼 */void moduleList(sds name) { dictIterator *di = dictGetIterator(modules); dictEntry *de; addReplyMultiBulkLen(c,dictSize(modules)); //遍歷modules字典，獲取每個模塊的名字和版本 while ((de = dictNext(di)) != NULL) { sds name = dictGetKey(de); struct RedisModule *module = dictGetVal(de); addReplyMultiBulkLen(c,4); addReplyBulkCString(c,"name"); addReplyBulkCBuffer(c,name,sdslen(name)); addReplyBulkCString(c,"ver"); addReplyLongLong(c,module->ver); } dictReleaseIterator(di);}
六、模塊導出符號與Redis core函數映射
在Redis提供給模塊的API中，API的名字都是類似RedisModule_<funcname>的形式，實際對應Redis core中的RM_<funcname>函數。目前只有一個例外就是RedisModule_Init這個模塊API在Redis core中的名字也是RedisModule_Init。上面我們講過，RedisModule_Init應該是模塊入口RedisModule_OnLoad中第一個調用的函數。而RedisModule_OnLoad的工作就是完成了RedisModule_<funcname>與RM_<funcname>之間的關聯建立關系。
下面我們首先以上面示例模塊中的RedisModule_CreateCommand這個模塊API為例，說明怎么關聯到RM_CreateCommand上的，然后在說明為什么這樣設計。
1、RedisModule_<funcname>與RM_<funcname>關聯建立過程
1.1、首先在Redis啟動的時候，會執行下面的初始化代碼
int moduleRegisterApi(const char *funcname, void *funcptr) { return dictAdd(server.moduleapi, (char*)funcname, funcptr);}#define REGISTER_API(name) \ moduleRegisterApi("RedisModule_" #name, (void *)(unsigned long)RM_ ## name)/* Register all the APIs we export. Keep this function at the end of the * file so that's easy to seek it to add new entries. */void moduleRegisterCoreAPI(void) { server.moduleapi = dictCreate(&moduleAPIDictType,NULL); ... //其他的接口同樣需要通過REGISTER_API來注冊 REGISTER_API(CreateCommand); REGISTER_API(SetModuleAttribs); ...}
上面代碼等效於
//在server.moduleapi中將字符串"RedisModule_<funcname>"與函數RM_<funcname>的地址建立關聯dictAdd(server.moduleapi, "RedisModule_CreateCommand", RM_CreateCommand)dictAdd(server.moduleapi, "RedisModule_SetModuleAttribs", RM_SetModuleAttribs)
1.2、在模塊源碼中包含redismodule.h頭文件的時候，會把下面的代碼包含進來
#define REDISMODULE_API_FUNC(x) (*x)//其他的模塊接口同樣需要通過REDISMODULE_API_FUNC來定義與RM_<funcname>一致的函數指針RedisModule_<funcname>int REDISMODULE_API_FUNC(RedisModule_CreateCommand)(RedisModuleCtx *ctx, const char *name, RedisModuleCmdFunc cmdfunc, const char *strflags, int firstkey, int lastkey, int keystep);int REDISMODULE_API_FUNC(RedisModule_SetModuleAttribs)(RedisModuleCtx *ctx, const char *name, int ver, int apiver);#define REDISMODULE_GET_API(name) \ RedisModule_GetApi("RedisModule_" #name, ((void **)&RedisModule_ ## name))static int RedisModule_Init(RedisModuleCtx *ctx, const char *name, int ver, int apiver) { void *getapifuncptr = ((void**)ctx)[0]; RedisModule_GetApi = (int (*)(const char *, void *)) (unsigned long)getapifuncptr; ... //其他模塊接口同樣需要通過REDISMODULE_GET_API來初始化RedisModule_<funcname>指針 REDISMODULE_GET_API(CreateCommand); REDISMODULE_GET_API(SetModuleAttribs); ... RedisModule_SetModuleAttribs(ctx,name,ver,apiver); return REDISMODULE_OK;}
上面代碼進行宏展開后等效如下
//定義與RM_<funcname>類型一致的函數指針RedisModule_<funcname>int (*RedisModule_CreateCommand)(RedisModuleCtx *ctx, const char *name, RedisModuleCmdFunc cmdfunc, const char *strflags, int firstkey, int lastkey, int keystep);int (*RedisModule_SetModuleAttribs)(RedisModuleCtx *ctx, const char *name, int ver, int apiver);static int RedisModule_Init(RedisModuleCtx *ctx, const char *name, int ver, int apiver) { void *getapifuncptr = ((void**)ctx)[0]; RedisModule_GetApi = (int (*)(const char *, void *)) (unsigned long)getapifuncptr; ... //其他模塊接口同樣需要通過REDISMODULE_GET_API來初始化RedisModule_<funcname>指針 RedisModule_GetApi("RedisModule_CreateCommand",((void **)&RedisModule_CreateCommand); RedisModule_GetApi("RedisModule_SetModuleAttribs",((void **)&RedisModule_SetModuleAttribs); ... RedisModule_SetModuleAttribs(ctx,name,ver,apiver); return REDISMODULE_OK;}
1.3、在上面moduleLoad加載模塊的時候，我們看到會傳遞RedisModuleCtx ctx = REDISMODULE_CTX_INIT作為入參，調用RedisModule_OnLoad，並在RedisModule_OnLoad中調用RedisModule_Init。
#define REDISMODULE_CTX_INIT {(void*)(unsigned long)&RM_GetApi, NULL, NULL, NULL, 0, 0, 0, NULL, 0, NULL, NULL, 0, NULL}/* 查找模塊請求的API，並保存在targetPtrPtr中 */int RM_GetApi(const char *funcname, void **targetPtrPtr) { dictEntry *he = dictFind(server.moduleapi, funcname); if (!he) return REDISMODULE_ERR; *targetPtrPtr = dictGetVal(he); return REDISMODULE_OK;}
因此在函數RedisModule_Init實際執行的時候，相當於把RedisModule_<funcname>指針初始化為RM_<funcname>函數的地址了。因此隨后在模塊中調用RedisModule_<funcname>的時候，實際上調用的是RM_<funcname>。
2、為什么采用這種設計？
實際上在redismodule.h頭文件或者模塊源碼中直接extern RM_<funcname>，也是可以直接訪問RM_<funcname>這個函數的。那么為什么要在每個模塊的源碼中定一個指向RM_<funcname>的函數指針RedisModule_<funcname>，並通過RedisModule_<funcname>來訪問模塊API呢？
主要是考慮到后續升級的靈活性，模塊可以有不同的API版本，雖然目前API版本只有一個，但是假如后續升級后，Redis支持了新版本的API。那么當不同API版本的模塊向Redis注冊的時候，Redis內核就可以根據注冊的API版本，來把不同模塊中的函數指針指向不同的API實現函數了。這類似以面向對象中依賴於抽象而不是依賴具體的設計思路。
補充說明：
1、在redis源碼src/modules目錄下給出了一些redis模塊相關的示例和說明文檔，是不錯的學習資料。
2、https://github.com/antirez/redis/commit/85919f80ed675dad7f2bee25018fec2833b8bbde