Why Redis Can Have Thread‑Safety Issues and How Lua Scripts Solve Them

Redis Command Issues

“Thread safety” problem

Although Redis is single‑threaded, thread‑safety issues can arise when multiple clients act like concurrent threads accessing shared memory without proper synchronization.

Typical scenario:

Redis stores a user status, e.g., user5277=idle;

Client A reads the status: status = get("user5277");

Client B reads the same status;

Client A sets the status to busy and assigns a task;

Client B also sets the status to busy and assigns another task;

Result: the user receives two tasks simultaneously.

The root cause is that Redis guarantees command serialization only within the server, but rapid execution of commands from different clients without proper request synchronization can lead to out‑of‑order execution.

Locking the user status can solve the problem, but introduces lock‑granularity, dead‑lock, and maintenance complexities.

Efficiency problem

Redis can achieve up to 100 k write QPS and 600 k read QPS, but network latency becomes the bottleneck. A single memory access costs about 100ns, while a round‑trip between data centers can take 500 000ns.

In distributed deployments, the main inefficiency comes from multiple network round‑trips, especially when a client reads a value, uses it to construct another key, and reads again.

Because ordinary Redis commands lack server‑side computation, developers often resort to pulling data to the client for processing, which adds latency.

Embedded Lua Execution

Redis includes a Lua interpreter, allowing multiple commands to be combined into a single script that runs atomically on the server.

Lua

Lua is a lightweight, fast, embeddable scripting language written in ANSI C.

Lightweight: small core library.

Efficient: fast startup and execution.

Embeddable: can be integrated into various systems (e.g., OpenResty embeds Lua in Nginx).

Execution steps

Since Redis 2.6, a Lua environment is created at startup, loading Lua libraries and defining global tables such as redis.pcall.

A typical Lua script execution flow:

Check if the script has been executed before; if not, generate a Lua function from its SHA1.

Bind timeout and error‑handling hooks to the function.

Create a pseudo‑client to run Redis commands inside the script.

Process the pseudo‑client's return values and send the final result back to the real client.

The pseudo‑client is treated like a normal client, so its commands are replicated via RDB/AOF and propagated to slaves.

Usage

Lua scripts are invoked with the EVAL and EVALSHA commands. EVAL executes a script directly, caching its SHA1 for future calls. EVALSHA requires the script to be loaded first with SCRIPT LOAD, which returns the SHA1.

Example:

127.0.0.1:6379> EVAL "return 'hello'" 0 0
"hello"

127.0.0.1:6379> SCRIPT LOAD "return redis.pcall('GET', ARGV[1])"
"20b602dcc1bb4ba8fca6b74ab364c05c58161a0a"

127.0.0.1:6379> EVALSHA 20b602dcc1bb4ba8fca6b74ab364c05c58161a0a 0 test
"zbs"

Inside a Lua script, KEYS[N] and ARGV[N] are used to access keys and arguments, starting from index 1. When a Redis command returns no value, the script receives false, not nil.

Lua Script Examples

Example 1 – Get a value from a hash and then retrieve another key:

// Use: EVAL script 2 A B
local tmpKey = redis.call('HGET', KEYS[1], KEYS[2]);
return redis.call('GET', tmpKey);

Example 2 – Pop multiple values from a list until a limit is reached or the list is empty:

// Use: EVAL script 2 list count
local list = {};
local item = false;
local num = tonumber(KEYS[2]);
while (num > 0) do
    item = redis.call('LPOP', KEYS[1]);
    if item == false then break; end;
    table.insert(list, item);
    num = num - 1;
end;
return list;

Example 3 – Retrieve the top‑N elements of a sorted set and fetch their detailed hash information:

local elements = redis.call('ZRANK', KEYS[1], 0, KEY[2]);
local detail = {};
for index, ele in elements do
    local info = redis.call('HGETALL', ele);
    table.insert(detail, info);
end;
return detail;

Some Reflections

Use cases

Achieve atomic operations to avoid data conflicts between concurrent clients.

Combine multiple dependent requests into a single round‑trip.

Important notes

Never use global variables in Lua scripts; always declare with local to avoid polluting the environment.

Be aware of the script's time complexity, as it blocks the single Redis thread.

If a Lua script fails, previously executed commands cannot be rolled back.

When multiple independent requests are needed, the pipeline feature is simpler than Lua scripting.