tlc: Общий двухуровневый кэш (lrucache + shared dict)

Установка

Если вы еще не настроили подписку на 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

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-tlc v0.2, выпущенную 3 октября 2016 года.

---

Реализация двухуровневого кэша с использованием lua-resty-lrucache и shared dictionaries.

Записи кэша записываются в 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

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

Создает новый экземпляр resty.tlc.cache с заданным именем/id и параметрами.

Не будет проверять, существует ли экземпляр уже, существующие экземпляры будут перезаписаны.

get

syntax: cache = manager.get(name)

Возвращает указанный экземпляр TLC кэша или nil.

delete

syntax: manager.delete(name)

Удаляет указанный экземпляр кэша.

list

syntax: instances = manager.list()

Возвращает массив таблиц доступных экземпляров кэша.

cache

new

syntax: instance = cache:new(opts)

Создает новый экземпляр resty.tlc.cache, opts — это таблица параметров для этого экземпляра.

opts = {
    dict         = dict,         -- Имя общего словаря, обязательно
    size         = size,         -- параметр max_items для LRU кэша, необязательно, по умолчанию 200
    pureffi      = pureffi,      -- Использовать вариант LRU кэша pureffi, необязательно, по умолчанию false
    loadfactor   = loadfactor,   -- Коэффициент загрузки для LRU кэша pureffi, необязательно
    serialiser   = serialiser,   -- Функция для сериализации значений при сохранении в общий словарь, необязательно, по умолчанию pcall'd cjson encode
    unserialiser = unserialiser, -- Функция для десериализации значений при сохранении в общий словарь, необязательно, по умолчанию pcall'd cjson decode
}

Функции для сериализации и десериализации должны return nil, err в случае неудачи.

set

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

Устанавливает или обновляет запись в кэше.

ttl является необязательным и указывается в секундах.

get

syntax: data = cache:get(key)

Возвращает данные из кэша или nil, если не установлено.

delete

syntax: cache:delete(key)

Удаляет запись как из LRU кэша, так и из общего словаря.

TODO: Удалить из LRU кэша во всех рабочих процессах.

flush

syntax: cache:flush(hard?)

Переинициализирует LRU кэш в текущем рабочем процессе и очищает общий словарь.

Аргумент hard также вызовет flush_expired() на словаре.

TODO: Переинициализировать LRU кэш во всех рабочих процессах.

GitHub

Вы можете найти дополнительные советы по настройке и документацию для этого модуля в репозитории GitHub для nginx-module-tlc.