From 832d8635e949fb24ee24cc86209524ea37773f3b Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 15:30:56 +0000 Subject: [PATCH] [automated site update] --- apidoc/html/index.html | 22 ++-- apidoc/html/navtreedata.js | 7 +- apidoc/html/navtreeindex0.js | 3 +- apidoc/html/search/all_10.js | 215 +++++++++++++++++------------------ apidoc/html/search/all_11.js | 2 +- apidoc/html/search/all_2.js | 11 +- apidoc/html/search/all_3.js | 2 +- apidoc/html/search/all_4.js | 2 +- apidoc/html/search/all_5.js | 3 +- apidoc/html/search/all_7.js | 2 +- apidoc/html/search/all_8.js | 13 +-- apidoc/html/search/all_e.js | 2 +- apidoc/html/toc.xml | 7 +- apidoc/redisx.tag | 1 - doc/README.md | 30 ++++- 15 files changed, 168 insertions(+), 154 deletions(-) diff --git a/apidoc/html/index.html b/apidoc/html/index.html index 5d82849..5900140 100644 --- a/apidoc/html/index.html +++ b/apidoc/html/index.html @@ -126,7 +126,6 @@

  • Simple Redis queries
  • Atomic execution blocks and LUA scripts
  • Publish/subscribe (PUB/SUB) support
    • -
  • Implementing further Redis commands
  • Error handling
  • Debug support
  • Future plans
    • @@ -383,9 +382,11 @@

  • Execution blocks
  • LUA script loading and execution
    • +

    Sometimes you want to ececute a series of Redis command atomically, such that nothing else may alter the database while the set of commands execute, so they may return a coherent state. For example, you want to set or query a collection of related variables so they change together and are reported together. You have two choices. (1) you can execute the Redis commands in an execution block, or else (2) load a LUA script onto the Redis server and call it with some parameters (possibly many times over).

    Execution blocks

    +

    Execution blocks offer a fairly simple way of bunching

    Redis *redis = ...;
    RESP *result;
    @@ -419,9 +420,12 @@

    redisxExecBlockAsync
    RESP * redisxExecBlockAsync(RedisClient *cl)
    Definition redisx-io.c:365
    INTERACTIVE_CHANNEL
    @ INTERACTIVE_CHANNEL
    Redis channel number for interactive queries.
    Definition redisx.h:103
    RedisClient
    Structure that represents a single Redis client connection instance.
    Definition redisx.h:139
    -

    +

    If at any point things don't go accoring to plan in the middle of the block, you can call redisAbortBlockAsync() to abort and discard all prior commands submitted in the execution block already.

    +

    LUA script loading and execution

    +

    LUA scripting offers a more capable version of executing more complex routines on the Redis server. LUA is a scripting language akin to python, and allows you to add extra logic, string manipulation etc to your Redis queries. Best of all, once you upload the script to the server, it can reduce network traffic significantly by not having to repeatedly submit the same set of Redis commands every single time. LUA scipts also get executed very efficiently on the server, and produce only the result you want/need.

    +

    Assuming you have prepared your LUA script, you can upload it to the Redis server as:

    Redis *redis = ...
    char *script = ... // The LUA script as a 0-terminated string.
    char *scriptSHA1 = NULL; // We'll store the SHA1 sum of the script here
    @@ -432,7 +436,8 @@

    // Oops, something went wrong...
    ...
    }
    -

    Redis *redis = ...
    +

    Redis will refer to the script by its SHA1 sum, so it's important keep a record of it. You'll call the script with its SHA1 sum, a set of redis keys the script may use, and a set of other parameters it might need.

    +
    Redis *redis = ...
    int status;
    // Execute the script, with one redis key argument (and no parameters)...
    @@ -441,6 +446,7 @@

    // Check status and inspect RESP
    ...

    Clearly, if you have additional Redis key arguments and/or parameters to pass to the script, you'll have to use redisxArrayRequest(), instead.

    +

    One thing to keep in mind about LUA scripts is that they are not persistent. They are lost each time the Redis server is restarted.

    @@ -582,12 +588,8 @@

    Now, we are capturing and processing all messages published to channels whose name begins with "event:", using our custom my_event_processor function.

    To end the subscription, we trace back the same steps by calling redisxUnsubscribe() to stop receiving further messages to the subscription channel or pattern, and by removing the my_event_procesor subscriber function as appropriate (provided no other subscription needs it) via redisxRemoveSubscriber().

    -

    -

    -Implementing further Redis commands

    -

    -

    +

    Error handling

    Error handling of RedisX is an extension of that of xchange, with further error codes defined in redisx.h. The RedisX functions that return an error status (either directly, or into the integer designated by a pointer argument), can be inspected by redisxErrorDescription(), e.g.:

    Redis *redis ...
    @@ -599,13 +601,13 @@

    }

    -

    +

    Debug support

    The xchange library provides two macros: xvprintf() and xdprintf(), for printing verbose and debug messages to stderr. Both work just like printf(), but they are conditional on verbosity being enabled via redisxSetVerbose(boolean) and the global variable xDebug being TRUE (non-zero), respectively. Applications using RedisX may use these macros to produce their own verbose and/or debugging outputs conditional on the same global settings.

    You can also turn debug messages by defining the DEBUG constant for the compiler, e.g. by adding -DDEBUG to CFLAGS prior to calling make.

    -

    +

    Future plans

    Some obvious ways the library could evolve and grow in the not too distant future: