From e7495e02346a76cd7fd747258f61ed6db22010ad Mon Sep 17 00:00:00 2001 From: Dvir Volk Date: Fri, 16 Dec 2016 15:15:56 +0200 Subject: [PATCH] Updated documents Signed-off-by: Dvir Volk --- API.md | 523 ++++++----- FUNCTIONS.md | 2387 +++++++++++++++++++++----------------------------- 2 files changed, 1302 insertions(+), 1608 deletions(-) diff --git a/API.md b/API.md index 1306419..3ac6a46 100644 --- a/API.md +++ b/API.md @@ -1,52 +1,62 @@ -Redis Modules API reference manual +Redis Modules: an introduction to the API === -Redis modules make possible the extension of Redis functionality using -external modules, by creating new Redis commands with performance and -features similar to what can be done inside the core itself. +The modules documentation is composed of the following files: -Redis modules are dynamic libraries loaded into Redis at startup or -using the `MODULE LOAD` command. Redis exports a C API, in the +* `INTRO.md` (this file). An overview about Redis Modules system and API. It's a good idea to start your reading here. +* `API.md` is generated from module.c top comments of RedisMoule functions. It is a good reference in order to understand how each function works. +* `TYPES.md` covers the implementation of native data types into modules. +* `BLOCK.md` shows how to write blocking commands that will not reply immediately, but will block the client, without blocking the Redis server, and will provide a reply whenever will be possible. + +Redis modules make possible to extend Redis functionality using external +modules, implementing new Redis commands at a speed and with features +similar to what can be done inside the core itself. + +Redis modules are dynamic libraries, that can be loaded into Redis at +startup or using the `MODULE LOAD` command. Redis exports a C API, in the form of a single C header file called `redismodule.h`. Modules are meant -to be written in C, or any language with C binding functionality -like C++. +to be written in C, however it will be possible to use C++ or other languages +that have C binding functionalities. -Modules are Redis-version agnostic: a given module does not need to be -designed, or recompiled, in order to run with a specific version of -Redis. In addition, they are registered using a specific Redis modules -API version. The current API version is "1". +Modules are designed in order to be loaded into different versions of Redis, +so a given module does not need to be designed, or recompiled, in order to +run with a specific version of Redis. For this reason, the module will +register to the Redis core using a specific API version. The current API +version is "1". -This document describes the alpha version of Redis modules. API, -functionality and other details may change in the future. +This document is about an alpha version of Redis modules. API, functionalities +and other details may change in the future. # Loading modules -In order to test a new Redis module, use the following `redis.conf` -configuration directive: +In order to test the module you are developing, you can load the module +using the following `redis.conf` configuration directive: loadmodule /path/to/mymodule.so -Load a module at runtime with the following command: +It is also possible to load a module at runtime using the following command: MODULE LOAD /path/to/mymodule.so -To list all loaded modules, use: +In order to list all loaded modules, use: MODULE LIST -Finally, unload (or reload) a module using the following command: +Finally, you can unload (and later reload if you wish) a module using the +following command: MODULE UNLOAD mymodule -Note that `mymodule` is the name the module used to register itself -with the Redis core, and **is not** the filename without the -`.so` suffix. The name can be obtained using `MODULE LIST`. It is -recommended to use the same filename for the dynamic library and module. +Note that `mymodule` above is not the filename without the `.so` suffix, but +instead, the name the module used to register itself into the Redis core. +The name can be obtained using `MODULE LIST`. However it is good practice +that the filename of the dynamic library is the same as the name the module +uses to register itself into the Redis core. -# A Hello World module +# The simplest module you can write -In order illustrate the basic components of a module, the following -implements a command that outputs a random number. +In order to show the different parts of a module, here we'll show a very +simple module that implements a command that outputs a random number. #include "redismodule.h" #include @@ -56,7 +66,7 @@ implements a command that outputs a random number. return REDISMODULE_OK; } - int RedisModule_OnLoad(RedisModuleCtx *ctx) { + int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) { if (RedisModule_Init(ctx,"helloworld",1,REDISMODULE_APIVER_1) == REDISMODULE_ERR) return REDISMODULE_ERR; @@ -68,17 +78,21 @@ implements a command that outputs a random number. } The example module has two functions. One implements a command called -`HELLOWORLD.RAND`. This function is specific to that module. In -addition, `RedisModule_OnLoad()` must be present in each Redis module. -It is the entry point for module initialization, and registers its -commands and other private data structures. - -In order to avoid namespace collisions, module commands should use the -dot-notation, for example, `HELLOWORLD.RAND`. - -Namespace collisions will cause `RedisModule_CreateCommand` to fail in -one or more modules. Loading will abort and an error condition -returned. +HELLOWORLD.RAND. This function is specific of that module. However the +other function called `RedisModule_OnLoad()` must be present in each +Redis module. It is the entry point for the module to be initialized, +register its commands, and potentially other private data structures +it uses. + +Note that it is a good idea for modules to call commands with the +name of the module followed by a dot, and finally the command name, +like in the case of `HELLOWORLD.RAND`. This way it is less likely to +have collisions. + +Note that if different modules have colliding commands, they'll not be +able to work in Redis at the same time, since the function +`RedisModule_CreateCommand` will fail in one of the modules, so the module +loading will abort returning an error condition. # Module initialization @@ -89,9 +103,9 @@ The following is the function prototype: int RedisModule_Init(RedisModuleCtx *ctx, const char *modulename, int module_version, int api_version); -The `Init` function announces to the Redis core that the module has a -given name, its version (reported by `MODULE LIST`), and that it uses -a specific version of the API. +The `Init` function announces the Redis core that the module has a given +name, its version (that is reported by `MODULE LIST`), and that is willing +to use a specific version of the API. If the API version is wrong, the name is already taken, or there are other similar errors, the function will return `REDISMODULE_ERR`, and the module @@ -100,15 +114,15 @@ similar errors, the function will return `REDISMODULE_ERR`, and the module Before the `Init` function is called, no other API function can be called, otherwise the module will segfault and the Redis instance will crash. -The second function called, `RedisModule_CreateCommand`, registers -commands with the Redis core. The following is the prototype: +The second function called, `RedisModule_CreateCommand`, is used in order +to register commands into the Redis core. The following is the prototype: int RedisModule_CreateCommand(RedisModuleCtx *ctx, const char *cmdname, RedisModuleCmdFunc cmdfunc); -Most Redis modules API calls have the `context` of the module -as first argument, in order to reference the calling module's context -and the client executing a given command. +As you can see, most Redis modules API calls all take as first argument +the `context` of the module, so that they have a reference to the module +calling it, to the command and client executing a given command, and so forth. To create a new command, the above function needs the context, the command name, and the function pointer of the function implementing the command, @@ -121,9 +135,9 @@ The command function arguments are just the context, that will be passed to all the other API calls, the command argument vector, and total number of arguments, as passed by the user. -The arguments are provided as pointers to a specific data type, the -`RedisModuleString`. This is an opaque data type with API functions -enabling access and use. Direct access to its fields is never needed. +As you can see, the arguments are provided as pointers to a specific data +type, the `RedisModuleString`. This is an opaque data type you have API +functions to access and use, direct access to its fields is never needed. Zooming into the example command implementation, we can find another call: @@ -134,29 +148,52 @@ exactly like other Redis commands do, like for example `INCR` or `SCARD`. # Setup and dependencies of a Redis module -Redis modules do not depend on Redis or 3rd party libraries, nor do they +Redis modules don't depend on Redis or some other library, nor they need to be compiled with a specific `redismodule.h` file. In order to create a new module, just copy a recent version of `redismodule.h` in your source tree, link all the libraries you want, and create -a dynamic library and export the `RedisModule_OnLoad()` function symbol. +a dynamic library having the `RedisModule_OnLoad()` function symbol +exported. The module will be able to load into different versions of Redis. +# Passing configuration parameters to Redis modules + +When the module is loaded with the `MODULE LOAD` command, or using the +`loadmodule` directive in the `redis.conf` file, the user is able to pass +configuration parameters to the module by adding arguments after the module +file name: + + loadmodule mymodule.so foo bar 1234 + +In the above example the strings `foo`, `bar` and `123` will be passed +to the module `OnLoad()` function in the `argv` argument as an array +of RedisModuleString pointers. The number of arguments passed is into `argc`. + +The way you can access those strings will be explained in the rest of this +document. Normally the module will store the module configuration parameters +in some `static` global variable that can be accessed module wide, so that +the configuration can change the behavior of different commands. + # Working with RedisModuleString objects The command argument vector `argv` passed to module commands, and the return value of other module APIs functions, are of type `RedisModuleString`. -Most often Redis module strings are passed directly to other API calls. -However, a number of API functions enable direct access to the string -object. For example, +Usually you directly pass module strings to other API calls, however sometimes +you may need to directly access the string object. + +There are a few functions in order to work with string objects: const char *RedisModule_StringPtrLen(RedisModuleString *string, size_t *len); -returns a pointer to `string` and sets its length in `len`. The `const` -modifier prevents direct modification. +The above function accesses a string by returning its pointer and setting its +length in `len`. +You should never write to a string object pointer, as you can see from the +`const` pointer qualifier. -New string objects are created using the following API: +However, if you want, you can create new string objects using the following +API: RedisModuleString *RedisModule_CreateString(RedisModuleCtx *ctx, const char *ptr, size_t len); @@ -165,12 +202,14 @@ call to `RedisModule_FreeString()`: void RedisModule_FreeString(RedisModuleString *str); -Alternatively, the automatic memory management API, covered later in -this document, can be employed to automatically free string handles. +However if you want to avoid having to free strings, the automatic memory +management, covered later in this document, can be a good alternative, by +doing it for you. Note that the strings provided via the argument vector `argv` never need -to be freed. Only strings created within a module need to be freed, or -new strings returned by other APIs where specified. +to be freed. You only need to free new strings you create, or new strings +returned by other APIs, where it is specified that the returned string must +be freed. ## Creating strings from numbers or parsing strings as numbers @@ -189,44 +228,46 @@ Similarly in order to parse a string as a number: ## Accessing Redis keys from modules Most Redis modules, in order to be useful, have to interact with the Redis -data space. An exception would be an ID generator that never accesses -Redis keys. Redis modules have two different APIs in order to -access the Redis data space. A **low level API** providing very +data space (this is not always true, for example an ID generator may +never touch Redis keys). Redis modules have two different APIs in order to +access the Redis data space, one is a low level API that provides very fast access and a set of functions to manipulate Redis data structures. -A **high level API** is provided to allow calling Redis commands and -retrieving results, similar to how Lua scripts access Redis. +The other API is more high level, and allows to call Redis commands and +fetch the result, similarly to how Lua scripts access Redis. The high level API is also useful in order to access Redis functionalities that are not available as APIs. -In general, module developers should prefer the low level API, because commands +In general modules developers should prefer the low level API, because commands implemented using the low level API run at a speed comparable to the speed of native Redis commands. However there are definitely use cases for the higher level API. For example often the bottleneck could be processing the data and not accessing it. -Also note that in some cases the low level API is is as simple as the -high level API. +Also note that sometimes using the low level API is not harder compared to +the higher level one. # Calling Redis commands -The high level API to access Redis combines the `RedisModule_Call()` -function with the functions needed to access the reply object returned -by `Call()`. +The high level API to access Redis is the sum of the `RedisModule_Call()` +function, together with the functions needed in order to access the +reply object returned by `Call()`. -`RedisModule_Call` uses a special calling convention, with a format -specifier used to define the types of objects passed as arguments. +`RedisModule_Call` uses a special calling convention, with a format specifier +that is used to specify what kind of objects you are passing as arguments +to the function. -Redis commands are invoked using a command name and a list of arguments. -However, when calling commands, the arguments may originate from different +Redis commands are invoked just using a command name and a list of arguments. +However when calling commands, the arguments may originate from different kind of strings: null-terminated C strings, RedisModuleString objects as received from the `argv` parameter in the command implementation, binary safe C buffers with a pointer and a length, and so forth. -To call `INCRBY` using as first argument (the key) a string received in -the argument vector `argv`, which is an array of RedisModuleString -object pointers, and a C string representing the number "10" as a second -argument (the increment), use the following function call: +For example if I want to call `INCRBY` using a first argument (the key) +a string received in the argument vector `argv`, which is an array +of RedisModuleString object pointers, and a C string representing the +number "10" as second argument (the increment), I'll use the following +function call: RedisModuleCallReply *reply; reply = RedisModule_Call(ctx,"INCR","sc",argv[1],"10"); @@ -248,15 +289,13 @@ This is the full list of format specifiers: * **v** -- Array of RedisModuleString objects. * **!** -- This modifier just tells the function to replicate the command to slaves and AOF. It is ignored from the point of view of arguments parsing. -The function returns either a `RedisModuleCallReply` object on success, -or NULL on error. +The function returns a `RedisModuleCallReply` object on success, on +error NULL is returned. -NULL is returned when the command name is invalid, the format specifier -uses characters that are not recognized, or when the command is called -with the wrong number of arguments. In the above cases the `errno` var -is set to `EINVAL`. NULL is also returned when, in an instance with -Cluster enabled, the target keys are non local hash slots. In this -case `errno` is set to `EPERM`. +NULL is returned when the command name is invalid, the format specifier uses +characters that are not recognized, or when the command is called with the +wrong number of arguments. In the above cases the `errno` var is set to `EINVAL`. NULL is also returned when, in an instance with Cluster enabled, the target +keys are about non local hash slots. In this case `errno` is set to `EPERM`. ## Working with RedisModuleCallReply objects. @@ -288,8 +327,7 @@ is used: size_t reply_len = RedisModule_CallReplyLength(reply); -In order to obtain the value of an integer reply, the following function -is used, as already shown in the example above: +In order to obtain the value of an integer reply, the following function is used, as already shown in the example above: long long reply_integer_val = RedisModule_CallReplyInteger(reply); @@ -304,51 +342,53 @@ Sub elements of array replies are accessed this way: The above function returns NULL if you try to access out of range elements. Strings and errors (which are like strings but with a different type) can -be accessed in the following way, making sure to never write to -the resulting pointer (that is returned as as const pointer so that -misusing must be pretty explicit):: +be accessed using in the following way, making sure to never write to +the resulting pointer (that is returned as as `const` pointer so that +misusing must be pretty explicit): size_t len; - const char *ptr = RedisModule_CallReplyStringPtr(reply,&len); + char *ptr = RedisModule_CallReplyStringPtr(reply,&len); If the reply type is not a string or an error, NULL is returned. RedisCallReply objects are not the same as module string objects -(RedisModuleString types). When an API function expects a module string, -the following function can be employed to create a new -`RedisModuleString` object from a call reply of type string, error or -integer: +(RedisModuleString types). However sometimes you may need to pass replies +of type string or integer, to API functions expecting a module string. - RedisModuleString *mystr = RedisModule_CreateStringFromCallReply(myreply); +When this is the case, you may want to evaluate if using the low level +API could be a simpler way to implement your command, or you can use +the following function in order to create a new string object from a +call reply of type string, error or integer: -Alternatively, one could evaluate whether using the low level API is as -simple (and potentially faster). + RedisModuleString *mystr = RedisModule_CreateStringFromCallReply(myreply); -If the reply is not of the right type, NULL is returned. The returned -string object should be released with `RedisModule_FreeString()`, or by -enabling automatic memory management (see section below). +If the reply is not of the right type, NULL is returned. +The returned string object should be released with `RedisModule_FreeString()` +as usually, or by enabling automatic memory management (see corresponding +section). # Releasing call reply objects -Reply objects must be freed using `RedisModule_FreeCallRelpy`. For arrays, -only the top level reply needs to be freed, but not the nested replies. -Currently, the module implementation provides protection in order to avoid -crashing if a nested reply object is freed on error--however, *this -protective feature may not be available in future versions, and should -not be considered part of the API*. +Reply objects must be freed using `RedisModule_FreeCallReply`. For arrays, +you need to free only the top level reply, not the nested replies. +Currently the module implementation provides a protection in order to avoid +crashing if you free a nested reply object for error, however this feature +is not guaranteed to be here forever, so should not be considered part +of the API. -Automatic memory management can take care of freeing replies (see -section below). Alternatively, memory can be released ASAP. +If you use automatic memory management (explained later in this document) +you don't need to free replies (but you still could if you wish to release +memory ASAP). ## Returning values from Redis commands Like normal Redis commands, new commands implemented via modules must be -able to return values to the caller. Towards this end, The API exports a -set of functions in order to return the usual Redis protocol types, and -arrays of such types (as elemented). Also, errors can be returned with any -error code and string, where the error code is the initial uppercase -letters in the error message--for example, the "BUSY" string in the -"BUSY the sever is busy" error message. +able to return values to the caller. The API exports a set of functions for +this goal, in order to return the usual types of the Redis protocol, and +arrays of such types as elemented. Also errors can be returned with any +error string and code (the error code is the initial uppercase letters in +the error message, like the "BUSY" string in the "BUSY the sever is busy" error +message). All the functions to send a reply to the client are called `RedisModule_ReplyWith`. @@ -369,8 +409,8 @@ We already saw how to reply with a long long in the examples above: RedisModule_ReplyWithLongLong(ctx,12345); -To reply with a simple string like "OK", that can't contain binary -values or newlines, use: +To reply with a simple string, that can't contain binary values or newlines, +(so it's suitable to send small words, like "OK") we use: RedisModule_ReplyWithSimpleString(ctx,"OK"); @@ -381,18 +421,18 @@ two different functions: int RedisModule_ReplyWithString(RedisModuleCtx *ctx, RedisModuleString *str); -The first function gets a C pointer and length. The second a RedisModuleString +The first function gets a C pointer and length. The second a RedisMoudleString object. Use one or the other depending on the source type you have at hand. -In order to reply with an array, use a function to emit the array -length, followed by as many calls to the above functions as there are -elements in the array: +In order to reply with an array, you just need to use a function to emit the +array length, followed by as many calls to the above functions as the number +of elements of the array are: RedisModule_ReplyWithArray(ctx,2); RedisModule_ReplyWithStringBuffer(ctx,"age",3); RedisModule_ReplyWithLongLong(ctx,22); -Returning nested arrays is easy--the nested array element just uses another +To return nested arrays is easy, your nested array element just uses another call to `RedisModule_ReplyWithArray()` followed by the calls to emit the sub array elements. @@ -401,16 +441,16 @@ sub array elements. Sometimes it is not possible to know beforehand the number of items of an array. As an example, think of a Redis module implementing a FACTOR command that given a number outputs the prime factors. Instead of -factorializing the number, storing the prime factors in an array, and -then producing the command reply, a better solution is to start an array +factorializing the number, storing the prime factors into an array, and +later produce the command reply, a better solution is to start an array reply where the length is not known, and set it later. This is accomplished with a special argument to `RedisModule_ReplyWithArray()`: RedisModule_ReplyWithArray(ctx, REDISMODULE_POSTPONED_ARRAY_LEN); -The above call starts an array reply, and more `ReplyWith` calls can -then be used to produce the array items. Finally in order to set the -length use the following call: +The above call starts an array reply so we can use other `ReplyWith` calls +in order to produce the array items. Finally in order to set the length +se use the following call: RedisModule_ReplySetArrayLength(ctx, number_of_items); @@ -428,7 +468,7 @@ to this: Another common use case for this feature is iterating over the arrays of some collection and only returning the ones passing some kind of filtering. -It is possible to have multiple nested arrays with a postponed reply. +It is possible to have multiple nested arrays with postponed reply. Each call to `SetArray()` will set the length of the latest corresponding call to `ReplyWithArray()`: @@ -444,7 +484,8 @@ This creates a 100 items array having as last element a 10 items array. # Arity and type checks Often commands need to check that the number of arguments and type of the key -is correct. To report a wrong arity, use `RedisModule_WrongArity()`: +is correct. In order to report a wrong arity, there is a specific function +called `RedisModule_WrongArity()`. The usage is trivial: if (argc != 2) return RedisModule_WrongArity(ctx); @@ -466,8 +507,8 @@ is of the expected type, or if it's empty. ## Low level access to keys -Low level access to keys enable operations on value objects associated -with keys directly, with a speed similar to what Redis uses internally to +Low level access to keys allow to perform operations on value objects associated +to keys directly, with a speed similar to what Redis uses internally to implement the built-in commands. Once a key is opened, a key pointer is returned that will be used with all the @@ -477,44 +518,39 @@ associated value. Because the API is meant to be very fast, it cannot do too many run-time checks, so the user must be aware of certain rules to follow: -* Opening the same key multiple times where at least one instance is -opened for writing, is undefined and may lead to crashes. -* While a key is open, it should only be accessed via the low level key -API. For example opening a key, then calling DEL on the same key using -the `RedisModule_Call()` API will result in a crash. However it is safe -to open a key, perform some operation with the low level API, close it, -then use other APIs to manage the same key, and later opening it again -to do some more work. - -In order to open a key the `RedisModule_OpenKey` function is used. It -returns a key pointer, used in subsequent calls to access and modify +* Opening the same key multiple times where at least one instance is opened for writing, is undefined and may lead to crashes. +* While a key is open, it should only be accessed via the low level key API. For example opening a key, then calling DEL on the same key using the `RedisModule_Call()` API will result into a crash. However it is safe to open a key, perform some operation with the low level API, closing it, then using other APIs to manage the same key, and later opening it again to do some more work. + +In order to open a key the `RedisModule_OpenKey` function is used. It returns +a key pointer, that we'll use with all the next calls to access and modify the value: RedisModuleKey *key; key = RedisModule_OpenKey(ctx,argv[1],REDISMODULE_READ); -The second argument is the key name, and must be a `RedisModuleString` -object. The third argument is the mode: `REDISMODULE_READ` or -`REDISMODULE_WRITE`. It is possible to use `|` to bitwise OR the two -modes to open the key in both modes. Currently, a key opened for writing -can also be accessed for reading but this is to be considered an -implementation detail. The right mode should be used in sane modules. +The second argument is the key name, that must be a `RedisModuleString` object. +The third argument is the mode: `REDISMODULE_READ` or `REDISMODULE_WRITE`. +It is possible to use `|` to bitwise OR the two modes to open the key in +both modes. Currently a key opened for writing can also be accessed for reading +but this is to be considered an implementation detail. The right mode should +be used in sane modules. -You can open non-existent keys for writing, and the keys will be created -when an attempt to write to the key is performed. However when opening -keys just for reading, `RedisModule_OpenKey` will return NULL if the key -does not exist. +You can open non exisitng keys for writing, since the keys will be created +when an attempt to write to the key is performed. However when opening keys +just for reading, `RedisModule_OpenKey` will return NULL if the key does not +exist. -A key is closed by calling: +Once you are done using a key, you can close it with: RedisModule_CloseKey(key); -With automatic memory management enabled, Redis will close all open keys -when the module function returns +Note that if automatic memory management is enabled, you are not forced to +close keys. When the module function returns, Redis will take care to close +all the keys which are still open. ## Getting the key type -In order to obtain the value of a key, use `RedisModule_KeyType()`: +In order to obtain the value of a key, use the `RedisModule_KeyType()` function: int keytype = RedisModule_KeyType(key); @@ -527,9 +563,9 @@ It returns one of the following values: REDISMODULE_KEYTYPE_SET REDISMODULE_KEYTYPE_ZSET -The above are standard Redis key types, with the addition of an empty -type signalling the key pointer is associated with an empty key that -does not exist yet. +The above are just the usual Redis key types, with the addition of an empty +type, that signals the key pointer is associated with an empty key that +does not yet exists. ## Creating new keys @@ -550,9 +586,9 @@ Just use: The function returns `REDISMODULE_ERR` if the key is not open for writing. Note that after a key gets deleted, it is setup in order to be targeted -by new key commands. For example `RedisModule_KeyType()` will return it -as an empty key, and writing to it will create a new key, possibly of -another type (depending on the API used). +by new key commands. For example `RedisModule_KeyType()` will return it is +an empty key, and writing to it will create a new key, possibly of another +type (depending on the API used). ## Managing key expires (TTLs) @@ -589,7 +625,7 @@ performed. ## Obtaining the length of values There is a single function in order to retrieve the length of the value -associated with an open key. The returned length is value-specific, and is +associated to an open key. The returned length is value-specific, and is the string length for strings, and the number of elements for the aggregated data types (how many elements there is in a list, set, sorted set, hash). @@ -608,11 +644,11 @@ The function works exactly like the Redis `SET` command itself, that is, if there is a prior value (of any type) it will be deleted. Accessing existing string values is performed using DMA (direct memory -access) for speed. The API will return a pointer and a length, so that -it's possible to access and, if needed, modify the string directly. +access) for speed. The API will return a pointer and a length, so that's +possible to access and, if needed, modify the string directly. size_t len, j; - char *myptr = RedisModule_StringDMA(key,REDISMODULE_WRITE,&len); + char *myptr = RedisModule_StringDMA(key,&len,REDISMODULE_WRITE); for (j = 0; j < len; j++) myptr[j] = 'A'; In the above example we write directly on the string. Note that if you want @@ -642,31 +678,53 @@ It's possible to push and pop values from list values: int RedisModule_ListPush(RedisModuleKey *key, int where, RedisModuleString *ele); RedisModuleString *RedisModule_ListPop(RedisModuleKey *key, int where); -The `where` argument specifies whether to push or pop from the tail +In both the APIs the `where` argument specifies if to push or pop from tail or head, using the following macros: REDISMODULE_LIST_HEAD REDISMODULE_LIST_TAIL -Elements returned by `RedisModule_ListPop()` are like strings created with +Elements returned by `RedisModule_ListPop()` are like strings craeted with `RedisModule_CreateString()`, they must be released with `RedisModule_FreeString()` or by enabling automatic memory management. ## Set type API -See [FUNCTIONS.md](FUNCTIONS.md) +Work in progress. ## Sorted set type API -See [FUNCTIONS.md](FUNCTIONS.md) +Documentation missing, please refer to the top comments inside `module.c` +for the following functions: + +* `RedisModule_ZsetAdd` +* `RedisModule_ZsetIncrby` +* `RedisModule_ZsetScore` +* `RedisModule_ZsetRem` + +And for the sorted set iterator: + +* `RedisModule_ZsetRangeStop` +* `RedisModule_ZsetFirstInScoreRange` +* `RedisModule_ZsetLastInScoreRange` +* `RedisModule_ZsetFirstInLexRange` +* `RedisModule_ZsetLastInLexRange` +* `RedisModule_ZsetRangeCurrentElement` +* `RedisModule_ZsetRangeNext` +* `RedisModule_ZsetRangePrev` +* `RedisModule_ZsetRangeEndReached` ## Hash type API -See [FUNCTIONS.md](FUNCTIONS.md) +Documentation missing, please refer to the top comments inside `module.c` +for the following functions: + +* `RedisModule_HashSet` +* `RedisModule_HashGet` ## Iterating aggregated values -See [FUNCTIONS.md](FUNCTIONS.md) +Work in progress. # Replicating commands @@ -676,41 +734,43 @@ it is important for module commands to handle their replication in a consistent way. When using the higher level APIs to invoke commands, replication happens -automatically when using the "!" modifier in the format string of +automatically if you use the "!" modifier in the format string of `RedisModule_Call()` as in the following example: reply = RedisModule_Call(ctx,"INCR","!sc",argv[1],"10"); -The bang is not parsed as a format specifier, but it internally flags -the command as "must replicate". +As you can see the format specifier is `"!sc"`. The bang is not parsed as a +format specifier, but it internally flags the command as "must replicate". -For more complex scenarios than that, use the low level API. In this -case, if there are no side effects in the command execution, and -it always consistently performs the same work, it is possible -to replicate the command verbatim as the user executed it. To do that, -call the following function: +If you use the above programming style, there are no problems. +However sometimes things are more complex than that, and you use the low level +API. In this case, if there are no side effects in the command execution, and +it consistently always performs the same work, what is possible to do is to +replicate the command verbatim as the user executed it. To do that, you just +need to call the following function: RedisModule_ReplicateVerbatim(ctx); -When you using the above API, do not use any other replication function +When you use the above API, you should not use any other replication function since they are not guaranteed to mix well. -An alternative is to tell Redis exactly which commands to replicate as -the effect of the command execution, using an API similar to -`RedisModule_Call()`. Instead of calling the command they are sent to -the AOF / slaves stream. For example: +However this is not the only option. It's also possible to exactly tell +Redis what commands to replicate as the effect of the command execution, using +an API similar to `RedisModule_Call()` but that instead of calling the command +sends it to the AOF / slaves stream. Example: RedisModule_Replicate(ctx,"INCRBY","cl","foo",my_increment); It's possible to call `RedisModule_Replicate` multiple times, and each -will emit a command. The entire sequence emitted is wrapped in a +will emit a command. All the sequence emitted is wrapped between a `MULTI/EXEC` transaction, so that the AOF and replication effects are the same as executing a single command. -It is not a good idea to mix both forms of replication if there are -simpler alternatives. However, when mixing note that commands replicated -with `Call()` are always the first emitted in the final `MULTI/EXEC` -block, while all the commands emitted with `Replicate()` will follow. +Note that `Call()` replication and `Replicate()` replication have a rule, +in case you want to mix both forms of replication (not necessarily a good +idea if there are simpler approaches). Commands replicated with `Call()` +are always the first emitted in the final `MULTI/EXEC` block, while all +the commands emitted with `Replicate()` will follow. # Automatic memory management @@ -718,20 +778,20 @@ Normally when writing programs in the C language, programmers need to manage memory manually. This is why the Redis modules API has functions to release strings, close open keys, free replies, and so forth. -However since commands are executed in a contained environment and -with a set of strict APIs, Redis is able to provide automatic memory -management to modules, at the cost of some performance (most of the -time, a very low cost). +However given that commands are executed in a contained environment and +with a set of strict APIs, Redis is able to provide automatic memory management +to modules, at the cost of some performance (most of the time, a very low +cost). -When automatic memory management is enabled, there is **no need to**: +When automatic memory management is enabled: -1. Close open keys. -2. Free replies. -3. Free RedisModuleString objects. +1. You don't need to close open keys. +2. You don't need to free replies. +3. You don't need to free RedisModuleString objects. -Automatic and manual memory management can be combined. For example, -automatic memory management may be active, but inside a loop allocating -a lot of strings, you may still want to free strings no longer used. +However you can still do it, if you want. For example, automatic memory +management may be active, but inside a loop allocating a lot of strings, +you may still want to free strings no longer used. In order to enable automatic memory management, just call the following function at the start of the command implementation: @@ -742,15 +802,56 @@ Automatic memory management is usually the way to go, however experienced C programmers may not use it in order to gain some speed and memory usage benefit. +# Allocating memory into modules + +Normal C programs use `malloc()` and `free()` in order to allocate and +release memory dynamically. While in Redis modules the use of malloc is +not technically forbidden, it is a lot better to use the Redis Modules +specific functions, that are exact replacements for `malloc`, `free`, +`realloc` and `strdup`. These functions are: + + void *RedisModule_Alloc(size_t bytes); + void* RedisModule_Realloc(void *ptr, size_t bytes); + void RedisModule_Free(void *ptr); + void RedisModule_Calloc(size_t nmemb, size_t size); + char *RedisModule_Strdup(const char *str); + +They work exactly like their `libc` equivalent calls, however they use +the same allocator Redis uses, and the memory allocated using these +functions is reported by the `INFO` command in the memory section, is +accounted when enforcing the `maxmemory` policy, and in general is +a first citizen of the Redis executable. On the contrar, the method +allocated inside modules with libc `malloc()` is transparent to Redis. + +Another reason to use the modules functions in order to allocate memory +is that, when creating native data types inside modules, the RDB loading +functions can return deserialized strings (from the RDB file) directly +as `RedisModule_Alloc()` allocations, so they can be used directly to +populate data structures after loading, instead of having to copy them +to the data structure. + +## Pool allocator + +Sometimes in commands implementations, it is required to perform many +small allocations that will be not retained at the end of the command +execution, but are just functional to execute the command itself. + +This work can be more easily accomplished using the Redis pool allocator: + + void *RedisModule_PoolAlloc(RedisModuleCtx *ctx, size_t bytes); + +It works similarly to `malloc()`, and returns memory aligned to the +next power of two of greater or equal to `bytes` (for a maximum alignment +of 8 bytes). However it allocates memory in blocks, so it the overhead +of the allocations is small, and more important, the memory allocated +is automatically released when the command returns. + +So in general short living allocations are a good candidates for the pool +allocator. + # Writing commands compatible with Redis Cluster -Work in progress, see [FUNCTIONS.md](FUNCTIONS.md) for the following API: +Documentation missing, please check the following functions inside `module.c`: RedisModule_IsKeysPositionRequest(ctx); RedisModule_KeyAtPos(ctx,pos); - -Command implementations, on keys position request, must reply with -`REDISMODULE_KEYPOS_OK` to signal the request was processed, otherwise -Cluster returns an error for those module commands that are not able to -describe the position of keys. - diff --git a/FUNCTIONS.md b/FUNCTIONS.md index d74480c..8659f79 100644 --- a/FUNCTIONS.md +++ b/FUNCTIONS.md @@ -1,1735 +1,1328 @@ +# Modules API reference -## module.c -* [RedisModule_FreeCallReply](#redismodule_freecallreply) +## `RM_Alloc` -* [RedisModule_CloseKey](#redismodule_closekey) + void *RM_Alloc(size_t bytes); -* [RedisModule_ZsetRangeStop](#redismodule_zsetrangestop) +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_Alloc](#redismodule_alloc) +## `RM_Calloc` -* [RedisModule_Calloc](#redismodule_calloc) + void *RM_Calloc(size_t nmemb, size_t size); -* [RedisModule_Realloc](#redismodule_realloc) +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_Free](#redismodule_free) +## `RM_Realloc` -* [RedisModule_Strdup](#redismodule_strdup) + void* RM_Realloc(void *ptr, size_t bytes); -* [RedisModule_PoolAlloc](#redismodule_poolalloc) +Use like realloc() for memory obtained with `RedisModule_Alloc()`. -* [RedisModule_GetApi](#redismodule_getapi) +## `RM_Free` -* [RedisModule_IsKeysPositionRequest](#redismodule_iskeyspositionrequest) + void RM_Free(void *ptr); -* [RedisModule_KeyAtPos](#redismodule_keyatpos) +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_CreateCommand](#redismodule_createcommand) +## `RM_Strdup` -* [RedisModule_SetModuleAttribs](#redismodule_setmoduleattribs) + char *RM_Strdup(const char *str); -* [RedisModule_AutoMemory](#redismodule_automemory) +Like strdup() but returns memory allocated with `RedisModule_Alloc()`. -* [RedisModule_CreateString](#redismodule_createstring) +## `RM_PoolAlloc` -* [RedisModule_CreateStringPrintf](#redismodule_createstringprintf) + void *RM_PoolAlloc(RedisModuleCtx *ctx, size_t bytes); -* [RedisModule_CreateStringFromLongLong](#redismodule_createstringfromlonglong) +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. -* [RedisModule_CreateStringFromString](#redismodule_createstringfromstring) +There is no realloc style function since when this is needed to use the +pool allocator is not a good idea. -* [RedisModule_FreeString](#redismodule_freestring) +The function returns NULL if `bytes` is 0. -* [RedisModule_RetainString](#redismodule_retainstring) +## `RM_GetApi` -* [RedisModule_StringPtrLen](#redismodule_stringptrlen) + int RM_GetApi(const char *funcname, void **targetPtrPtr); -* [RedisModule_StringToLongLong](#redismodule_stringtolonglong) +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`. -* [RedisModule_StringToDouble](#redismodule_stringtodouble) +This function is not meant to be used by modules developer, it is only +used implicitly by including redismodule.h. -* [RedisModule_StringCompare](#redismodule_stringcompare) +## `RM_IsKeysPositionRequest` -* [RedisModule_StringAppendBuffer](#redismodule_stringappendbuffer) + int RM_IsKeysPositionRequest(RedisModuleCtx *ctx); -* [RedisModule_WrongArity](#redismodule_wrongarity) +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_ReplyWithLongLong](#redismodule_replywithlonglong) +## `RM_KeyAtPos` -* [RedisModule_ReplyWithError](#redismodule_replywitherror) + void RM_KeyAtPos(RedisModuleCtx *ctx, int pos); -* [RedisModule_ReplyWithSimpleString](#redismodule_replywithsimplestring) +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: -* [RedisModule_ReplyWithArray](#redismodule_replywitharray) + if (`RedisModule_IsKeysPositionRequest(ctx))` { + `RedisModule_KeyAtPos(ctx`,1); + `RedisModule_KeyAtPos(ctx`,2); + } -* [RedisModule_ReplySetArrayLength](#redismodule_replysetarraylength) + 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_ReplyWithStringBuffer](#redismodule_replywithstringbuffer) +## `RM_CreateCommand` -* [RedisModule_ReplyWithString](#redismodule_replywithstring) + int RM_CreateCommand(RedisModuleCtx *ctx, const char *name, RedisModuleCmdFunc cmdfunc, const char *strflags, int firstkey, int lastkey, int keystep); -* [RedisModule_ReplyWithNull](#redismodule_replywithnull) +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. -* [RedisModule_ReplyWithCallReply](#redismodule_replywithcallreply) +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. -* [RedisModule_ReplyWithDouble](#redismodule_replywithdouble) +The command function type is the following: -* [RedisModule_Replicate](#redismodule_replicate) + int MyCommand_RedisCommand(RedisModuleCtx *ctx, RedisModuleString **argv, int argc); -* [RedisModule_ReplicateVerbatim](#redismodule_replicateverbatim) +And is supposed to always return `REDISMODULE_OK`. -* [RedisModule_GetClientId](#redismodule_getclientid) +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: -* [RedisModule_GetSelectedDb](#redismodule_getselecteddb) +* **"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_SelectDb](#redismodule_selectdb) +## `RM_SetModuleAttribs` -* [RedisModule_OpenKey](#redismodule_openkey) + void RM_SetModuleAttribs(RedisModuleCtx *ctx, const char *name, int ver, int apiver); -* [RedisModule_CloseKey](#redismodule_closekey) +Called by `RM_Init()` to setup the `ctx->module` structure. -* [RedisModule_KeyType](#redismodule_keytype) +This is an internal function, Redis modules developers don't need +to use it. -* [RedisModule_ValueLength](#redismodule_valuelength) +## `RM_Milliseconds` -* [RedisModule_DeleteKey](#redismodule_deletekey) + long long RM_Milliseconds(void); -* [RedisModule_GetExpire](#redismodule_getexpire) +Return the current UNIX time in milliseconds. -* [RedisModule_SetExpire](#redismodule_setexpire) +## `RM_AutoMemory` -* [RedisModule_StringSet](#redismodule_stringset) + void RM_AutoMemory(RedisModuleCtx *ctx); -* [RedisModule_StringDMA](#redismodule_stringdma) +Enable automatic memory management. See API.md for more information. -* [RedisModule_StringTruncate](#redismodule_stringtruncate) +The function must be called as the first function of a command implementation +that wants to use automatic memory. -* [RedisModule_ListPush](#redismodule_listpush) +## `RM_CreateString` -* [RedisModule_ListPop](#redismodule_listpop) + RedisModuleString *RM_CreateString(RedisModuleCtx *ctx, const char *ptr, size_t len); -* [RedisModule_ZsetAddFlagsToCoreFlags](#redismodule_zsetaddflagstocoreflags) +Create a new module string object. The returned string must be freed +with `RedisModule_FreeString()`, unless automatic memory is enabled. -* [RedisModule_ZsetAddFlagsFromCoreFlags](#redismodule_zsetaddflagsfromcoreflags) +The string is created by copying the `len` bytes starting +at `ptr`. No reference is retained to the passed buffer. -* [RedisModule_ZsetAdd](#redismodule_zsetadd) +## `RM_CreateStringPrintf` -* [RedisModule_ZsetIncrby](#redismodule_zsetincrby) + RedisModuleString *RM_CreateStringPrintf(RedisModuleCtx *ctx, const char *fmt, ...); -* [RedisModule_ZsetRem](#redismodule_zsetrem) +Create a new module string object from a printf format and arguments. +The returned string must be freed with `RedisModule_FreeString()`, unless +automatic memory is enabled. -* [RedisModule_ZsetScore](#redismodule_zsetscore) +The string is created using the sds formatter function sdscatvprintf(). -* [RedisModule_ZsetRangeStop](#redismodule_zsetrangestop) +## `RM_CreateStringFromLongLong` -* [RedisModule_ZsetRangeEndReached](#redismodule_zsetrangeendreached) + RedisModuleString *RM_CreateStringFromLongLong(RedisModuleCtx *ctx, long long ll); -* [RedisModule_ZsetFirstInScoreRange](#redismodule_zsetfirstinscorerange) +Like `RedisModule_CreatString()`, but creates a string starting from a long long +integer instead of taking a buffer and its length. -* [RedisModule_ZsetLastInScoreRange](#redismodule_zsetlastinscorerange) +The returned string must be released with `RedisModule_FreeString()` or by +enabling automatic memory management. -* [RedisModule_ZsetFirstInLexRange](#redismodule_zsetfirstinlexrange) +## `RM_CreateStringFromString` -* [RedisModule_ZsetLastInLexRange](#redismodule_zsetlastinlexrange) + RedisModuleString *RM_CreateStringFromString(RedisModuleCtx *ctx, const RedisModuleString *str); -* [RedisModule_ZsetRangeCurrentElement](#redismodule_zsetrangecurrentelement) +Like `RedisModule_CreatString()`, but creates a string starting from another +RedisModuleString. -* [RedisModule_ZsetRangeNext](#redismodule_zsetrangenext) +The returned string must be released with `RedisModule_FreeString()` or by +enabling automatic memory management. -* [RedisModule_ZsetRangePrev](#redismodule_zsetrangeprev) +## `RM_FreeString` -* [RedisModule_HashSet](#redismodule_hashset) + void RM_FreeString(RedisModuleCtx *ctx, RedisModuleString *str); -* [RedisModule_HashGet](#redismodule_hashget) +Free a module string object obtained with one of the Redis modules API calls +that return new string objects. -* [RedisModule_FreeCallReply_Rec](#redismodule_freecallreply_rec) +It is possible to call this function even when automatic memory management +is enabled. In that case the string will be released ASAP and removed +from the pool of string to release at the end. -* [RedisModule_FreeCallReply](#redismodule_freecallreply) +## `RM_RetainString` -* [RedisModule_CallReplyType](#redismodule_callreplytype) + void RM_RetainString(RedisModuleCtx *ctx, RedisModuleString *str); -* [RedisModule_CallReplyLength](#redismodule_callreplylength) +Every call to this function, will make the string 'str' requiring +an additional call to `RedisModule_FreeString()` in order to really +free the string. Note that the automatic freeing of the string obtained +enabling modules automatic memory management counts for one +`RedisModule_FreeString()` call (it is just executed automatically). -* [RedisModule_CallReplyArrayElement](#redismodule_callreplyarrayelement) +Normally you want to call this function when, at the same time +the following conditions are true: -* [RedisModule_CallReplyInteger](#redismodule_callreplyinteger) +1) You have automatic memory management enabled. +2) You want to create string objects. +3) Those string objects you create need to live *after* the callback + function(for example a command implementation) creating them returns. -* [RedisModule_CallReplyStringPtr](#redismodule_callreplystringptr) +Usually you want this in order to store the created string object +into your own data structure, for example when implementing a new data +type. -* [RedisModule_CreateStringFromCallReply](#redismodule_createstringfromcallreply) +Note that when memory management is turned off, you don't need +any call to RetainString() since creating a string will always result +into a string that lives after the callback function returns, if +no FreeString() call is performed. -* [RedisModule_Call](#redismodule_call) +## `RM_StringPtrLen` -* [RedisModule_CallReplyProto](#redismodule_callreplyproto) + const char *RM_StringPtrLen(const RedisModuleString *str, size_t *len); -* [RedisModule_CreateDataType](#redismodule_createdatatype) +Given a string module object, this function returns the string pointer +and length of the string. The returned pointer and length should only +be used for read only accesses and never modified. -* [RedisModule_ModuleTypeSetValue](#redismodule_moduletypesetvalue) +## `RM_StringToLongLong` -* [RedisModule_ModuleTypeGetType](#redismodule_moduletypegettype) + int RM_StringToLongLong(const RedisModuleString *str, long long *ll); -* [RedisModule_ModuleTypeGetValue](#redismodule_moduletypegetvalue) +Convert the string into a long long integer, storing it at `*ll`. +Returns `REDISMODULE_OK` on success. If the string can't be parsed +as a valid, strict long long (no spaces before/after), `REDISMODULE_ERR` +is returned. -* [RedisModule_SaveUnsigned](#redismodule_saveunsigned) +## `RM_StringToDouble` -* [RedisModule_LoadUnsigned](#redismodule_loadunsigned) + int RM_StringToDouble(const RedisModuleString *str, double *d); -* [RedisModule_SaveSigned](#redismodule_savesigned) +Convert the string into a double, storing it at `*d`. +Returns `REDISMODULE_OK` on success or `REDISMODULE_ERR` if the string is +not a valid string representation of a double value. -* [RedisModule_LoadSigned](#redismodule_loadsigned) +## `RM_StringCompare` -* [RedisModule_SaveString](#redismodule_savestring) + int RM_StringCompare(RedisModuleString *a, RedisModuleString *b); -* [RedisModule_SaveStringBuffer](#redismodule_savestringbuffer) +Compare two string objects, returning -1, 0 or 1 respectively if +a < b, a == b, a > b. Strings are compared byte by byte as two +binary blobs without any encoding care / collation attempt. -* [RedisModule_LoadString](#redismodule_loadstring) +## `RM_StringAppendBuffer` -* [RedisModule_LoadStringBuffer](#redismodule_loadstringbuffer) + int RM_StringAppendBuffer(RedisModuleCtx *ctx, RedisModuleString *str, const char *buf, size_t len); -* [RedisModule_SaveDouble](#redismodule_savedouble) +Append the specified buffere to the string 'str'. The string must be a +string created by the user that is referenced only a single time, otherwise +`REDISMODULE_ERR` is returend and the operation is not performed. -* [RedisModule_LoadDouble](#redismodule_loaddouble) +## `RM_WrongArity` -* [RedisModule_SaveFloat](#redismodule_savefloat) + int RM_WrongArity(RedisModuleCtx *ctx); -* [RedisModule_LoadFloat](#redismodule_loadfloat) +Send an error about the number of arguments given to the command, +citing the command name in the error message. -* [RedisModule_EmitAOF](#redismodule_emitaof) +Example: -* [RedisModule_GetContextFromIO](#redismodule_getcontextfromio) + if (argc != 3) return `RedisModule_WrongArity(ctx)`; -* [RedisModule_LogRaw](#redismodule_lograw) +## `RM_ReplyWithLongLong` -* [RedisModule_Log](#redismodule_log) + int RM_ReplyWithLongLong(RedisModuleCtx *ctx, long long ll); -* [RedisModule_LogIOError](#redismodule_logioerror) +Send an integer reply to the client, with the specified long long value. +The function always returns `REDISMODULE_OK`. -## util.h -* [RMUtil_ArgExists](#rmutil_argexists) +## `RM_ReplyWithError` -* [RMUtil_ParseArgs](#rmutil_parseargs) + int RM_ReplyWithError(RedisModuleCtx *ctx, const char *err); -* [RMUtil_ParseArgsAfter](#rmutil_parseargsafter) +Reply with the error 'err'. -* [RMUtil_GetRedisInfo](#rmutil_getredisinfo) +Note that 'err' must contain all the error, including +the initial error code. The function only provides the initial "-", so +the usage is, for example: -## strings.h -* [RMUtil_CreateFormattedString](#rmutil_createformattedstring) + `RM_ReplyWithError(ctx`,"ERR Wrong Type"); -* [RMUtil_StringEquals](#rmutil_stringequals) +and not just: -* [RMUtil_StringEqualsC](#rmutil_stringequalsc) + `RM_ReplyWithError(ctx`,"Wrong Type"); -* [RMUtil_StringToLower](#rmutil_stringtolower) +The function always returns `REDISMODULE_OK`. -* [RMUtil_StringToUpper](#rmutil_stringtoupper) +## `RM_ReplyWithSimpleString` -## vector.h -* [Vector_Get](#vector_get) + int RM_ReplyWithSimpleString(RedisModuleCtx *ctx, const char *msg); -* [Vector_Pop](#vector_pop) +Reply with a simple string (+... \r\n in RESP protocol). This replies +are suitable only when sending a small non-binary string with small +overhead, like "OK" or similar replies. -* [Vector_Resize](#vector_resize) +The function always returns `REDISMODULE_OK`. -* [Vector_Size](#vector_size) +## `RM_ReplyWithArray` -* [Vector_Cap](#vector_cap) + int RM_ReplyWithArray(RedisModuleCtx *ctx, long len); -* [Vector_Free](#vector_free) -### RedisModule_FreeCallReply -``` -void RedisModule_FreeCallReply(RedisModuleCallReply *reply); -``` - -------------------------------------------------------------------------- - Prototypes - -------------------------------------------------------------------------- +Reply with an array type of 'len' elements. However 'len' other calls +to `ReplyWith*` style functions must follow in order to emit the elements +of the array. +When producing arrays with a number of element that is not known beforehand +the function can be called with the special count +`REDISMODULE_POSTPONED_ARRAY_LEN`, and the actual number of elements can be +later set with `RedisModule_ReplySetArrayLength()` (which will set the +latest "open" count if there are multiple ones). -### RedisModule_CloseKey -``` -void RedisModule_CloseKey(RedisModuleKey *key); -``` - -------------------------------------------------------------------------- - Prototypes - -------------------------------------------------------------------------- +The function always returns `REDISMODULE_OK`. +## `RM_ReplySetArrayLength` -### RedisModule_ZsetRangeStop -``` -void RedisModule_ZsetRangeStop(RedisModuleKey *kp); -``` - -------------------------------------------------------------------------- - Prototypes - -------------------------------------------------------------------------- + void RM_ReplySetArrayLength(RedisModuleCtx *ctx, long len); +When `RedisModule_ReplyWithArray()` is used with the argument +`REDISMODULE_POSTPONED_ARRAY_LEN`, because we don't know beforehand the number +of items we are going to output as elements of the array, this function +will take care to set the array length. -### 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(). +Since it is possible to have multiple array replies pending with unknown +length, this function guarantees to always set the latest array length +that was created in a postponed way. +For example in order to output an array like [1,[10,20,30]] we +could write: -### 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_ReplyWithArray(ctx`,`REDISMODULE_POSTPONED_ARRAY_LEN`); + `RedisModule_ReplyWithLongLong(ctx`,1); + `RedisModule_ReplyWithArray(ctx`,`REDISMODULE_POSTPONED_ARRAY_LEN`); + `RedisModule_ReplyWithLongLong(ctx`,10); + `RedisModule_ReplyWithLongLong(ctx`,20); + `RedisModule_ReplyWithLongLong(ctx`,30); + `RedisModule_ReplySetArrayLength(ctx`,3); // Set len of 10,20,30 array. + `RedisModule_ReplySetArrayLength(ctx`,2); // Set len of top array +Note that in the above example there is no reason to postpone the array +length, since we produce a fixed number of elements, but in the practice +the code may use an interator or other ways of creating the output so +that is not easy to calculate in advance the number of elements. -### RedisModule_Realloc -``` -void* RedisModule_Realloc(void *ptr, size_t bytes) { -``` - Use like realloc() for memory obtained with RedisModule_Alloc(). +## `RM_ReplyWithStringBuffer` + int RM_ReplyWithStringBuffer(RedisModuleCtx *ctx, const char *buf, size_t len); -### 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. +Reply with a bulk string, taking in input a C buffer pointer and length. +The function always returns `REDISMODULE_OK`. -### 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_AutoMemory -``` -void RedisModule_AutoMemory(RedisModuleCtx *ctx) { -``` - Enable automatic memory management. See API.md for more information. - - The function must be called as the first function of a command implementation - that wants to use automatic memory. - - -### RedisModule_CreateString -``` -RedisModuleString *RedisModule_CreateString(RedisModuleCtx *ctx, const char *ptr, size_t len) { -``` - Create a new module string object. The returned string must be freed - with RedisModule_FreeString(), unless automatic memory is enabled. - - The string is created by copying the `len` bytes starting - at `ptr`. No reference is retained to the passed buffer. - - -### RedisModule_CreateStringPrintf -``` -RedisModuleString *RedisModule_CreateStringPrintf(RedisModuleCtx *ctx, const char *fmt, ...) { -``` - Create a new module string object from a printf format and arguments. - The returned string must be freed with RedisModule_FreeString(), unless automatic - memory is enabled. - - The string is created using the sds formatter function sdscatvprintf() - - -### RedisModule_CreateStringFromLongLong -``` -RedisModuleString *RedisModule_CreateStringFromLongLong(RedisModuleCtx *ctx, long long ll) { -``` - Like RedisModule_CreatString(), but creates a string starting from a long long - integer instead of taking a buffer and its length. - - The returned string must be released with RedisModule_FreeString() or by - enabling automatic memory management. - - -### RedisModule_CreateStringFromString -``` -RedisModuleString *RedisModule_CreateStringFromString(RedisModuleCtx *ctx, const RedisModuleString *str) { -``` - Like RedisModule_CreatString(), but creates a string starting from another - RedisModuleString. - - The returned string must be released with RedisModule_FreeString() or by - enabling automatic memory management. - - -### RedisModule_FreeString -``` -void RedisModule_FreeString(RedisModuleCtx *ctx, RedisModuleString *str) { -``` - Free a module string object obtained with one of the Redis modules API calls - that return new string objects. - - It is possible to call this function even when automatic memory management - is enabled. In that case the string will be released ASAP and removed - from the pool of string to release at the end. - - -### RedisModule_RetainString -``` -void RedisModule_RetainString(RedisModuleCtx *ctx, RedisModuleString *str) { -``` - Every call to this function, will make the string 'str' requiring - an additional call to RedisModule_FreeString() in order to really - free the string. Note that the automatic freeing of the string obtained - enabling modules automatic memory management counts for one - RedisModule_FreeString() call (it is just executed automatically). +## `RM_ReplyWithString` - Normally you want to call this function when, at the same time - the following conditions are true: + int RM_ReplyWithString(RedisModuleCtx *ctx, RedisModuleString *str); - 1) You have automatic memory management enabled. - 2) You want to create string objects. - 3) Those string objects you create need to live *after* the callback - function(for example a command implementation) creating them returns. +Reply with a bulk string, taking in input a RedisModuleString object. - Usually you want this in order to store the created string object - into your own data structure, for example when implementing a new data - type. +The function always returns `REDISMODULE_OK`. - Note that when memory management is turned off, you don't need - any call to RetainString() since creating a string will always result - into a string that lives after the callback function returns, if - no FreeString() call is performed. +## `RM_ReplyWithNull` + int RM_ReplyWithNull(RedisModuleCtx *ctx); -### RedisModule_StringPtrLen -``` -const char *RedisModule_StringPtrLen(const RedisModuleString *str, size_t *len) { -``` - Given a string module object, this function returns the string pointer - and length of the string. The returned pointer and length should only - be used for read only accesses and never modified. +Reply to the client with a NULL. In the RESP protocol a NULL is encoded +as the string "$-1\r\n". +The function always returns `REDISMODULE_OK`. -### RedisModule_StringToLongLong -``` -int RedisModule_StringToLongLong(const RedisModuleString *str, long long *ll) { -``` - Convert the string into a long long integer, storing it at `*ll`. - Returns REDISMODULE_OK on success. If the string can't be parsed - as a valid, strict long long (no spaces before/after), REDISMODULE_ERR - is returned. +## `RM_ReplyWithCallReply` + int RM_ReplyWithCallReply(RedisModuleCtx *ctx, RedisModuleCallReply *reply); -### RedisModule_StringToDouble -``` -int RedisModule_StringToDouble(const RedisModuleString *str, double *d) { -``` - Convert the string into a double, storing it at `*d`. - Returns REDISMODULE_OK on success or REDISMODULE_ERR if the string is - not a valid string representation of a double value. +Reply exactly what a Redis command returned us with `RedisModule_Call()`. +This function is useful when we use `RedisModule_Call()` in order to +execute some command, as we want to reply to the client exactly the +same reply we obtained by the command. +The function always returns `REDISMODULE_OK`. -### RedisModule_StringCompare -``` -int RedisModule_StringCompare(RedisModuleString *a, RedisModuleString *b) { -``` - Compare two string objects, returning -1, 0 or 1 respectively if - a < b, a == b, a > b. Strings are compared byte by byte as two - binary blobs without any encoding care / collation attempt. +## `RM_ReplyWithDouble` + int RM_ReplyWithDouble(RedisModuleCtx *ctx, double d); -### RedisModule_StringAppendBuffer -``` -int RedisModule_StringAppendBuffer(RedisModuleCtx *ctx, RedisModuleString *str, const char *buf, size_t len) { -``` - Append the specified buffere to the string 'str'. The string must be a - string created by the user that is referenced only a single time, otherwise - REDISMODULE_ERR is returend and the operation is not performed. +Send a string reply obtained converting the double 'd' into a bulk string. +This function is basically equivalent to converting a double into +a string into a C buffer, and then calling the function +`RedisModule_ReplyWithStringBuffer()` with the buffer and length. +The function always returns `REDISMODULE_OK`. -### RedisModule_WrongArity -``` -int RedisModule_WrongArity(RedisModuleCtx *ctx) { -``` - Send an error about the number of arguments given to the command, - citing the command name in the error message. +## `RM_Replicate` - Example: + int RM_Replicate(RedisModuleCtx *ctx, const char *cmdname, const char *fmt, ...); - if (argc != 3) return RedisModule_WrongArity(ctx); +Replicate the specified command and arguments to slaves and AOF, as effect +of execution of the calling command implementation. +The replicated commands are always wrapped into the MULTI/EXEC that +contains all the commands replicated in a given module command +execution. However the commands replicated with `RedisModule_Call()` +are the first items, the ones replicated with `RedisModule_Replicate()` +will all follow before the EXEC. -### RedisModule_ReplyWithLongLong -``` -int RedisModule_ReplyWithLongLong(RedisModuleCtx *ctx, long long ll) { -``` - Send an integer reply to the client, with the specified long long value. - The function always returns REDISMODULE_OK. +Modules should try to use one interface or the other. +This command follows exactly the same interface of `RedisModule_Call()`, +so a set of format specifiers must be passed, followed by arguments +matching the provided format specifiers. -### RedisModule_ReplyWithError -``` -int RedisModule_ReplyWithError(RedisModuleCtx *ctx, const char *err) { -``` - Reply with the error 'err'. +Please refer to `RedisModule_Call()` for more information. - Note that 'err' must contain all the error, including - the initial error code. The function only provides the initial "-", so - the usage is, for example: +The command returns `REDISMODULE_ERR` if the format specifiers are invalid +or the command name does not belong to a known command. - RM_ReplyWithError(ctx,"ERR Wrong Type"); +## `RM_ReplicateVerbatim` - and not just: + int RM_ReplicateVerbatim(RedisModuleCtx *ctx); - RM_ReplyWithError(ctx,"Wrong Type"); +This function will replicate the command exactly as it was invoked +by the client. Note that this function will not wrap the command into +a MULTI/EXEC stanza, so it should not be mixed with other replication +commands. - The function always returns REDISMODULE_OK. +Basically this form of replication is useful when you want to propagate +the command to the slaves and AOF file exactly as it was called, since +the command can just be re-executed to deterministically re-create the +new state starting from the old one. +The function always returns `REDISMODULE_OK`. -### RedisModule_ReplyWithSimpleString -``` -int RedisModule_ReplyWithSimpleString(RedisModuleCtx *ctx, const char *msg) { -``` - Reply with a simple string (+... \r\n in RESP protocol). This replies - are suitable only when sending a small non-binary string with small - overhead, like "OK" or similar replies. +## `RM_GetClientId` - The function always returns REDISMODULE_OK. + unsigned long long RM_GetClientId(RedisModuleCtx *ctx); +Return the ID of the current client calling the currently active module +command. The returned ID has a few guarantees: -### RedisModule_ReplyWithArray -``` -int RedisModule_ReplyWithArray(RedisModuleCtx *ctx, long len) { -``` - Reply with an array type of 'len' elements. However 'len' other calls - to `ReplyWith*` style functions must follow in order to emit the elements - of the array. +1. The ID is different for each different client, so if the same client + executes a module command multiple times, it can be recognized as + having the same ID, otherwise the ID will be different. +2. The ID increases monotonically. Clients connecting to the server later + are guaranteed to get IDs greater than any past ID previously seen. - When producing arrays with a number of element that is not known beforehand - the function can be called with the special count - REDISMODULE_POSTPONED_ARRAY_LEN, and the actual number of elements can be - later set with RedisModule_ReplySetArrayLength() (which will set the - latest "open" count if there are multiple ones). +Valid IDs are from 1 to 2^64-1. If 0 is returned it means there is no way +to fetch the ID in the context the function was currently called. - The function always returns REDISMODULE_OK. +## `RM_GetSelectedDb` + int RM_GetSelectedDb(RedisModuleCtx *ctx); -### RedisModule_ReplySetArrayLength -``` -void RedisModule_ReplySetArrayLength(RedisModuleCtx *ctx, long len) { -``` - When RedisModule_ReplyWithArray() is used with the argument - REDISMODULE_POSTPONED_ARRAY_LEN, because we don't know beforehand the number - of items we are going to output as elements of the array, this function - will take care to set the array length. +Return the currently selected DB. - Since it is possible to have multiple array replies pending with unknown - length, this function guarantees to always set the latest array length - that was created in a postponed way. +## `RM_SelectDb` - For example in order to output an array like [1,[10,20,30]] we - could write: + int RM_SelectDb(RedisModuleCtx *ctx, int newid); - RedisModule_ReplyWithArray(ctx,REDISMODULE_POSTPONED_ARRAY_LEN); - RedisModule_ReplyWithLongLong(ctx,1); - RedisModule_ReplyWithArray(ctx,REDISMODULE_POSTPONED_ARRAY_LEN); - RedisModule_ReplyWithLongLong(ctx,10); - RedisModule_ReplyWithLongLong(ctx,20); - RedisModule_ReplyWithLongLong(ctx,30); - RedisModule_ReplySetArrayLength(ctx,3); // Set len of 10,20,30 array. - RedisModule_ReplySetArrayLength(ctx,2); // Set len of top array +Change the currently selected DB. Returns an error if the id +is out of range. - Note that in the above example there is no reason to postpone the array - length, since we produce a fixed number of elements, but in the practice - the code may use an interator or other ways of creating the output so - that is not easy to calculate in advance the number of elements. +Note that the client will retain the currently selected DB even after +the Redis command implemented by the module calling this function +returns. +If the module command wishes to change something in a different DB and +returns back to the original one, it should call `RedisModule_GetSelectedDb()` +before in order to restore the old DB number before returning. -### RedisModule_ReplyWithStringBuffer -``` -int RedisModule_ReplyWithStringBuffer(RedisModuleCtx *ctx, const char *buf, size_t len) { -``` - Reply with a bulk string, taking in input a C buffer pointer and length. +## `RM_OpenKey` - The function always returns REDISMODULE_OK. + void *RM_OpenKey(RedisModuleCtx *ctx, robj *keyname, int mode); +Return an handle representing a Redis key, so that it is possible +to call other APIs with the key handle as argument to perform +operations on the key. -### RedisModule_ReplyWithString -``` -int RedisModule_ReplyWithString(RedisModuleCtx *ctx, RedisModuleString *str) { -``` - Reply with a bulk string, taking in input a RedisModuleString object. +The return value is the handle repesenting the key, that must be +closed with `RM_CloseKey()`. - The function always returns REDISMODULE_OK. +If the key does not exist and WRITE mode is requested, the handle +is still returned, since it is possible to perform operations on +a yet not existing key (that will be created, for example, after +a list push operation). If the mode is just READ instead, and the +key does not exist, NULL is returned. However it is still safe to +call `RedisModule_CloseKey()` and `RedisModule_KeyType()` on a NULL +value. +## `RM_CloseKey` -### RedisModule_ReplyWithNull -``` -int RedisModule_ReplyWithNull(RedisModuleCtx *ctx) { -``` - Reply to the client with a NULL. In the RESP protocol a NULL is encoded - as the string "$-1\r\n". + void RM_CloseKey(RedisModuleKey *key); - The function always returns REDISMODULE_OK. +Close a key handle. +## `RM_KeyType` -### RedisModule_ReplyWithCallReply -``` -int RedisModule_ReplyWithCallReply(RedisModuleCtx *ctx, RedisModuleCallReply *reply) { -``` - Reply exactly what a Redis command returned us with RedisModule_Call(). - This function is useful when we use RedisModule_Call() in order to - execute some command, as we want to reply to the client exactly the - same reply we obtained by the command. + int RM_KeyType(RedisModuleKey *key); - The function always returns REDISMODULE_OK. +Return the type of the key. If the key pointer is NULL then +`REDISMODULE_KEYTYPE_EMPTY` is returned. +## `RM_ValueLength` -### RedisModule_ReplyWithDouble -``` -int RedisModule_ReplyWithDouble(RedisModuleCtx *ctx, double d) { -``` - Send a string reply obtained converting the double 'd' into a bulk string. - This function is basically equivalent to converting a double into - a string into a C buffer, and then calling the function - RedisModule_ReplyWithStringBuffer() with the buffer and length. + size_t RM_ValueLength(RedisModuleKey *key); - The function always returns REDISMODULE_OK. +Return the length of the value associated with the key. +For strings this is the length of the string. For all the other types +is the number of elements (just counting keys for hashes). +If the key pointer is NULL or the key is empty, zero is returned. -### RedisModule_Replicate -``` -int RedisModule_Replicate(RedisModuleCtx *ctx, const char *cmdname, const char *fmt, ...) { -``` - Replicate the specified command and arguments to slaves and AOF, as effect - of execution of the calling command implementation. - - The replicated commands are always wrapped into the MULTI/EXEC that - contains all the commands replicated in a given module command - execution. However the commands replicated with RedisModule_Call() - are the first items, the ones replicated with RedisModule_Replicate() - will all follow before the EXEC. +## `RM_DeleteKey` - Modules should try to use one interface or the other. + int RM_DeleteKey(RedisModuleKey *key); - This command follows exactly the same interface of RedisModule_Call(), - so a set of format specifiers must be passed, followed by arguments - matching the provided format specifiers. +If the key is open for writing, remove it, and setup the key to +accept new writes as an empty key (that will be created on demand). +On success `REDISMODULE_OK` is returned. If the key is not open for +writing `REDISMODULE_ERR` is returned. - Please refer to RedisModule_Call() for more information. +## `RM_GetExpire` - The command returns REDISMODULE_ERR if the format specifiers are invalid - or the command name does not belong to a known command. + mstime_t RM_GetExpire(RedisModuleKey *key); +Return the key expire value, as milliseconds of remaining TTL. +If no TTL is associated with the key or if the key is empty, +`REDISMODULE_NO_EXPIRE` is returned. -### RedisModule_ReplicateVerbatim -``` -int RedisModule_ReplicateVerbatim(RedisModuleCtx *ctx) { -``` - This function will replicate the command exactly as it was invoked - by the client. Note that this function will not wrap the command into - a MULTI/EXEC stanza, so it should not be mixed with other replication - commands. +## `RM_SetExpire` - Basically this form of replication is useful when you want to propagate - the command to the slaves and AOF file exactly as it was called, since - the command can just be re-executed to deterministically re-create the - new state starting from the old one. + int RM_SetExpire(RedisModuleKey *key, mstime_t expire); - The function always returns REDISMODULE_OK. +Set a new expire for the key. If the special expire +`REDISMODULE_NO_EXPIRE` is set, the expire is cancelled if there was +one (the same as the PERSIST command). +Note that the expire must be provided as a positive integer representing +the number of milliseconds of TTL the key should have. -### RedisModule_GetClientId -``` -unsigned long long RedisModule_GetClientId(RedisModuleCtx *ctx) { -``` - Return the ID of the current client calling the currently active module - command. The returned ID has a few guarantees: +The function returns `REDISMODULE_OK` on success or `REDISMODULE_ERR` if +the key was not open for writing or is an empty key. - 1. The ID is different for each different client, so if the same client - executes a module command multiple times, it can be recognized as - having the same ID, otherwise the ID will be different. - 2. The ID increases monotonically. Clients connecting to the server later - are guaranteed to get IDs greater than any past ID previously seen. +## `RM_StringSet` - Valid IDs are from 1 to 2^64-1. If 0 is returned it means there is no way - to fetch the ID in the context the function was currently called. + int RM_StringSet(RedisModuleKey *key, RedisModuleString *str); +If the key is open for writing, set the specified string 'str' as the +value of the key, deleting the old value if any. +On success `REDISMODULE_OK` is returned. If the key is not open for +writing or there is an active iterator, `REDISMODULE_ERR` is returned. -### RedisModule_GetSelectedDb -``` -int RedisModule_GetSelectedDb(RedisModuleCtx *ctx) { -``` - Return the currently selected DB. +## `RM_StringDMA` + char *RM_StringDMA(RedisModuleKey *key, size_t *len, int mode); -### RedisModule_SelectDb -``` -int RedisModule_SelectDb(RedisModuleCtx *ctx, int newid) { -``` - Change the currently selected DB. Returns an error if the id - is out of range. - - Note that the client will retain the currently selected DB even after - the Redis command implemented by the module calling this function - returns. - - If the module command wishes to change something in a different DB and - returns back to the original one, it should call RedisModule_GetSelectedDb() - before in order to restore the old DB number before returning. +Prepare the key associated string value for DMA access, and returns +a pointer and size (by reference), that the user can use to read or +modify the string in-place accessing it directly via pointer. +The 'mode' is composed by bitwise OR-ing the following flags: -### RedisModule_OpenKey -``` -void *RedisModule_OpenKey(RedisModuleCtx *ctx, robj *keyname, int mode) { -``` - Return an handle representing a Redis key, so that it is possible - to call other APIs with the key handle as argument to perform - operations on the key. +`REDISMODULE_READ` -- Read access +`REDISMODULE_WRITE` -- Write access - The return value is the handle repesenting the key, that must be - closed with RM_CloseKey(). +If the DMA is not requested for writing, the pointer returned should +only be accessed in a read-only fashion. - If the key does not exist and WRITE mode is requested, the handle - is still returned, since it is possible to perform operations on - a yet not existing key (that will be created, for example, after - a list push operation). If the mode is just READ instead, and the - key does not exist, NULL is returned. However it is still safe to - call RedisModule_CloseKey() and RedisModule_KeyType() on a NULL - value. +On error (wrong type) NULL is returned. +DMA access rules: -### RedisModule_CloseKey -``` -void RedisModule_CloseKey(RedisModuleKey *key) { -``` - Close a key handle. +1. No other key writing function should be called since the moment +the pointer is obtained, for all the time we want to use DMA access +to read or modify the string. +2. Each time `RM_StringTruncate()` is called, to continue with the DMA +access, `RM_StringDMA()` should be called again to re-obtain +a new pointer and length. -### RedisModule_KeyType -``` -int RedisModule_KeyType(RedisModuleKey *key) { -``` - Return the type of the key. If the key pointer is NULL then - REDISMODULE_KEYTYPE_EMPTY is returned. +3. If the returned pointer is not NULL, but the length is zero, no +byte can be touched (the string is empty, or the key itself is empty) +so a `RM_StringTruncate()` call should be used if there is to enlarge +the string, and later call StringDMA() again to get the pointer. +## `RM_StringTruncate` -### RedisModule_ValueLength -``` -size_t RedisModule_ValueLength(RedisModuleKey *key) { -``` - Return the length of the value associated with the key. - For strings this is the length of the string. For all the other types - is the number of elements (just counting keys for hashes). + int RM_StringTruncate(RedisModuleKey *key, size_t newlen); - If the key pointer is NULL or the key is empty, zero is returned. +If the string is open for writing and is of string type, resize it, padding +with zero bytes if the new length is greater than the old one. +After this call, `RM_StringDMA()` must be called again to continue +DMA access with the new pointer. -### RedisModule_DeleteKey -``` -int RedisModule_DeleteKey(RedisModuleKey *key) { -``` - If the key is open for writing, remove it, and setup the key to - accept new writes as an empty key (that will be created on demand). - On success REDISMODULE_OK is returned. If the key is not open for - writing REDISMODULE_ERR is returned. +The function returns `REDISMODULE_OK` on success, and `REDISMODULE_ERR` on +error, that is, the key is not open for writing, is not a string +or resizing for more than 512 MB is requested. +If the key is empty, a string key is created with the new string value +unless the new length value requested is zero. -### RedisModule_GetExpire -``` -mstime_t RedisModule_GetExpire(RedisModuleKey *key) { -``` - Return the key expire value, as milliseconds of remaining TTL. - If no TTL is associated with the key or if the key is empty, - REDISMODULE_NO_EXPIRE is returned. - +## `RM_ListPush` -### RedisModule_SetExpire -``` -int RedisModule_SetExpire(RedisModuleKey *key, mstime_t expire) { -``` - Set a new expire for the key. If the special expire - REDISMODULE_NO_EXPIRE is set, the expire is cancelled if there was - one (the same as the PERSIST command). + int RM_ListPush(RedisModuleKey *key, int where, RedisModuleString *ele); - Note that the expire must be provided as a positive integer representing - the number of milliseconds of TTL the key should have. - - The function returns REDISMODULE_OK on success or REDISMODULE_ERR if - the key was not open for writing or is an empty key. +Push an element into a list, on head or tail depending on 'where' argumnet. +If the key pointer is about an empty key opened for writing, the key +is created. On error (key opened for read-only operations or of the wrong +type) `REDISMODULE_ERR` is returned, otherwise `REDISMODULE_OK` is returned. +## `RM_ListPop` -### RedisModule_StringSet -``` -int RedisModule_StringSet(RedisModuleKey *key, RedisModuleString *str) { -``` - If the key is open for writing, set the specified string 'str' as the - value of the key, deleting the old value if any. - On success REDISMODULE_OK is returned. If the key is not open for - writing or there is an active iterator, REDISMODULE_ERR is returned. - + RedisModuleString *RM_ListPop(RedisModuleKey *key, int where); -### RedisModule_StringDMA -``` -char *RedisModule_StringDMA(RedisModuleKey *key, size_t *len, int mode) { -``` - Prepare the key associated string value for DMA access, and returns - a pointer and size (by reference), that the user can use to read or - modify the string in-place accessing it directly via pointer. +Pop an element from the list, and returns it as a module string object +that the user should be free with `RM_FreeString()` or by enabling +automatic memory. 'where' specifies if the element should be popped from +head or tail. The command returns NULL if: +1) The list is empty. +2) The key was not open for writing. +3) The key is not a list. - The 'mode' is composed by bitwise OR-ing the following flags: +## `RM_ZsetAddFlagsToCoreFlags` - REDISMODULE_READ -- Read access - REDISMODULE_WRITE -- Write access + int RM_ZsetAddFlagsToCoreFlags(int flags); - If the DMA is not requested for writing, the pointer returned should - only be accessed in a read-only fashion. +Conversion from/to public flags of the Modules API and our private flags, +so that we have everything decoupled. - On error (wrong type) NULL is returned. +## `RM_ZsetAddFlagsFromCoreFlags` - DMA access rules: + int RM_ZsetAddFlagsFromCoreFlags(int flags); - 1. No other key writing function should be called since the moment - the pointer is obtained, for all the time we want to use DMA access - to read or modify the string. +See previous function comment. - 2. Each time RM_StringTruncate() is called, to continue with the DMA - access, RM_StringDMA() should be called again to re-obtain - a new pointer and length. +## `RM_ZsetAdd` - 3. If the returned pointer is not NULL, but the length is zero, no - byte can be touched (the string is empty, or the key itself is empty) - so a RM_StringTruncate() call should be used if there is to enlarge - the string, and later call StringDMA() again to get the pointer. + int RM_ZsetAdd(RedisModuleKey *key, double score, RedisModuleString *ele, int *flagsptr); +Add a new element into a sorted set, with the specified 'score'. +If the element already exists, the score is updated. -### RedisModule_StringTruncate -``` -int RedisModule_StringTruncate(RedisModuleKey *key, size_t newlen) { -``` - If the string is open for writing and is of string type, resize it, padding - with zero bytes if the new length is greater than the old one. +A new sorted set is created at value if the key is an empty open key +setup for writing. - After this call, RM_StringDMA() must be called again to continue - DMA access with the new pointer. +Additional flags can be passed to the function via a pointer, the flags +are both used to receive input and to communicate state when the function +returns. 'flagsptr' can be NULL if no special flags are used. - The function returns REDISMODULE_OK on success, and REDISMODULE_ERR on - error, that is, the key is not open for writing, is not a string - or resizing for more than 512 MB is requested. +The input flags are: - If the key is empty, a string key is created with the new string value - unless the new length value requested is zero. +`REDISMODULE_ZADD_XX`: Element must already exist. Do nothing otherwise. +`REDISMODULE_ZADD_NX`: Element must not exist. Do nothing otherwise. +The output flags are: -### RedisModule_ListPush -``` -int RedisModule_ListPush(RedisModuleKey *key, int where, RedisModuleString *ele) { -``` - Push an element into a list, on head or tail depending on 'where' argumnet. - If the key pointer is about an empty key opened for writing, the key - is created. On error (key opened for read-only operations or of the wrong - type) REDISMODULE_ERR is returned, otherwise REDISMODULE_OK is returned. +`REDISMODULE_ZADD_ADDED`: The new element was added to the sorted set. +`REDISMODULE_ZADD_UPDATED`: The score of the element was updated. +`REDISMODULE_ZADD_NOP`: No operation was performed because XX or NX flags. +On success the function returns `REDISMODULE_OK`. On the following errors +`REDISMODULE_ERR` is returned: -### RedisModule_ListPop -``` -RedisModuleString *RedisModule_ListPop(RedisModuleKey *key, int where) { -``` - Pop an element from the list, and returns it as a module string object - that the user should be free with RM_FreeString() or by enabling - automatic memory. 'where' specifies if the element should be popped from - head or tail. The command returns NULL if: - 1) The list is empty. - 2) The key was not open for writing. - 3) The key is not a list. +* The key was not opened for writing. +* The key is of the wrong type. +* 'score' double value is not a number (NaN). +## `RM_ZsetIncrby` -### RedisModule_ZsetAddFlagsToCoreFlags -``` -int RedisModule_ZsetAddFlagsToCoreFlags(int flags) { -``` - Conversion from/to public flags of the Modules API and our private flags, - so that we have everything decoupled. + int RM_ZsetIncrby(RedisModuleKey *key, double score, RedisModuleString *ele, int *flagsptr, double *newscore); +This function works exactly like `RM_ZsetAdd()`, but instead of setting +a new score, the score of the existing element is incremented, or if the +element does not already exist, it is added assuming the old score was +zero. -### RedisModule_ZsetAddFlagsFromCoreFlags -``` -int RedisModule_ZsetAddFlagsFromCoreFlags(int flags) { -``` - See previous function comment. +The input and output flags, and the return value, have the same exact +meaning, with the only difference that this function will return +`REDISMODULE_ERR` even when 'score' is a valid double number, but adding it +to the existing score resuts into a NaN (not a number) condition. +This function has an additional field 'newscore', if not NULL is filled +with the new score of the element after the increment, if no error +is returned. -### RedisModule_ZsetAdd -``` -int RedisModule_ZsetAdd(RedisModuleKey *key, double score, RedisModuleString *ele, int *flagsptr) { -``` - Add a new element into a sorted set, with the specified 'score'. - If the element already exists, the score is updated. +## `RM_ZsetRem` - A new sorted set is created at value if the key is an empty open key - setup for writing. + int RM_ZsetRem(RedisModuleKey *key, RedisModuleString *ele, int *deleted); - Additional flags can be passed to the function via a pointer, the flags - are both used to receive input and to communicate state when the function - returns. 'flagsptr' can be NULL if no special flags are used. +Remove the specified element from the sorted set. +The function returns `REDISMODULE_OK` on success, and `REDISMODULE_ERR` +on one of the following conditions: - The input flags are: +* The key was not opened for writing. +* The key is of the wrong type. - REDISMODULE_ZADD_XX: Element must already exist. Do nothing otherwise. - REDISMODULE_ZADD_NX: Element must not exist. Do nothing otherwise. +The return value does NOT indicate the fact the element was really +removed (since it existed) or not, just if the function was executed +with success. - The output flags are: +In order to know if the element was removed, the additional argument +'deleted' must be passed, that populates the integer by reference +setting it to 1 or 0 depending on the outcome of the operation. +The 'deleted' argument can be NULL if the caller is not interested +to know if the element was really removed. - REDISMODULE_ZADD_ADDED: The new element was added to the sorted set. - REDISMODULE_ZADD_UPDATED: The score of the element was updated. - REDISMODULE_ZADD_NOP: No operation was performed because XX or NX flags. +Empty keys will be handled correctly by doing nothing. - On success the function returns REDISMODULE_OK. On the following errors - REDISMODULE_ERR is returned: +## `RM_ZsetScore` - * The key was not opened for writing. - * The key is of the wrong type. - * 'score' double value is not a number (NaN). + int RM_ZsetScore(RedisModuleKey *key, RedisModuleString *ele, double *score); +On success retrieve the double score associated at the sorted set element +'ele' and returns `REDISMODULE_OK`. Otherwise `REDISMODULE_ERR` is returned +to signal one of the following conditions: -### RedisModule_ZsetIncrby -``` -int RedisModule_ZsetIncrby(RedisModuleKey *key, double score, RedisModuleString *ele, int *flagsptr, double *newscore) { -``` - This function works exactly like RM_ZsetAdd(), but instead of setting - a new score, the score of the existing element is incremented, or if the - element does not already exist, it is added assuming the old score was - zero. +* There is no such element 'ele' in the sorted set. +* The key is not a sorted set. +* The key is an open empty key. - The input and output flags, and the return value, have the same exact - meaning, with the only difference that this function will return - REDISMODULE_ERR even when 'score' is a valid double number, but adding it - to the existing score resuts into a NaN (not a number) condition. +## `RM_ZsetRangeStop` - This function has an additional field 'newscore', if not NULL is filled - with the new score of the element after the increment, if no error - is returned. + void RM_ZsetRangeStop(RedisModuleKey *key); +Stop a sorted set iteration. -### RedisModule_ZsetRem -``` -int RedisModule_ZsetRem(RedisModuleKey *key, RedisModuleString *ele, int *deleted) { -``` - Remove the specified element from the sorted set. - The function returns REDISMODULE_OK on success, and REDISMODULE_ERR - on one of the following conditions: +## `RM_ZsetRangeEndReached` - * The key was not opened for writing. - * The key is of the wrong type. - - The return value does NOT indicate the fact the element was really - removed (since it existed) or not, just if the function was executed - with success. + int RM_ZsetRangeEndReached(RedisModuleKey *key); - In order to know if the element was removed, the additional argument - 'deleted' must be passed, that populates the integer by reference - setting it to 1 or 0 depending on the outcome of the operation. - The 'deleted' argument can be NULL if the caller is not interested - to know if the element was really removed. - - Empty keys will be handled correctly by doing nothing. +Return the "End of range" flag value to signal the end of the iteration. +## `RM_ZsetFirstInScoreRange` -### RedisModule_ZsetScore -``` -int RedisModule_ZsetScore(RedisModuleKey *key, RedisModuleString *ele, double *score) { -``` - On success retrieve the double score associated at the sorted set element - 'ele' and returns REDISMODULE_OK. Otherwise REDISMODULE_ERR is returned - to signal one of the following conditions: + int RM_ZsetFirstInScoreRange(RedisModuleKey *key, double min, double max, int minex, int maxex); - * There is no such element 'ele' in the sorted set. - * The key is not a sorted set. - * The key is an open empty key. +Setup a sorted set iterator seeking the first element in the specified +range. Returns `REDISMODULE_OK` if the iterator was correctly initialized +otherwise `REDISMODULE_ERR` is returned in the following conditions: +1. The value stored at key is not a sorted set or the key is empty. -### RedisModule_ZsetRangeStop -``` -void RedisModule_ZsetRangeStop(RedisModuleKey *key) { -``` - Stop a sorted set iteration. +The range is specified according to the two double values 'min' and 'max'. +Both can be infinite using the following two macros: +`REDISMODULE_POSITIVE_INFINITE` for positive infinite value +`REDISMODULE_NEGATIVE_INFINITE` for negative infinite value -### RedisModule_ZsetRangeEndReached -``` -int RedisModule_ZsetRangeEndReached(RedisModuleKey *key) { -``` - Return the "End of range" flag value to signal the end of the iteration. +'minex' and 'maxex' parameters, if true, respectively setup a range +where the min and max value are exclusive (not included) instead of +inclusive. +## `RM_ZsetLastInScoreRange` -### RedisModule_ZsetFirstInScoreRange -``` -int RedisModule_ZsetFirstInScoreRange(RedisModuleKey *key, double min, double max, int minex, int maxex) { -``` - Setup a sorted set iterator seeking the first element in the specified - range. Returns REDISMODULE_OK if the iterator was correctly initialized - otherwise REDISMODULE_ERR is returned in the following conditions: + int RM_ZsetLastInScoreRange(RedisModuleKey *key, double min, double max, int minex, int maxex); - 1. The value stored at key is not a sorted set or the key is empty. +Exactly like `RedisModule_ZsetFirstInScoreRange()` but the last element of +the range is selected for the start of the iteration instead. - The range is specified according to the two double values 'min' and 'max'. - Both can be infinite using the following two macros: +## `RM_ZsetFirstInLexRange` - REDISMODULE_POSITIVE_INFINITE for positive infinite value - REDISMODULE_NEGATIVE_INFINITE for negative infinite value + int RM_ZsetFirstInLexRange(RedisModuleKey *key, RedisModuleString *min, RedisModuleString *max); - 'minex' and 'maxex' parameters, if true, respectively setup a range - where the min and max value are exclusive (not included) instead of - inclusive. +Setup a sorted set iterator seeking the first element in the specified +lexicographical range. Returns `REDISMODULE_OK` if the iterator was correctly +initialized otherwise `REDISMODULE_ERR` is returned in the +following conditions: +1. The value stored at key is not a sorted set or the key is empty. +2. The lexicographical range 'min' and 'max' format is invalid. -### RedisModule_ZsetLastInScoreRange -``` -int RedisModule_ZsetLastInScoreRange(RedisModuleKey *key, double min, double max, int minex, int maxex) { -``` - Exactly like RedisModule_ZsetFirstInScoreRange() but the last element of - the range is selected for the start of the iteration instead. +'min' and 'max' should be provided as two RedisModuleString objects +in the same format as the parameters passed to the ZRANGEBYLEX command. +The function does not take ownership of the objects, so they can be released +ASAP after the iterator is setup. +## `RM_ZsetLastInLexRange` -### RedisModule_ZsetFirstInLexRange -``` -int RedisModule_ZsetFirstInLexRange(RedisModuleKey *key, RedisModuleString *min, RedisModuleString *max) { -``` - Setup a sorted set iterator seeking the first element in the specified - lexicographical range. Returns REDISMODULE_OK if the iterator was correctly - initialized otherwise REDISMODULE_ERR is returned in the - following conditions: + int RM_ZsetLastInLexRange(RedisModuleKey *key, RedisModuleString *min, RedisModuleString *max); - 1. The value stored at key is not a sorted set or the key is empty. - 2. The lexicographical range 'min' and 'max' format is invalid. +Exactly like `RedisModule_ZsetFirstInLexRange()` but the last element of +the range is selected for the start of the iteration instead. - 'min' and 'max' should be provided as two RedisModuleString objects - in the same format as the parameters passed to the ZRANGEBYLEX command. - The function does not take ownership of the objects, so they can be released - ASAP after the iterator is setup. +## `RM_ZsetRangeCurrentElement` + RedisModuleString *RM_ZsetRangeCurrentElement(RedisModuleKey *key, double *score); -### RedisModule_ZsetLastInLexRange -``` -int RedisModule_ZsetLastInLexRange(RedisModuleKey *key, RedisModuleString *min, RedisModuleString *max) { -``` - Exactly like RedisModule_ZsetFirstInLexRange() but the last element of - the range is selected for the start of the iteration instead. +Return the current sorted set element of an active sorted set iterator +or NULL if the range specified in the iterator does not include any +element. +## `RM_ZsetRangeNext` -### RedisModule_ZsetRangeCurrentElement -``` -RedisModuleString *RedisModule_ZsetRangeCurrentElement(RedisModuleKey *key, double *score) { -``` - Return the current sorted set element of an active sorted set iterator - or NULL if the range specified in the iterator does not include any - element. + int RM_ZsetRangeNext(RedisModuleKey *key); +Go to the next element of the sorted set iterator. Returns 1 if there was +a next element, 0 if we are already at the latest element or the range +does not include any item at all. -### RedisModule_ZsetRangeNext -``` -int RedisModule_ZsetRangeNext(RedisModuleKey *key) { -``` - Go to the next element of the sorted set iterator. Returns 1 if there was - a next element, 0 if we are already at the latest element or the range - does not include any item at all. +## `RM_ZsetRangePrev` + int RM_ZsetRangePrev(RedisModuleKey *key); -### RedisModule_ZsetRangePrev -``` -int RedisModule_ZsetRangePrev(RedisModuleKey *key) { -``` - Go to the previous element of the sorted set iterator. Returns 1 if there was - a previous element, 0 if we are already at the first element or the range - does not include any item at all. +Go to the previous element of the sorted set iterator. Returns 1 if there was +a previous element, 0 if we are already at the first element or the range +does not include any item at all. +## `RM_HashSet` -### RedisModule_HashSet -``` -int RedisModule_HashSet(RedisModuleKey *key, int flags, ...) { -``` - Set the field of the specified hash field to the specified value. - If the key is an empty key open for writing, it is created with an empty - hash value, in order to set the specified field. + int RM_HashSet(RedisModuleKey *key, int flags, ...); - The function is variadic and the user must specify pairs of field - names and values, both as RedisModuleString pointers (unless the - CFIELD option is set, see later). +Set the field of the specified hash field to the specified value. +If the key is an empty key open for writing, it is created with an empty +hash value, in order to set the specified field. - Example to set the hash argv[1] to the value argv[2]: +The function is variadic and the user must specify pairs of field +names and values, both as RedisModuleString pointers (unless the +CFIELD option is set, see later). - RedisModule_HashSet(key,REDISMODULE_HASH_NONE,argv[1],argv[2],NULL); +Example to set the hash argv[1] to the value argv[2]: - The function can also be used in order to delete fields (if they exist) - by setting them to the specified value of REDISMODULE_HASH_DELETE: + `RedisModule_HashSet(key`,`REDISMODULE_HASH_NONE`,argv[1],argv[2],NULL); - RedisModule_HashSet(key,REDISMODULE_HASH_NONE,argv[1], - REDISMODULE_HASH_DELETE,NULL); +The function can also be used in order to delete fields (if they exist) +by setting them to the specified value of `REDISMODULE_HASH_DELETE`: - The behavior of the command changes with the specified flags, that can be - set to REDISMODULE_HASH_NONE if no special behavior is needed. + `RedisModule_HashSet(key`,`REDISMODULE_HASH_NONE`,argv[1], + `REDISMODULE_HASH_DELETE`,NULL); - REDISMODULE_HASH_NX: The operation is performed only if the field was not - already existing in the hash. - REDISMODULE_HASH_XX: The operation is performed only if the field was - already existing, so that a new value could be - associated to an existing filed, but no new fields - are created. - REDISMODULE_HASH_CFIELDS: The field names passed are null terminated C - strings instead of RedisModuleString objects. +The behavior of the command changes with the specified flags, that can be +set to `REDISMODULE_HASH_NONE` if no special behavior is needed. - Unless NX is specified, the command overwrites the old field value with - the new one. +`REDISMODULE_HASH_NX`: The operation is performed only if the field was not + already existing in the hash. +`REDISMODULE_HASH_XX`: The operation is performed only if the field was + already existing, so that a new value could be + associated to an existing filed, but no new fields + are created. +`REDISMODULE_HASH_CFIELDS`: The field names passed are null terminated C + strings instead of RedisModuleString objects. - When using REDISMODULE_HASH_CFIELDS, field names are reported using - normal C strings, so for example to delete the field "foo" the following - code can be used: +Unless NX is specified, the command overwrites the old field value with +the new one. - RedisModule_HashSet(key,REDISMODULE_HASH_CFIELDS,"foo", - REDISMODULE_HASH_DELETE,NULL); +When using `REDISMODULE_HASH_CFIELDS`, field names are reported using +normal C strings, so for example to delete the field "foo" the following +code can be used: - Return value: + `RedisModule_HashSet(key`,`REDISMODULE_HASH_CFIELDS`,"foo", + `REDISMODULE_HASH_DELETE`,NULL); - The number of fields updated (that may be less than the number of fields - specified because of the XX or NX options). +Return value: - In the following case the return value is always zero: +The number of fields updated (that may be less than the number of fields +specified because of the XX or NX options). - * The key was not open for writing. - * The key was associated with a non Hash value. +In the following case the return value is always zero: +* The key was not open for writing. +* The key was associated with a non Hash value. -### RedisModule_HashGet -``` -int RedisModule_HashGet(RedisModuleKey *key, int flags, ...) { -``` - Get fields from an hash value. This function is called using a variable - number of arguments, alternating a field name (as a StringRedisModule - pointer) with a pointer to a StringRedisModule pointer, that is set to the - value of the field if the field exist, or NULL if the field did not exist. - At the end of the field/value-ptr pairs, NULL must be specified as last - argument to signal the end of the arguments in the variadic function. +## `RM_HashGet` - This is an example usage: + int RM_HashGet(RedisModuleKey *key, int flags, ...); - RedisModuleString *first, *second; - RedisModule_HashGet(mykey,REDISMODULE_HASH_NONE,argv[1],&first, - argv[2],&second,NULL); +Get fields from an hash value. This function is called using a variable +number of arguments, alternating a field name (as a StringRedisModule +pointer) with a pointer to a StringRedisModule pointer, that is set to the +value of the field if the field exist, or NULL if the field did not exist. +At the end of the field/value-ptr pairs, NULL must be specified as last +argument to signal the end of the arguments in the variadic function. - As with RedisModule_HashSet() the behavior of the command can be specified - passing flags different than REDISMODULE_HASH_NONE: +This is an example usage: - REDISMODULE_HASH_CFIELD: field names as null terminated C strings. + RedisModuleString *first, *second; + `RedisModule_HashGet(mykey`,`REDISMODULE_HASH_NONE`,argv[1],&first, + argv[2],&second,NULL); - REDISMODULE_HASH_EXISTS: instead of setting the value of the field - expecting a RedisModuleString pointer to pointer, the function just - reports if the field esists or not and expects an integer pointer - as the second element of each pair. +As with `RedisModule_HashSet()` the behavior of the command can be specified +passing flags different than `REDISMODULE_HASH_NONE`: - Example of REDISMODULE_HASH_CFIELD: +`REDISMODULE_HASH_CFIELD`: field names as null terminated C strings. - RedisModuleString *username, *hashedpass; - RedisModule_HashGet(mykey,"username",&username,"hp",&hashedpass, NULL); +`REDISMODULE_HASH_EXISTS`: instead of setting the value of the field +expecting a RedisModuleString pointer to pointer, the function just +reports if the field esists or not and expects an integer pointer +as the second element of each pair. - Example of REDISMODULE_HASH_EXISTS: +Example of `REDISMODULE_HASH_CFIELD`: - int exists; - RedisModule_HashGet(mykey,argv[1],&exists,NULL); + RedisModuleString *username, *hashedpass; + `RedisModule_HashGet(mykey`,"username",&username,"hp",&hashedpass, NULL); - The function returns REDISMODULE_OK on success and REDISMODULE_ERR if - the key is not an hash value. +Example of `REDISMODULE_HASH_EXISTS`: - Memory management: + int exists; + `RedisModule_HashGet(mykey`,argv[1],&exists,NULL); - The returned RedisModuleString objects should be released with - RedisModule_FreeString(), or by enabling automatic memory management. +The function returns `REDISMODULE_OK` on success and `REDISMODULE_ERR` if +the key is not an hash value. +Memory management: -### RedisModule_FreeCallReply_Rec -``` -void RedisModule_FreeCallReply_Rec(RedisModuleCallReply *reply, int freenested){ -``` - Free a Call reply and all the nested replies it contains if it's an - array. +The returned RedisModuleString objects should be released with +`RedisModule_FreeString()`, or by enabling automatic memory management. +## `RM_FreeCallReply_Rec` -### RedisModule_FreeCallReply -``` -void RedisModule_FreeCallReply(RedisModuleCallReply *reply) { -``` - Wrapper for the recursive free reply function. This is needed in order - to have the first level function to return on nested replies, but only - if called by the module API. + void RM_FreeCallReply_Rec(RedisModuleCallReply *reply, int freenested); +Free a Call reply and all the nested replies it contains if it's an +array. -### RedisModule_CallReplyType -``` -int RedisModule_CallReplyType(RedisModuleCallReply *reply) { -``` - Return the reply type. - - -### RedisModule_CallReplyLength -``` -size_t RedisModule_CallReplyLength(RedisModuleCallReply *reply) { -``` - Return the reply type length, where applicable. +## `RM_FreeCallReply` + void RM_FreeCallReply(RedisModuleCallReply *reply); -### RedisModule_CallReplyArrayElement -``` -RedisModuleCallReply *RedisModule_CallReplyArrayElement(RedisModuleCallReply *reply, size_t idx) { -``` - Return the 'idx'-th nested call reply element of an array reply, or NULL - if the reply type is wrong or the index is out of range. - - -### RedisModule_CallReplyInteger -``` -long long RedisModule_CallReplyInteger(RedisModuleCallReply *reply) { -``` - Return the long long of an integer reply. - - -### RedisModule_CallReplyStringPtr -``` -const char *RedisModule_CallReplyStringPtr(RedisModuleCallReply *reply, size_t *len) { -``` - Return the pointer and length of a string or error reply. - - -### RedisModule_CreateStringFromCallReply -``` -RedisModuleString *RedisModule_CreateStringFromCallReply(RedisModuleCallReply *reply) { -``` - Return a new string object from a call reply of type string, error or - integer. Otherwise (wrong reply type) return NULL. - - -### RedisModule_Call -``` -RedisModuleCallReply *RedisModule_Call(RedisModuleCtx *ctx, const char *cmdname, const char *fmt, ...) { -``` - Exported API to call any Redis command from modules. - On success a RedisModuleCallReply object is returned, otherwise - NULL is returned and errno is set to the following values: - - EINVAL: command non existing, wrong arity, wrong format specifier. - EPERM: operation in Cluster instance with key in non local slot. - - -### RedisModule_CallReplyProto -``` -const char *RedisModule_CallReplyProto(RedisModuleCallReply *reply, size_t *len) { -``` - Return a pointer, and a length, to the protocol returned by the command - that returned the reply object. - - -### RedisModule_CreateDataType -``` -moduleType *RedisModule_CreateDataType(RedisModuleCtx *ctx, const char *name, int encver, moduleTypeLoadFunc rdb_load, moduleTypeSaveFunc rdb_save, moduleTypeRewriteFunc aof_rewrite, moduleTypeDigestFunc digest, moduleTypeFreeFunc free) { -``` - Register a new data type exported by the module. The parameters are the - following. Please for in depth documentation check the modules API - documentation, especially the INTRO.md file. - - * **name**: A 9 characters data type name that MUST be unique in the Redis - Modules ecosystem. Be creative... and there will be no collisions. Use - the charset A-Z a-z 9-0, plus the two "-_" characters. A good - idea is to use, for example `-`. For example - "tree-AntZ" may mean "Tree data structure by @antirez". To use both - lower case and upper case letters helps in order to prevent collisions. - * **encver**: Encoding version, which is, the version of the serialization - that a module used in order to persist data. As long as the "name" - matches, the RDB loading will be dispatched to the type callbacks - whatever 'encver' is used, however the module can understand if - the encoding it must load are of an older version of the module. - For example the module "tree-AntZ" initially used encver=0. Later - after an upgrade, it started to serialize data in a different format - and to register the type with encver=1. However this module may - still load old data produced by an older version if the rdb_load - callback is able to check the encver value and act accordingly. - The encver must be a positive value between 0 and 1023. - * **rdb_load**: A callback function pointer that loads data from RDB files. - * **rdb_save**: A callback function pointer that saves data to RDB files. - * **aof_rewrite**: A callback function pointer that rewrites data as commands. - * **digest**: A callback function pointer that is used for `DEBUG DIGEST`. - * **free**: A callback function pointer that can free a type value. - - Note: the module name "AAAAAAAAA" is reserved and produces an error, it - happens to be pretty lame as well. - - If there is already a module registering a type with the same name, - and if the module name or encver is invalid, NULL is returned. - Otherwise the new type is registered into Redis, and a reference of - type RedisModuleType is returned: the caller of the function should store - this reference into a gobal variable to make future use of it in the - modules type API, since a single module may register multiple types. - Example code fragment: - - static RedisModuleType *BalancedTreeType; - - int RedisModule_OnLoad(RedisModuleCtx *ctx) { - // some code here ... - BalancedTreeType = RM_CreateDataType(...); - } - - -### RedisModule_ModuleTypeSetValue -``` -int RedisModule_ModuleTypeSetValue(RedisModuleKey *key, moduleType *mt, void *value) { -``` - If the key is open for writing, set the specified module type object - as the value of the key, deleting the old value if any. - On success REDISMODULE_OK is returned. If the key is not open for - writing or there is an active iterator, REDISMODULE_ERR is returned. - - -### RedisModule_ModuleTypeGetType -``` -moduleType *RedisModule_ModuleTypeGetType(RedisModuleKey *key) { -``` - Assuming RedisModule_KeyType() returned REDISMODULE_KEYTYPE_MODULE on - the key, returns the moduel type pointer of the value stored at key. - - If the key is NULL, is not associated with a module type, or is empty, - then NULL is returned instead. - - -### RedisModule_ModuleTypeGetValue -``` -void *RedisModule_ModuleTypeGetValue(RedisModuleKey *key) { -``` - Assuming RedisModule_KeyType() returned REDISMODULE_KEYTYPE_MODULE on - the key, returns the module type low-level value stored at key, as - it was set by the user via RedisModule_ModuleTypeSet(). - - If the key is NULL, is not associated with a module type, or is empty, - then NULL is returned instead. - - -### RedisModule_SaveUnsigned -``` -void RedisModule_SaveUnsigned(RedisModuleIO *io, uint64_t value) { -``` - Save an unsigned 64 bit value into the RDB file. This function should only - be called in the context of the rdb_save method of modules implementing new - data types. - - -### RedisModule_LoadUnsigned -``` -uint64_t RedisModule_LoadUnsigned(RedisModuleIO *io) { -``` - Load an unsigned 64 bit value from the RDB file. This function should only - be called in the context of the rdb_load method of modules implementing - new data types. - - -### RedisModule_SaveSigned -``` -void RedisModule_SaveSigned(RedisModuleIO *io, int64_t value) { -``` - Like RedisModule_SaveUnsigned() but for signed 64 bit values. - - -### RedisModule_LoadSigned -``` -int64_t RedisModule_LoadSigned(RedisModuleIO *io) { -``` - Like RedisModule_LoadUnsigned() but for signed 64 bit values. - - -### RedisModule_SaveString -``` -void RedisModule_SaveString(RedisModuleIO *io, RedisModuleString *s) { -``` - In the context of the rdb_save method of a module type, saves a - string into the RDB file taking as input a RedisModuleString. - - The string can be later loaded with RedisModule_LoadString() or - other Load family functions expecting a serialized string inside - the RDB file. - - -### RedisModule_SaveStringBuffer -``` -void RedisModule_SaveStringBuffer(RedisModuleIO *io, const char *str, size_t len) { -``` - Like RedisModule_SaveString() but takes a raw C pointer and length - as input. - - -### RedisModule_LoadString -``` -RedisModuleString *RedisModule_LoadString(RedisModuleIO *io) { -``` - In the context of the rdb_load method of a module data type, loads a string - from the RDB file, that was previously saved with RedisModule_SaveString() - functions family. - - The returned string is a newly allocated RedisModuleString object, and - the user should at some point free it with a call to RedisModule_FreeString(). - - If the data structure does not store strings as RedisModuleString objects, - the similar function RedisModule_LoadStringBuffer() could be used instead. - - -### RedisModule_LoadStringBuffer -``` -char *RedisModule_LoadStringBuffer(RedisModuleIO *io, size_t *lenptr) { -``` - Like RedisModule_LoadString() but returns an heap allocated string that - was allocated with RedisModule_Alloc(), and can be resized or freed with - RedisModule_Realloc() or RedisModule_Free(). +Wrapper for the recursive free reply function. This is needed in order +to have the first level function to return on nested replies, but only +if called by the module API. - The size of the string is stored at '*lenptr' if not NULL. - The returned string is not automatically NULL termianted, it is loaded - exactly as it was stored inisde the RDB file. - - -### RedisModule_SaveDouble -``` -void RedisModule_SaveDouble(RedisModuleIO *io, double value) { -``` - In the context of the rdb_save method of a module data type, saves a double - value to the RDB file. The double can be a valid number, a NaN or infinity. - It is possible to load back the value with RedisModule_LoadDouble(). - - -### RedisModule_LoadDouble -``` -double RedisModule_LoadDouble(RedisModuleIO *io) { -``` - In the context of the rdb_save method of a module data type, loads back the - double value saved by RedisModule_SaveDouble(). - - -### RedisModule_SaveFloat -``` -void RedisModule_SaveFloat(RedisModuleIO *io, float value) { -``` - In the context of the rdb_save method of a module data type, saves a float - value to the RDB file. The float can be a valid number, a NaN or infinity. - It is possible to load back the value with RedisModule_LoadFloat(). - - -### RedisModule_LoadFloat -``` -float RedisModule_LoadFloat(RedisModuleIO *io) { -``` - In the context of the rdb_save method of a module data type, loads back the - float value saved by RedisModule_SaveFloat(). - - -### RedisModule_EmitAOF -``` -void RedisModule_EmitAOF(RedisModuleIO *io, const char *cmdname, const char *fmt, ...) { -``` - Emits a command into the AOF during the AOF rewriting process. This function - is only called in the context of the aof_rewrite method of data types exported - by a module. The command works exactly like RedisModule_Call() in the way - the parameters are passed, but it does not return anything as the error - handling is performed by Redis itself. - - -### RedisModule_GetContextFromIO -``` -RedisModuleCtx *RedisModule_GetContextFromIO(RedisModuleIO *io) { -``` - -------------------------------------------------------------------------- - IO context handling - -------------------------------------------------------------------------- - - -### RedisModule_LogRaw -``` -void RedisModule_LogRaw(RedisModule *module, const char *levelstr, const char *fmt, va_list ap) { -``` - This is the low level function implementing both: - - RM_Log() - RM_LogIOError() - - -### RedisModule_Log -``` -void RedisModule_Log(RedisModuleCtx *ctx, const char *levelstr, const char *fmt, ...) { -``` - Produces a log message to the standard Redis log, the format accepts - printf-alike specifiers, while level is a string describing the log - level to use when emitting the log, and must be one of the following: - - * "debug" - * "verbose" - * "notice" - * "warning" - - If the specified log level is invalid, verbose is used by default. - There is a fixed limit to the length of the log line this function is able - to emit, this limti is not specified but is guaranteed to be more than - a few lines of text. - - -### RedisModule_LogIOError -``` -void RedisModule_LogIOError(RedisModuleIO *io, const char *levelstr, const char *fmt, ...) { -``` - Log errors from RDB / AOF serialization callbacks. - - This function should be used when a callback is returning a critical - error to the caller since cannot load or save the data for some - critical reason. - - -### RMUtil_ArgExists -``` -int RMUtil_ArgExists(const char *arg, RedisModuleString **argv, int argc, int offset); -``` - Return the offset of an arg if it exists in the arg list, or 0 if it's not there - - -### RMUtil_ParseArgs -``` -int RMUtil_ParseArgs(RedisModuleString **argv, int argc, int offset, const char *fmt, ...); -``` -Automatically conver the arg list to corresponding variable pointers according to a given format. -You pass it the command arg list and count, the starting offset, a parsing format, and pointers to the variables. -The format is a string consisting of the following identifiers: - - c -- pointer to a Null terminated C string pointer. - s -- pointer to a RedisModuleString - l -- pointer to Long long integer. - d -- pointer to a Double - * -- do not parse this argument at all - -Example: If I want to parse args[1], args[2] as a long long and double, I do: - double d; - long long l; - RMUtil_ParseArgs(argv, argc, 1, "ld", &l, &d); - - -### RMUtil_ParseArgsAfter -``` -int RMUtil_ParseArgsAfter(const char *token, RedisModuleString **argv, int argc, const char *fmt, ...); -``` -Same as RMUtil_ParseArgs, but only parses the arguments after `token`, if it was found. -This is useful for optional stuff like [LIMIT [offset] [limit]] - - -### RMUtil_GetRedisInfo -``` -RMUtilInfo *RMUtil_GetRedisInfo(RedisModuleCtx *ctx); -``` - Get redis INFO result and parse it as RMUtilInfo. - Returns NULL if something goes wrong. - The resulting object needs to be freed with RMUtilRedisInfo_Free - - -### RMUtil_CreateFormattedString -``` -RedisModuleString *RMUtil_CreateFormattedString(RedisModuleCtx *ctx, const char *fmt, ...); -``` - Create a new RedisModuleString object from a printf-style format and arguments. - Note that RedisModuleString objects CANNOT be used as formatting arguments. - - -### RMUtil_StringEquals -``` -int RMUtil_StringEquals(RedisModuleString *s1, RedisModuleString *s2); -``` - Return 1 if the two strings are equal. Case *sensitive* +## `RM_CallReplyType` + int RM_CallReplyType(RedisModuleCallReply *reply); -### RMUtil_StringEqualsC -``` -int RMUtil_StringEqualsC(RedisModuleString *s1, const char *s2); -``` - Return 1 if the string is equal to a C NULL terminated string. Case *sensitive* +Return the reply type. +## `RM_CallReplyLength` -### RMUtil_StringToLower -``` -void RMUtil_StringToLower(RedisModuleString *s); -``` - Converts a redis string to lowercase in place without reallocating anything - - -### RMUtil_StringToUpper -``` -void RMUtil_StringToUpper(RedisModuleString *s); -``` - Converts a redis string to uppercase in place without reallocating anything - - -### Vector_Get -``` -int Vector_Get(Vector *v, size_t pos, void *ptr); -``` - get the element at index pos. The value is copied in to ptr. If pos is outside - the vector capacity, we return 0 - otherwise 1 + size_t RM_CallReplyLength(RedisModuleCallReply *reply); +Return the reply type length, where applicable. -### Vector_Pop -``` -int Vector_Pop(Vector *v, void *ptr); -``` - Get the element at the end of the vector, decreasing the size by one - - -### Vector_Resize -``` -int Vector_Resize(Vector *v, size_t newcap); -``` - resize capacity of v - - -### Vector_Size -``` -int Vector_Size(Vector *v); -``` - return the used size of the vector, regardless of capacity - - -### Vector_Cap -``` -int Vector_Cap(Vector *v); -``` - return the actual capacity +## `RM_CallReplyArrayElement` + RedisModuleCallReply *RM_CallReplyArrayElement(RedisModuleCallReply *reply, size_t idx); -### Vector_Free -``` -void Vector_Free(Vector *v); -``` - free the vector and the underlying data. Does not release its elements if - they are pointers +Return the 'idx'-th nested call reply element of an array reply, or NULL +if the reply type is wrong or the index is out of range. + +## `RM_CallReplyInteger` + + long long RM_CallReplyInteger(RedisModuleCallReply *reply); + +Return the long long of an integer reply. + +## `RM_CallReplyStringPtr` + + const char *RM_CallReplyStringPtr(RedisModuleCallReply *reply, size_t *len); + +Return the pointer and length of a string or error reply. + +## `RM_CreateStringFromCallReply` + + RedisModuleString *RM_CreateStringFromCallReply(RedisModuleCallReply *reply); + +Return a new string object from a call reply of type string, error or +integer. Otherwise (wrong reply type) return NULL. + +## `RM_Call` + + RedisModuleCallReply *RM_Call(RedisModuleCtx *ctx, const char *cmdname, const char *fmt, ...); + +Exported API to call any Redis command from modules. +On success a RedisModuleCallReply object is returned, otherwise +NULL is returned and errno is set to the following values: + +EINVAL: command non existing, wrong arity, wrong format specifier. +EPERM: operation in Cluster instance with key in non local slot. + +## `RM_CallReplyProto` + + const char *RM_CallReplyProto(RedisModuleCallReply *reply, size_t *len); + +Return a pointer, and a length, to the protocol returned by the command +that returned the reply object. + +## `RM_CreateDataType` + + moduleType *RM_CreateDataType(RedisModuleCtx *ctx, const char *name, int encver, void *typemethods_ptr); + +Register a new data type exported by the module. The parameters are the +following. Please for in depth documentation check the modules API +documentation, especially the TYPES.md file. + +* **name**: A 9 characters data type name that MUST be unique in the Redis + Modules ecosystem. Be creative... and there will be no collisions. Use + the charset A-Z a-z 9-0, plus the two "-_" characters. A good + idea is to use, for example `-`. For example + "tree-AntZ" may mean "Tree data structure by @antirez". To use both + lower case and upper case letters helps in order to prevent collisions. +* **encver**: Encoding version, which is, the version of the serialization + that a module used in order to persist data. As long as the "name" + matches, the RDB loading will be dispatched to the type callbacks + whatever 'encver' is used, however the module can understand if + the encoding it must load are of an older version of the module. + For example the module "tree-AntZ" initially used encver=0. Later + after an upgrade, it started to serialize data in a different format + and to register the type with encver=1. However this module may + still load old data produced by an older version if the rdb_load + callback is able to check the encver value and act accordingly. + The encver must be a positive value between 0 and 1023. +* **typemethods_ptr** is a pointer to a RedisModuleTypeMethods structure + that should be populated with the methods callbacks and structure + version, like in the following example: + + RedisModuleTypeMethods tm = { + .version = `REDISMODULE_TYPE_METHOD_VERSION`, + .rdb_load = myType_RDBLoadCallBack, + .rdb_save = myType_RDBSaveCallBack, + .aof_rewrite = myType_AOFRewriteCallBack, + .free = myType_FreeCallBack, + + // Optional fields + .digest = myType_DigestCallBack, + .mem_usage = myType_MemUsageCallBack, + } + +* **rdb_load**: A callback function pointer that loads data from RDB files. +* **rdb_save**: A callback function pointer that saves data to RDB files. +* **aof_rewrite**: A callback function pointer that rewrites data as commands. +* **digest**: A callback function pointer that is used for `DEBUG DIGEST`. +* **free**: A callback function pointer that can free a type value. + +The **digest* and **mem_usage** methods should currently be omitted since +they are not yet implemented inside the Redis modules core. + +Note: the module name "AAAAAAAAA" is reserved and produces an error, it +happens to be pretty lame as well. + +If there is already a module registering a type with the same name, +and if the module name or encver is invalid, NULL is returned. +Otherwise the new type is registered into Redis, and a reference of +type RedisModuleType is returned: the caller of the function should store +this reference into a gobal variable to make future use of it in the +modules type API, since a single module may register multiple types. +Example code fragment: + + static RedisModuleType *BalancedTreeType; + + int `RedisModule_OnLoad(RedisModuleCtx` *ctx) { + // some code here ... + BalancedTreeType = `RM_CreateDataType(`...); + } + +## `RM_ModuleTypeSetValue` + + int RM_ModuleTypeSetValue(RedisModuleKey *key, moduleType *mt, void *value); + +If the key is open for writing, set the specified module type object +as the value of the key, deleting the old value if any. +On success `REDISMODULE_OK` is returned. If the key is not open for +writing or there is an active iterator, `REDISMODULE_ERR` is returned. + +## `RM_ModuleTypeGetType` + + moduleType *RM_ModuleTypeGetType(RedisModuleKey *key); + +Assuming `RedisModule_KeyType()` returned `REDISMODULE_KEYTYPE_MODULE` on +the key, returns the moduel type pointer of the value stored at key. + +If the key is NULL, is not associated with a module type, or is empty, +then NULL is returned instead. + +## `RM_ModuleTypeGetValue` + + void *RM_ModuleTypeGetValue(RedisModuleKey *key); + +Assuming `RedisModule_KeyType()` returned `REDISMODULE_KEYTYPE_MODULE` on +the key, returns the module type low-level value stored at key, as +it was set by the user via `RedisModule_ModuleTypeSet()`. + +If the key is NULL, is not associated with a module type, or is empty, +then NULL is returned instead. + +## `RM_SaveUnsigned` + + void RM_SaveUnsigned(RedisModuleIO *io, uint64_t value); + +Save an unsigned 64 bit value into the RDB file. This function should only +be called in the context of the rdb_save method of modules implementing new +data types. + +## `RM_LoadUnsigned` + + uint64_t RM_LoadUnsigned(RedisModuleIO *io); + +Load an unsigned 64 bit value from the RDB file. This function should only +be called in the context of the rdb_load method of modules implementing +new data types. + +## `RM_SaveSigned` + + void RM_SaveSigned(RedisModuleIO *io, int64_t value); + +Like `RedisModule_SaveUnsigned()` but for signed 64 bit values. + +## `RM_LoadSigned` + + int64_t RM_LoadSigned(RedisModuleIO *io); + +Like `RedisModule_LoadUnsigned()` but for signed 64 bit values. + +## `RM_SaveString` + + void RM_SaveString(RedisModuleIO *io, RedisModuleString *s); + +In the context of the rdb_save method of a module type, saves a +string into the RDB file taking as input a RedisModuleString. + +The string can be later loaded with `RedisModule_LoadString()` or +other Load family functions expecting a serialized string inside +the RDB file. + +## `RM_SaveStringBuffer` + + void RM_SaveStringBuffer(RedisModuleIO *io, const char *str, size_t len); + +Like `RedisModule_SaveString()` but takes a raw C pointer and length +as input. + +## `RM_LoadString` + + RedisModuleString *RM_LoadString(RedisModuleIO *io); + +In the context of the rdb_load method of a module data type, loads a string +from the RDB file, that was previously saved with `RedisModule_SaveString()` +functions family. + +The returned string is a newly allocated RedisModuleString object, and +the user should at some point free it with a call to `RedisModule_FreeString()`. + +If the data structure does not store strings as RedisModuleString objects, +the similar function `RedisModule_LoadStringBuffer()` could be used instead. + +## `RM_LoadStringBuffer` + + char *RM_LoadStringBuffer(RedisModuleIO *io, size_t *lenptr); + +Like `RedisModule_LoadString()` but returns an heap allocated string that +was allocated with `RedisModule_Alloc()`, and can be resized or freed with +`RedisModule_Realloc()` or `RedisModule_Free()`. + +The size of the string is stored at '*lenptr' if not NULL. +The returned string is not automatically NULL termianted, it is loaded +exactly as it was stored inisde the RDB file. + +## `RM_SaveDouble` + + void RM_SaveDouble(RedisModuleIO *io, double value); + +In the context of the rdb_save method of a module data type, saves a double +value to the RDB file. The double can be a valid number, a NaN or infinity. +It is possible to load back the value with `RedisModule_LoadDouble()`. + +## `RM_LoadDouble` + + double RM_LoadDouble(RedisModuleIO *io); + +In the context of the rdb_save method of a module data type, loads back the +double value saved by `RedisModule_SaveDouble()`. + +## `RM_SaveFloat` + + void RM_SaveFloat(RedisModuleIO *io, float value); + +In the context of the rdb_save method of a module data type, saves a float +value to the RDB file. The float can be a valid number, a NaN or infinity. +It is possible to load back the value with `RedisModule_LoadFloat()`. + +## `RM_LoadFloat` + + float RM_LoadFloat(RedisModuleIO *io); + +In the context of the rdb_save method of a module data type, loads back the +float value saved by `RedisModule_SaveFloat()`. + +## `RM_EmitAOF` + + void RM_EmitAOF(RedisModuleIO *io, const char *cmdname, const char *fmt, ...); + +Emits a command into the AOF during the AOF rewriting process. This function +is only called in the context of the aof_rewrite method of data types exported +by a module. The command works exactly like `RedisModule_Call()` in the way +the parameters are passed, but it does not return anything as the error +handling is performed by Redis itself. + +## `RM_LogRaw` + + void RM_LogRaw(RedisModule *module, const char *levelstr, const char *fmt, va_list ap); + +This is the low level function implementing both: + + `RM_Log()` + `RM_LogIOError()` + +## `RM_Log` + + void RM_Log(RedisModuleCtx *ctx, const char *levelstr, const char *fmt, ...); + +/* +Produces a log message to the standard Redis log, the format accepts +printf-alike specifiers, while level is a string describing the log +level to use when emitting the log, and must be one of the following: + +* "debug" +* "verbose" +* "notice" +* "warning" + +If the specified log level is invalid, verbose is used by default. +There is a fixed limit to the length of the log line this function is able +to emit, this limti is not specified but is guaranteed to be more than +a few lines of text. + +## `RM_LogIOError` + + void RM_LogIOError(RedisModuleIO *io, const char *levelstr, const char *fmt, ...); + +Log errors from RDB / AOF serialization callbacks. + +This function should be used when a callback is returning a critical +error to the caller since cannot load or save the data for some +critical reason. + +## `RM_BlockClient` + + RedisModuleBlockedClient *RM_BlockClient(RedisModuleCtx *ctx, RedisModuleCmdFunc reply_callback, RedisModuleCmdFunc timeout_callback, void (*free_privdata)(void*), long long timeout_ms); + +Block a client in the context of a blocking command, returning an handle +which will be used, later, in order to block the client with a call to +`RedisModule_UnblockClient()`. The arguments specify callback functions +and a timeout after which the client is unblocked. + +The callbacks are called in the following contexts: + +reply_callback: called after a successful `RedisModule_UnblockClient()` call + in order to reply to the client and unblock it. +reply_timeout: called when the timeout is reached in order to send an + error to the client. +free_privdata: called in order to free the privata data that is passed + by `RedisModule_UnblockClient()` call. + +## `RM_UnblockClient` + + int RM_UnblockClient(RedisModuleBlockedClient *bc, void *privdata); + +Unblock a client blocked by ``RedisModule_BlockedClient``. This will trigger +the reply callbacks to be called in order to reply to the client. +The 'privdata' argument will be accessible by the reply callback, so +the caller of this function can pass any value that is needed in order to +actually reply to the client. + +A common usage for 'privdata' is a thread that computes something that +needs to be passed to the client, included but not limited some slow +to compute reply or some reply obtained via networking. + +Note: this function can be called from threads spawned by the module. + +## `RM_AbortBlock` + + int RM_AbortBlock(RedisModuleBlockedClient *bc); + +Abort a blocked client blocking operation: the client will be unblocked +without firing the reply callback. + +## `RM_IsBlockedReplyRequest` + + int RM_IsBlockedReplyRequest(RedisModuleCtx *ctx); + +Return non-zero if a module command was called in order to fill the +reply for a blocked client. + +## `RM_IsBlockedTimeoutRequest` + + int RM_IsBlockedTimeoutRequest(RedisModuleCtx *ctx); + +Return non-zero if a module command was called in order to fill the +reply for a blocked client that timed out. + +## `RM_GetBlockedClientPrivateData` + + void *RM_GetBlockedClientPrivateData(RedisModuleCtx *ctx); + +Get the privata data set by `RedisModule_UnblockClient()`