tlc: 通用二级缓存 (lrucache + 共享字典)

安装

如果您尚未设置 RPM 仓库订阅，请 注册。然后您可以继续以下步骤。

CentOS/RHEL 7 或 Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-tlc

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-tlc

要在 NGINX 中使用此 Lua 库，请确保已安装 nginx-module-lua。

本文档描述了 lua-resty-tlc v0.2，于 2016 年 10 月 03 日发布。

---

使用 lua-resty-lrucache 和 共享字典 实现的二级缓存。

缓存条目写入当前工作进程的 lru-cache 和共享字典。

在工作进程的 lru-cache 实例中未命中的缓存读取将从共享字典重新填充（如果可用）。

共享字典中的值会自动序列化和反序列化为 JSON（支持自定义序列化函数）。

还提供了一个管理模块来维护全局的 TLC 缓存实例集。

概述

lua_shared_dict tlc_cache 10m;
lua_shared_dict tlc_cache2 1m;

init_by_lua_block {
    local manager = require("resty.tlc.manager")
    manager.new("my_cache", {size = 500, dict = "tlc_cache"})

    manager.new("my_cache2", {size = 500, dict = "tlc_cache2"})
}


location = /get {
    content_by_lua_block {
        local manager = require("resty.tlc.manager")
        local cache = manager.get("my_cache")

        local args = ngx.req.get_uri_args()
        local key = args["key"]

        local data, err = cache:get(key)
        if err then
            ngx.log(ngx.ERR, err)
        elseif data == nil then
            ngx.status = ngx.HTTP_NOT_FOUND
            ngx.say("未找到")
        else
            ngx.say(tostring(data))
        end
    }
}

location = /set {
    content_by_lua_block {
        local manager = require("resty.tlc.manager")
        local cache = manager.get("my_cache")

        local args = ngx.req.get_uri_args()
        local key = args["key"]
        local val = args["val"] or { foo = bar }
        local ttl = args["ttl"]

        local ok, err = cache:set(key, val, ttl)
        if not ok then
            ngx.log(ngx.ERR, err)
        end
    }
}

location = /flush {
    content_by_lua_block {
        local manager = require("resty.tlc.manager")
        local cache = manager.get("my_cache")
        cache:flush()
    }
}

location = /list {
    content_by_lua_block {
        local manager = require("resty.tlc.manager")
        local instances = manager.list()

        ngx.say(require("cjson").encode(instances))
    }
}

方法

• manager
• new
• get
• set
• delete
• list
• cache
• new
• set
• get
• delete
• flush

manager

new

语法: ok, err = manager.new(name, opts)

使用给定的名称/ID 和选项创建一个新的 resty.tlc.cache 实例。

不会检查实例是否已存在，现有实例将被覆盖。

get

语法: cache = manager.get(name)

返回指定的 TLC 缓存实例或 nil。

delete

语法: manager.delete(name)

删除指定的缓存实例。

list

语法: instances = manager.list()

返回可用缓存实例的数组表。

cache

new

语法: instance = cache:new(opts)

创建一个新的 resty.tlc.cache 实例，opts 是该实例的选项表。

opts = {
    dict         = dict,         -- 共享字典名称，必需
    size         = size,         -- LRU 缓存的 max_items 参数，可选，默认 200
    pureffi      = pureffi,      -- 使用纯 ffi LRU 缓存变体，可选，默认 false
    loadfactor   = loadfactor,   -- 纯 ffi LRU 缓存的负载因子， 可选
    serialiser   = serialiser,   -- 保存到共享字典时序列化值的函数， 可选，默认使用 pcall 的 cjson encode
    unserialiser = unserialiser, -- 保存到共享字典时反序列化值的函数， 可选，默认使用 pcall 的 cjson decode
}

序列化和反序列化的函数在失败时应 返回 nil, err。

set

语法: ok, err = cache:set(key, value, ttl?)

在缓存中设置或更新条目。

ttl 是可选的，单位为秒。

get

语法: data = cache:get(key)

从缓存中返回数据，如果未设置则返回 nil。

delete

语法: cache:delete(key)

从 LRU 缓存和共享字典中删除条目。

TODO: 在所有工作进程中从 LRU 缓存中删除。

flush

语法: cache:flush(hard?)

重新初始化当前工作进程中的 LRU 缓存并刷新共享字典。

hard 参数还将调用字典上的 flush_expired()。

TODO: 在所有工作进程中重新初始化 LRU 缓存。

GitHub

您可以在 nginx-module-tlc 的 GitHub 仓库 中找到此模块的其他配置提示和文档。