Replace Multi-Round-Trip Race-Prone Logic with a Small Measured Atomic Function

Learning outcomes

The chapter closes with a decision, not merely another feature demo. AtlasMart will compare a deliberately race-prone read/branch/write workflow with one small Redis Function that performs the conditional state transition atomically. The goal is to measure correctness and round-trip behavior while keeping the server-side code tiny enough to remain operationally safe.

1. The race-prone workflow has a gap between observation and mutation

A naive reservation service reads stock, decides in the application, then decrements stock and writes an order record. Two clients can both read the same last unit before either writes. Pipelining can reduce transport round trips but cannot make a branch that depends on a previous result atomic.

Client A: GET stock -> 1Client B: GET stock -> 1Client A: decides yes; DECR stock -> 0Client B: decides yes; DECR stock -> -1Invariant broken: stock must never be negative.

2. The Function keeps only the critical state transition in Redis

The server-side API receives two declared keys—the stock counter and one order hash—and a positive quantity argument. It reads the current stock, rejects when insufficient, and otherwise performs the two Redis writes before another client can interleave. External payment, inventory replenishment, email, and analytics remain outside Redis.

#!lua name=atlasmart_ch14_reserve_v1redis.register_function{function_name='reserve_order_v1', callback=function(keys,args) local qty=tonumber(args[1]); if not qty or qty <= 0 then return redis.error_reply('ERR qty must be positive'); end; local stock=tonumber(redis.call('GET',keys[1]) or '0'); if stock < qty then return {0,stock}; end; redis.call('DECRBY',keys[1],qty); redis.call('HSET',keys[2],'status','reserved','qty',qty); return {1,stock-qty}; end, description='Atomic AtlasMart stock reservation'}

import redisr = redis.Redis(host="127.0.0.1", port=6379, username="academy-admin", password="AtlasMart-Admin-Lab-Only-2026", decode_responses=True)library = "#!lua name=atlasmart_ch14_reserve_v1\nredis.register_function{function_name='reserve_order_v1', callback=function(keys,args) local qty=tonumber(args[1]); if not qty or qty <= 0 then return redis.error_reply('ERR qty must be positive'); end; local stock=tonumber(redis.call('GET',keys[1]) or '0'); if stock < qty then return {0,stock}; end; redis.call('DECRBY',keys[1],qty); redis.call('HSET',keys[2],'status','reserved','qty',qty); return {1,stock-qty}; end, description='Atomic AtlasMart stock reservation'}"try:    r.function_delete("atlasmart_ch14_reserve_v1")except redis.ResponseError:    passprint(r.function_load(library))

3. A deterministic single-call proof comes before the stress test

Start with stock 2 and request one unit. The Function should return success + remaining stock, decrement exactly once, and create the reservation hash. Then request more than remaining stock; the Function should reject without changing either key for that second order.

UNLINK atlasmart:ch14:l5:stock atlasmart:ch14:l5:order:1 atlasmart:ch14:l5:order:2SET atlasmart:ch14:l5:stock 2FCALL reserve_order_v1 2 atlasmart:ch14:l5:stock atlasmart:ch14:l5:order:1 1FCALL reserve_order_v1 2 atlasmart:ch14:l5:stock atlasmart:ch14:l5:order:2 2GET atlasmart:ch14:l5:stockHGETALL atlasmart:ch14:l5:order:1EXISTS atlasmart:ch14:l5:order:2# Expected: first succeeds, second rejects, remaining stock=1, order:2 absent.

4. Stress harness: compare naive and Function workflows

The following free/local redis-py harness runs bounded concurrent workers against a synthetic stock counter. It reports operation counts and p50/p95/p99 client-observed latency. Run each mode on a freshly reset prefix. The naive workflow intentionally inserts a tiny application-side scheduling yield between GET and DECR to make the race observable; it is not production code.

import concurrent.futures, statistics, time, redisHOST, PORT = "127.0.0.1", 6379USER, PASSWORD = "academy-admin", "AtlasMart-Admin-Lab-Only-2026"PREFIX = "atlasmart:ch14:l5"INITIAL_STOCK, CLIENTS = 40, 80def client():    return redis.Redis(host=HOST, port=PORT, username=USER, password=PASSWORD, decode_responses=True)def pct(xs, p):    ys = sorted(xs); return ys[min(len(ys)-1, max(0, round((len(ys)-1)*p)))]def run(mode):    r = client(); stock = f"{PREFIX}:{mode}:stock"    keys = [stock] + [f"{PREFIX}:{mode}:order:{i}" for i in range(CLIENTS)]    if keys: r.unlink(*keys)    r.set(stock, INITIAL_STOCK)    def one(i):        c = client(); order = f"{PREFIX}:{mode}:order:{i}"; t0=time.perf_counter_ns()        if mode == "naive":            seen = int(c.get(stock) or 0)            if seen > 0:                time.sleep(0.001)                remaining = c.decr(stock)                c.hset(order, mapping={"status":"reserved"})                ok = 1            else:                remaining, ok = seen, 0        else:            reply = c.fcall("reserve_order_v1", 2, stock, order, 1)            ok, remaining = int(reply[0]), int(reply[1])        return ok, remaining, (time.perf_counter_ns()-t0)/1_000_000    with concurrent.futures.ThreadPoolExecutor(max_workers=16) as ex:        rows = list(ex.map(one, range(CLIENTS)))    final_stock = int(r.get(stock) or 0)    successes = sum(x[0] for x in rows)    lat = [x[2] for x in rows]    print(mode, {"successes":successes,"final_stock":final_stock,"invariant_ok":final_stock>=0 and final_stock+successes==INITIAL_STOCK,"p50_ms":round(pct(lat,.50),3),"p95_ms":round(pct(lat,.95),3),"p99_ms":round(pct(lat,.99),3)})run("naive")run("function")

