Skip to content

Commit 126aa68

Browse files
tanbrotanbro
committed
feat(cache): add descriptive comments and improve code readability
- Add detailed comments to explain cache operations and parameters - Improve code structure and add blank lines for better readability - Clarify the purpose of each cache strategy (FIFO, LFU, LRU, RR) - Explain the logic for handling TTL, evictions, and stale entries
1 parent a6ff7c1 commit 126aa68

File tree

11 files changed

+158
-21
lines changed

11 files changed

+158
-21
lines changed

‎src/redis_func_cache/lua/fifo_get.lua‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,19 @@
1+
2+
--[[
3+
FIFO (First-In-First-Out) cache get operation using zset order.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = order)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: TTL for both keys (number, seconds)
7+
ARGV[2]: hash key to retrieve
8+
Returns: value if found, otherwise nil. Cleans up stale entries.
9+
]]
110
local zset_key = KEYS[1]
211
local hmap_key = KEYS[2]
312

413
local ttl = ARGV[1]
514
local hash = ARGV[2]
615

16+
-- Set TTL if specified
717
if tonumber(ttl) > 0 then
818
redis.call('EXPIRE', zset_key, ttl)
919
redis.call('EXPIRE', hmap_key, ttl)
@@ -12,10 +22,11 @@ end
1222
local rnk = redis.call('ZRANK', zset_key, hash)
1323
local val = redis.call('HGET', hmap_key, hash)
1424

25+
-- If found, return value; else clean up stale entries
1526
if rnk and val then
1627
return val
1728
elseif rnk then
18-
redis.call('ZREM', zset_key, hash)
29+
redis.call('ZREM', zset_key, hash) -- remove stale zset member
1930
elseif val then
20-
redis.call('HDEL', hmap_key, hash)
31+
redis.call('HDEL', hmap_key, hash) -- remove stale hash value
2132
end

‎src/redis_func_cache/lua/fifo_put.lua‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
2+
--[[
3+
FIFO (First-In-First-Out) cache put operation using zset order.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = order)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: max cache size (number)
7+
ARGV[2]: TTL for both keys (number, seconds)
8+
ARGV[3]: hash key to store
9+
ARGV[4]: value to store
10+
Returns: number of evicted items
11+
]]
112
local zset_key = KEYS[1]
213
local hmap_key = KEYS[2]
314

@@ -6,23 +17,26 @@ local ttl = ARGV[2]
617
local hash = ARGV[3]
718
local return_value = ARGV[4]
819

20+
-- Set TTL if specified
921
if tonumber(ttl) > 0 then
1022
redis.call('EXPIRE', zset_key, ttl)
1123
redis.call('EXPIRE', hmap_key, ttl)
1224
end
1325

1426
local c = 0
1527

28+
-- If hash not in zset, insert and evict if needed
1629
if not redis.call('ZRANK', zset_key, hash) then
1730
if maxsize > 0 then
1831
local n = redis.call('ZCARD', zset_key) - maxsize
1932
while n >= 0 do
20-
local popped = redis.call('ZPOPMIN', zset_key)
33+
local popped = redis.call('ZPOPMIN', zset_key) -- evict oldest
2134
redis.call('HDEL', hmap_key, popped[1])
2235
n = n - 1
2336
c = c + 1
2437
end
2538
end
39+
-- Find highest score and increment for new entry
2640
local highest_with_score = redis.call('ZRANGE', zset_key, '+inf', '-inf', 'BYSCORE', 'REV', 'LIMIT', 0, 1,
2741
'WITHSCORES')
2842
if rawequal(next(highest_with_score), nil) then

‎src/redis_func_cache/lua/fifo_t_put.lua‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
2+
--[[
3+
FIFO (First-In-First-Out) cache put operation with timestamp.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = timestamp)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: max cache size (number)
7+
ARGV[2]: TTL for both keys (number, seconds)
8+
ARGV[3]: hash key to store
9+
ARGV[4]: value to store
10+
Returns: number of evicted items
11+
]]
112
local zset_key = KEYS[1]
213
local hmap_key = KEYS[2]
314

@@ -6,25 +17,27 @@ local ttl = ARGV[2]
617
local hash = ARGV[3]
718
local return_value = ARGV[4]
819

20+
-- Set TTL if specified
921
if tonumber(ttl) > 0 then
1022
redis.call('EXPIRE', zset_key, ttl)
1123
redis.call('EXPIRE', hmap_key, ttl)
1224
end
1325

1426
local c = 0
1527

28+
-- If hash not in zset, insert and evict if needed
1629
if not redis.call('ZRANK', zset_key, hash) then
1730
if maxsize > 0 then
1831
local n = redis.call('ZCARD', zset_key) - maxsize
1932
while n >= 0 do
20-
local popped = redis.call('ZPOPMIN', zset_key)
33+
local popped = redis.call('ZPOPMIN', zset_key) -- evict oldest
2134
redis.call('HDEL', hmap_key, popped[1])
2235
n = n - 1
2336
c = c + 1
2437
end
2538
end
2639
local time = redis.call('TIME')
27-
redis.call('ZADD', zset_key, time[1] + time[2] / 1e-6, hash)
40+
redis.call('ZADD', zset_key, time[1] + time[2] / 1e-6, hash) -- use current time as score
2841
redis.call('HSET', hmap_key, hash, return_value)
2942
end
3043

‎src/redis_func_cache/lua/lfu_get.lua‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,19 @@
1+
2+
--[[
3+
LFU (Least Frequently Used) cache get operation.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = frequency)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: TTL for both keys (number, seconds)
7+
ARGV[2]: hash key to retrieve
8+
Returns: value if found, otherwise nil. Increments frequency, cleans up stale entries.
9+
]]
110
local zset_key = KEYS[1]
211
local hmap_key = KEYS[2]
312

413
local ttl = ARGV[1]
514
local hash = ARGV[2]
615

16+
-- Set TTL if specified
717
if tonumber(ttl) > 0 then
818
redis.call('EXPIRE', zset_key, ttl)
919
redis.call('EXPIRE', hmap_key, ttl)
@@ -12,11 +22,12 @@ end
1222
local rnk = redis.call('ZRANK', zset_key, hash)
1323
local val = redis.call('HGET', hmap_key, hash)
1424

25+
-- If found, increment frequency; else clean up stale entries
1526
if rnk and val then
1627
redis.call('ZINCRBY', zset_key, 1, hash)
1728
return val
1829
elseif rnk then
19-
redis.call('ZREM', zset_key, hash)
30+
redis.call('ZREM', zset_key, hash) -- remove stale zset member
2031
elseif val then
21-
redis.call('HDEL', hmap_key, hash)
32+
redis.call('HDEL', hmap_key, hash) -- remove stale hash value
2233
end

‎src/redis_func_cache/lua/lfu_put.lua‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
2+
--[[
3+
LFU (Least Frequently Used) cache put operation.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = frequency)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: max cache size (number)
7+
ARGV[2]: TTL for both keys (number, seconds)
8+
ARGV[3]: hash key to store
9+
ARGV[4]: value to store
10+
Returns: number of evicted items
11+
]]
112
local zset_key = KEYS[1]
213
local hmap_key = KEYS[2]
314

@@ -6,23 +17,25 @@ local ttl = ARGV[2]
617
local hash = ARGV[3]
718
local return_value = ARGV[4]
819

20+
-- Set TTL if specified
921
if tonumber(ttl) > 0 then
1022
redis.call('EXPIRE', zset_key, ttl)
1123
redis.call('EXPIRE', hmap_key, ttl)
1224
end
1325

1426
local c = 0
27+
-- If hash not in zset, insert and evict if needed
1528
if not redis.call('ZRANK', zset_key, hash) then
1629
if maxsize > 0 then
1730
local n = redis.call('ZCARD', zset_key) - maxsize
1831
while n >= 0 do
19-
local popped = redis.call('ZPOPMIN', zset_key)
32+
local popped = redis.call('ZPOPMIN', zset_key) -- evict least frequently used
2033
redis.call('HDEL', hmap_key, popped[1])
2134
n = n - 1
2235
c = c + 1
2336
end
2437
end
25-
redis.call('ZINCRBY', zset_key, 1, hash)
38+
redis.call('ZINCRBY', zset_key, 1, hash) -- increment frequency
2639
redis.call('HSET', hmap_key, hash, return_value)
2740
end
2841

‎src/redis_func_cache/lua/lru_get.lua‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,19 @@
1+
2+
--[[
3+
LRU (Least Recently Used) cache get operation using zset order update.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = order)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: TTL for both keys (number, seconds)
7+
ARGV[2]: hash key to retrieve
8+
Returns: value if found, otherwise nil. Updates order, cleans up stale entries.
9+
]]
110
local zset_key = KEYS[1]
211
local hmap_key = KEYS[2]
312

413
local ttl = ARGV[1]
514
local hash = ARGV[2]
615

16+
-- Set TTL if specified
717
if tonumber(ttl) > 0 then
818
redis.call('EXPIRE', zset_key, ttl)
919
redis.call('EXPIRE', hmap_key, ttl)
@@ -12,6 +22,7 @@ end
1222
local rnk = redis.call('ZRANK', zset_key, hash)
1323
local val = redis.call('HGET', hmap_key, hash)
1424

25+
-- If found, update order; else clean up stale entries
1526
if rnk and val then
1627
local highest_with_score = redis.call('ZRANGE', zset_key, '+inf', '-inf', 'BYSCORE', 'REV', 'LIMIT', 0, 1,
1728
'WITHSCORES')
@@ -24,7 +35,7 @@ if rnk and val then
2435
end
2536
return val
2637
elseif rnk then
27-
redis.call('ZREM', zset_key, hash)
38+
redis.call('ZREM', zset_key, hash) -- remove stale zset member
2839
elseif val then
29-
redis.call('HDEL', hmap_key, hash)
40+
redis.call('HDEL', hmap_key, hash) -- remove stale hash value
3041
end

‎src/redis_func_cache/lua/lru_put.lua‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
2+
--[[
3+
LRU (Least Recently Used) cache put operation using zset order.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = order)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: max cache size (number)
7+
ARGV[2]: TTL for both keys (number, seconds)
8+
ARGV[3]: hash key to store
9+
ARGV[4]: value to store
10+
ARGV[6]: (optional) 'mru' for MRU eviction
11+
Returns: number of evicted items
12+
]]
113
local zset_key = KEYS[1]
214
local hmap_key = KEYS[2]
315

@@ -6,6 +18,7 @@ local ttl = ARGV[2]
618
local hash = ARGV[3]
719
local return_value = ARGV[4]
820

21+
-- Set TTL if specified
922
if tonumber(ttl) > 0 then
1023
redis.call('EXPIRE', zset_key, ttl)
1124
redis.call('EXPIRE', hmap_key, ttl)
@@ -18,21 +31,23 @@ end
1831

1932
local c = 0
2033

34+
-- If hash not in zset, insert and evict if needed
2135
if not redis.call('ZRANK', zset_key, hash) then
2236
if maxsize > 0 then
2337
local n = redis.call('ZCARD', zset_key) - maxsize
2438
while n >= 0 do
2539
local popped
2640
if is_mru then
27-
popped = redis.call('ZPOPMAX', zset_key)
41+
popped = redis.call('ZPOPMAX', zset_key) -- MRU eviction
2842
else
29-
popped = redis.call('ZPOPMIN', zset_key)
43+
popped = redis.call('ZPOPMIN', zset_key) -- LRU eviction
3044
end
3145
redis.call('HDEL', hmap_key, popped[1])
3246
n = n - 1
3347
c = c + 1
3448
end
3549
end
50+
-- Find highest score and increment for new entry
3651
local highest_with_score = redis.call('ZRANGE', zset_key, '+inf', '-inf', 'BYSCORE', 'REV', 'LIMIT', 0, 1,
3752
'WITHSCORES')
3853
if rawequal(next(highest_with_score), nil) then

‎src/redis_func_cache/lua/lru_t_get.lua‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,19 @@
1+
2+
--[[
3+
LRU (Least Recently Used) cache get operation with timestamp update.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = timestamp)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: TTL for both keys (number, seconds)
7+
ARGV[2]: hash key to retrieve
8+
Returns: value if found, otherwise nil. Updates access time, cleans up stale entries.
9+
]]
110
local zset_key = KEYS[1]
211
local hmap_key = KEYS[2]
312

413
local ttl = ARGV[1]
514
local hash = ARGV[2]
615

16+
-- Set TTL if specified
717
if tonumber(ttl) > 0 then
818
redis.call('EXPIRE', zset_key, ttl)
919
redis.call('EXPIRE', hmap_key, ttl)
@@ -12,12 +22,13 @@ end
1222
local rnk = redis.call('ZRANK', zset_key, hash)
1323
local val = redis.call('HGET', hmap_key, hash)
1424

25+
-- If found, update timestamp; else clean up stale entries
1526
if rnk and val then
1627
local time = redis.call('TIME')
1728
redis.call('ZADD', zset_key, time[1] + time[2] / 1e-6, hash)
1829
return val
1930
elseif rnk then
20-
redis.call('ZREM', zset_key, hash)
31+
redis.call('ZREM', zset_key, hash) -- remove stale zset member
2132
elseif val then
22-
redis.call('HDEL', hmap_key, hash)
33+
redis.call('HDEL', hmap_key, hash) -- remove stale hash value
2334
end

‎src/redis_func_cache/lua/lru_t_put.lua‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
2+
--[[
3+
LRU (Least Recently Used) cache put operation with timestamp.
4+
KEYS[1]: Redis sorted set key for cache hashes (score = timestamp)
5+
KEYS[2]: Redis hash key for cache values
6+
ARGV[1]: max cache size (number)
7+
ARGV[2]: TTL for both keys (number, seconds)
8+
ARGV[3]: hash key to store
9+
ARGV[4]: value to store
10+
ARGV[5]: (optional) 'mru' for MRU eviction
11+
Returns: number of evicted items
12+
]]
113
local zset_key = KEYS[1]
214
local hmap_key = KEYS[2]
315

@@ -6,6 +18,7 @@ local ttl = ARGV[2]
618
local hash = ARGV[3]
719
local return_value = ARGV[4]
820

21+
-- Set TTL if specified
922
if tonumber(ttl) > 0 then
1023
redis.call('EXPIRE', zset_key, ttl)
1124
redis.call('EXPIRE', hmap_key, ttl)
@@ -17,15 +30,16 @@ if #ARGV > 4 then
1730
end
1831

1932
local c = 0
33+
-- If hash not in zset, insert and evict if needed
2034
if not redis.call('ZRANK', zset_key, hash) then
2135
if maxsize > 0 then
2236
local n = redis.call('ZCARD', zset_key) - maxsize
2337
while n >= 0 do
2438
local popped
2539
if is_mru then
26-
popped = redis.call('ZPOPMAX', zset_key)
40+
popped = redis.call('ZPOPMAX', zset_key) -- MRU eviction
2741
else
28-
popped = redis.call('ZPOPMIN', zset_key)
42+
popped = redis.call('ZPOPMIN', zset_key) -- LRU eviction
2943
end
3044
redis.call('HDEL', hmap_key, popped[1])
3145
n = n - 1
@@ -34,7 +48,7 @@ if not redis.call('ZRANK', zset_key, hash) then
3448
end
3549

3650
local time = redis.call('TIME')
37-
redis.call('ZADD', zset_key, time[1] + time[2] * 1e-6, hash)
51+
redis.call('ZADD', zset_key, time[1] + time[2] * 1e-6, hash) -- use current time as score
3852
redis.call('HSET', hmap_key, hash, return_value)
3953
end
4054

0 commit comments

Comments
 (0)