Modules API reference

RedisModule_Alloc

void *RedisModule_Alloc(size_t bytes);

Use like malloc(). Memory allocated with this function is reported in Redis INFO memory, used for keys eviction according to maxmemory settings and in general is taken into account as memory allocated by Redis. You should avoid using malloc().

RedisModule_Calloc

void *RedisModule_Calloc(size_t nmemb, size_t size);

Use like calloc(). Memory allocated with this function is reported in Redis INFO memory, used for keys eviction according to maxmemory settings and in general is taken into account as memory allocated by Redis. You should avoid using calloc() directly.

RedisModule_Realloc

void* RedisModule_Realloc(void *ptr, size_t bytes);

Use like realloc() for memory obtained with RedisModule_Alloc().

RedisModule_Free

void RedisModule_Free(void *ptr);

Use like free() for memory obtained by RedisModule_Alloc() and RedisModule_Realloc(). However you should never try to free with RedisModule_Free() memory allocated with malloc() inside your module.

RedisModule_Strdup

char *RedisModule_Strdup(const char *str);

Like strdup() but returns memory allocated with RedisModule_Alloc().

RedisModule_PoolAlloc

void *RedisModule_PoolAlloc(RedisModuleCtx *ctx, size_t bytes);

Return heap allocated memory that will be freed automatically when the module callback function returns. Mostly suitable for small allocations that are short living and must be released when the callback returns anyway. The returned memory is aligned to the architecture word size if at least word size bytes are requested, otherwise it is just aligned to the next power of two, so for example a 3 bytes request is 4 bytes aligned while a 2 bytes request is 2 bytes aligned.

There is no realloc style function since when this is needed to use the pool allocator is not a good idea.

The function returns NULL if bytes is 0.

RedisModule_GetApi

int RedisModule_GetApi(const char *funcname, void **targetPtrPtr);

Lookup the requested module API and store the function pointer into the target pointer. The function returns REDISMODULE_ERR if there is no such named API, otherwise REDISMODULE_OK.

This function is not meant to be used by modules developer, it is only used implicitly by including redismodule.h.

RedisModule_IsKeysPositionRequest

int RedisModule_IsKeysPositionRequest(RedisModuleCtx *ctx);

Return non-zero if a module command, that was declared with the flag “getkeys-api”, is called in a special way to get the keys positions and not to get executed. Otherwise zero is returned.

RedisModule_KeyAtPos

void RedisModule_KeyAtPos(RedisModuleCtx *ctx, int pos);

When a module command is called in order to obtain the position of keys, since it was flagged as “getkeys-api” during the registration, the command implementation checks for this special call using the RedisModule_IsKeysPositionRequest() API and uses this function in order to report keys, like in the following example:

if (RedisModule_IsKeysPositionRequest(ctx)) {
    RedisModule_KeyAtPos(ctx,1);
    RedisModule_KeyAtPos(ctx,2);
}

Note: in the example below the get keys API would not be needed since keys are at fixed positions. This interface is only used for commands with a more complex structure.

RedisModule_CreateCommand

int RedisModule_CreateCommand(RedisModuleCtx *ctx, const char *name, RedisModuleCmdFunc cmdfunc, const char *strflags, int firstkey, int lastkey, int keystep);

Register a new command in the Redis server, that will be handled by calling the function pointer ‘func’ using the RedisModule calling convention. The function returns REDISMODULE_ERR if the specified command name is already busy or a set of invalid flags were passed, otherwise REDISMODULE_OK is returned and the new command is registered.

This function must be called during the initialization of the module inside the RedisModule_OnLoad() function. Calling this function outside of the initialization function is not defined.

The command function type is the following:

 int MyCommand_RedisCommand(RedisModuleCtx *ctx, RedisModuleString **argv, int argc);

And is supposed to always return REDISMODULE_OK.

The set of flags ‘strflags’ specify the behavior of the command, and should be passed as a C string compoesd of space separated words, like for example “write deny-oom”. The set of flags are:

  • “write”: The command may modify the data set (it may also read from it).
  • “readonly”: The command returns data from keys but never writes.
  • “admin”: The command is an administrative command (may change replication or perform similar tasks).
  • “deny-oom”: The command may use additional memory and should be denied during out of memory conditions.
  • “deny-script”: Don’t allow this command in Lua scripts.
  • “allow-loading”: Allow this command while the server is loading data. Only commands not interacting with the data set should be allowed to run in this mode. If not sure don’t use this flag.
  • “pubsub”: The command publishes things on Pub/Sub channels.
  • “random”: The command may have different outputs even starting from the same input arguments and key values.
  • “allow-stale”: The command is allowed to run on slaves that don’t serve stale data. Don’t use if you don’t know what this means.
  • “no-monitor”: Don’t propoagate the command on monitor. Use this if the command has sensible data among the arguments.
  • “fast”: The command time complexity is not greater than O(log(N)) where N is the size of the collection or anything else representing the normal scalability issue with the command.
  • “getkeys-api”: The command implements the interface to return the arguments that are keys. Used when start/stop/step is not enough because of the command syntax.
  • “no-cluster”: The command should not register in Redis Cluster since is not designed to work with it because, for example, is unable to report the position of the keys, programmatically creates key names, or any other reason.

RedisModule_SetModuleAttribs

void RedisModule_SetModuleAttribs(RedisModuleCtx *ctx, const char *name, int ver, int apiver);

Called by RM_Init() to setup the ctx->module structure.

This is an internal function, Redis modules developers don’t need to use it.

RedisModule_Milliseconds

long long RedisModule_Milliseconds(void);

Return the current UNIX time in milliseconds.

RedisModule_AutoMemory

void RedisModule_AutoMemory(RedisModuleCtx *ctx);

Enable automatic memory management. See API.md for more information.

The function must be calle