5. What the latency numbers do—and do not—mean

The Function reduces a conditional workflow to one client request and executes the critical commands server-side. That can remove network round trips, especially when the application is not colocated with Redis. It does not imply that Lua is inherently faster than all native commands, nor that large Functions are safe. Compare client p50/p95/p99, server Slow Log/latency evidence, payload sizes, and concurrency under the same persistence/network conditions.

6. Compare the simplest correct primitives

Do not default every conditional workflow to Functions. Chapter 13 already established that single native commands are preferred when they express the invariant, and WATCH is useful when application-side computation is necessary. Functions fit when a small stable multi-command state transition benefits from one server-side atomic API.

7. Cluster, ACL, persistence, and failover remain separate axes

The function call is atomic on the target Redis node, but production correctness still depends on topology. In Cluster, all declared keys for the call should share a slot; with ACLs, the caller needs scripting plus underlying command/key permissions; with AOF/RDB, durability follows configured persistence; with asynchronous replication/Sentinel failover, successful responses do not create zero-loss guarantees. Those concerns are measured in later chapters rather than being smuggled into the word “atomic.”

CLUSTER KEYSLOT atlasmart:ch14:{sku:42}:stockCLUSTER KEYSLOT atlasmart:ch14:{sku:42}:order:1001# Same {sku:42} hash tag is the intended Cluster design. Current mandatory lab remains standalone.

8. Failure injection: invalid quantity must fail before mutation

The Function validates quantity before reading/writing stock. Exercise zero and nonnumeric quantities and prove neither stock nor an order hash changes. This is a bounded semantic failure, not destructive chaos.

SET atlasmart:ch14:l5:validate:stock 5FCALL reserve_order_v1 2 atlasmart:ch14:l5:validate:stock atlasmart:ch14:l5:validate:order0 0FCALL reserve_order_v1 2 atlasmart:ch14:l5:validate:stock atlasmart:ch14:l5:validate:orderX nopeGET atlasmart:ch14:l5:validate:stockEXISTS atlasmart:ch14:l5:validate:order0 atlasmart:ch14:l5:validate:orderX# Expected: errors, stock remains 5, both order keys absent.

9. Verification checklist and cleanup

• The deterministic test accepted one valid reservation and rejected an oversized one without partial writes.
• The concurrency harness recorded actual success/reject counts and p50/p95/p99 values for both modes.
• The naive mode is labeled intentionally wrong and not reused as a recommendation.
• The Function mode's invariant check uses exact Redis state, not a claim based on “atomic” terminology.
• Cluster/failover/durability claims are explicitly scoped to what the standalone lab can and cannot prove.

UNLINK atlasmart:ch14:l5:stock atlasmart:ch14:l5:order:1 atlasmart:ch14:l5:order:2 atlasmart:ch14:l5:validate:stock atlasmart:ch14:l5:validate:order0 atlasmart:ch14:l5:validate:orderXFUNCTION DELETE atlasmart_ch14_reserve_v1# The stress harness already unlinks only its explicit naive/function fixture keys before each run.

10. Production judgment

Adopt the Function only if the measured workflow benefits from one atomic server-side state transition and the code stays bounded, versioned, observable, and least-privileged. Monitor server p95/p99, Slow Log, function errors, key hotness, replication lag, and deployment version. Keep rollback source/dumps available. Avoid expanding the Function into pricing, payment, messaging, or long-running orchestration; Redis programmability is strongest as a narrow data-local primitive.

11. Chapter summary and bridge

Chapter 14 turned server-side programmability into an explicit engineering tradeoff: Eval scripts are volatile application-owned code, Functions are persisted deployed libraries, both can provide atomic data-local logic, and both can block Redis when abused. You measured cache/lifecycle/error/ACL/concurrency behavior and kept external work outside Lua. Chapter 15 moves to pipelining, batching, client connections, retries, and client-side caching—optimizations that change transport and freshness without pretending to add atomicity.

Authoritative references

• Redis Open Source 8.10 release notes
• Redis programmability
• Scripting with Lua
• Redis Lua API reference
• Redis Functions introduction
• EVAL
• EVAL_RO
• EVALSHA
• EVALSHA_RO
• SCRIPT EXISTS
• SCRIPT LOAD
• SCRIPT FLUSH
• SCRIPT KILL
• FCALL
• FCALL_RO
• FUNCTION LOAD
• FUNCTION LIST
• FUNCTION STATS
• FUNCTION DUMP
• FUNCTION RESTORE
• FUNCTION DELETE
• Redis ACLs
• ACL DRYRUN
• Redis Cluster specification
• Scale with Redis Cluster
• Redis latency diagnosis
• SLOWLOG
• Redis persistence
• Redis replication
• redis-py documentation
• redis-py 8.1.0 on PyPI
• Redis licenses