Zum Inhalt

memcached: Lua memcached-Clienttreiber für nginx-module-lua basierend auf der cosocket API

Installation

Wenn Sie noch kein RPM-Repository-Abonnement eingerichtet haben, melden Sie sich an. Danach können Sie mit den folgenden Schritten fortfahren.

CentOS/RHEL 7 oder 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-memcached

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

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

Um diese Lua-Bibliothek mit NGINX zu verwenden, stellen Sie sicher, dass nginx-module-lua installiert ist.

Dieses Dokument beschreibt lua-resty-memcached v0.18, das am 07. Juni 2026 veröffentlicht wurde.

Diese Lua-Bibliothek ist ein memcached-Clienttreiber für das ngx_lua-nginx-Modul:

http://wiki.nginx.org/HttpLuaModule

Diese Lua-Bibliothek nutzt die cosocket-API von ngx_lua, die ein 100% nicht blockierendes Verhalten gewährleistet.

Bitte beachten Sie, dass mindestens ngx_lua 0.5.0rc29 oder OpenResty 1.0.15.7 erforderlich ist.

Synopsis

    server {
        location /test {
            content_by_lua '
                local memcached = require "resty.memcached"
                local memc, err = memcached:new()
                if not memc then
                    ngx.say("failed to instantiate memc: ", err)
                    return
                end

                memc:set_timeout(1000) -- 1 sec

                -- oder verbinden Sie sich mit einer Unix-Domain-Socket-Datei, die von einem
                -- memcached-Server überwacht wird:
                --     local ok, err = memc:connect("unix:/path/to/memc.sock")

                local ok, err = memc:connect("127.0.0.1", 11211)
                if not ok then
                    ngx.say("failed to connect: ", err)
                    return
                end

                local ok, err = memc:flush_all()
                if not ok then
                    ngx.say("failed to flush all: ", err)
                    return
                end

                local ok, err = memc:set("dog", 32)
                if not ok then
                    ngx.say("failed to set dog: ", err)
                    return
                end

                local res, flags, err = memc:get("dog")
                if err then
                    ngx.say("failed to get dog: ", err)
                    return
                end

                if not res then
                    ngx.say("dog not found")
                    return
                end

                ngx.say("dog: ", res)

                -- lege es in den Verbindungspool mit der Größe 100,
                -- mit 10 Sekunden maximaler Leerlaufzeit
                local ok, err = memc:set_keepalive(10000, 100)
                if not ok then
                    ngx.say("cannot set keepalive: ", err)
                    return
                end

                -- oder schließen Sie die Verbindung sofort:
                -- local ok, err = memc:close()
                -- if not ok then
                --     ngx.say("failed to close: ", err)
                --     return
                -- end
            ';
        }
    }

Methoden

Das key-Argument, das in den folgenden Methoden bereitgestellt wird, wird automatisch gemäß den URI-Escaping-Regeln vor dem Senden an den memcached-Server escaped.

new

syntax: memc, err = memcached:new(opts?)

Erstellt ein memcached-Objekt. Im Falle von Fehlern gibt es nil und eine Zeichenfolge zurück, die den Fehler beschreibt.

Es akzeptiert ein optionales opts-Tabellenargument. Die folgenden Optionen werden unterstützt:

  • key_transform

    eine Array-Tabelle, die zwei Funktionen zum Escapen und Unescapen der memcached-Schlüssel enthält. Standardmäßig werden die memcached-Schlüssel als URI-Komponenten escaped und unescaped, das heißt

    memached:new{
        key_transform = { ngx.escape_uri, ngx.unescape_uri }
    }

connect

syntax: ok, err = memc:connect(host, port)

syntax: ok, err = memc:connect("unix:/path/to/unix.sock")

Versucht, sich mit dem Remote-Host und dem Port zu verbinden, auf dem der memcached-Server lauscht, oder mit einer lokalen Unix-Domain-Socket-Datei, die vom memcached-Server überwacht wird.

Bevor der Hostname tatsächlich aufgelöst und eine Verbindung zum Remote-Backend hergestellt wird, sucht diese Methode immer im Verbindungspool nach passenden Leerlaufverbindungen, die durch vorherige Aufrufe dieser Methode erstellt wurden.

sslhandshake

syntax: session, err = memc:sslhandshake(reused_session?, server_name?, ssl_verify?, send_status_req?)

Führt das SSL/TLS-Handshake über die derzeit etablierte Verbindung durch. Siehe die tcpsock.sslhandshake API von OpenResty für weitere Details.

set

syntax: ok, err = memc:set(key, value, exptime, flags)

Fügt einen Eintrag bedingungslos in memcached ein. Wenn der Schlüssel bereits existiert, wird er überschrieben.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (zusammenhangslos) verkettet werden sollen. Zum Beispiel,

    memc:set("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:set("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es niemals abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

set_timeout

syntax: ok, err = memc:set_timeout(timeout)

Setzt den Timeout (in ms) für nachfolgende Operationen, einschließlich der connect-Methode.

Gibt 1 zurück, wenn erfolgreich, und nil plus eine Zeichenfolge, die den Fehler beschreibt, andernfalls.

set_timeouts

syntax: ok, err = memc:set_timeouts(connect_timeout, send_timeout, read_timeout)

Setzt die Timeouts (in ms) für Verbindungs-, Sende- und Leseoperationen.

Gibt 1 zurück, wenn erfolgreich, und nil plus eine Zeichenfolge, die den Fehler beschreibt, andernfalls.

set_keepalive

syntax: ok, err = memc:set_keepalive(max_idle_timeout, pool_size)

Legt die aktuelle memcached-Verbindung sofort in den ngx_lua cosocket-Verbindungspool.

Sie können die maximale Leerlaufzeit (in ms) angeben, wenn die Verbindung im Pool ist, und die maximale Größe des Pools für jeden nginx-Arbeitsprozess.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

Rufen Sie diese Methode nur an der Stelle auf, an der Sie stattdessen die close-Methode aufgerufen hätten. Das Aufrufen dieser Methode versetzt das aktuelle memcached-Objekt sofort in den Zustand closed. Alle nachfolgenden Operationen, die nicht connect() auf dem aktuellen Objekt sind, geben den closed-Fehler zurück.

get_reused_times

syntax: times, err = memc:get_reused_times()

Diese Methode gibt die (erfolgreich) wiederverwendeten Zeiten für die aktuelle Verbindung zurück. Im Fehlerfall gibt es nil und eine Zeichenfolge zurück, die den Fehler beschreibt.

Wenn die aktuelle Verbindung nicht aus dem integrierten Verbindungspool stammt, gibt diese Methode immer 0 zurück, das heißt, die Verbindung wurde (noch) nie wiederverwendet. Wenn die Verbindung aus dem Verbindungspool stammt, ist der Rückgabewert immer ungleich null. Diese Methode kann also auch verwendet werden, um zu bestimmen, ob die aktuelle Verbindung aus dem Pool stammt.

close

syntax: ok, err = memc:close()

Schließt die aktuelle memcached-Verbindung und gibt den Status zurück.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

add

syntax: ok, err = memc:add(key, value, exptime, flags)

Fügt einen Eintrag in memcached ein, wenn und nur wenn der Schlüssel nicht existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (zusammenhangslos) verkettet werden sollen. Zum Beispiel,

    memc:add("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:add("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es niemals abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

replace

syntax: ok, err = memc:replace(key, value, exptime, flags)

Fügt einen Eintrag in memcached ein, wenn und nur wenn der Schlüssel existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (zusammenhangslos) verkettet werden sollen. Zum Beispiel,

    memc:replace("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:replace("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es niemals abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

append

syntax: ok, err = memc:append(key, value, exptime, flags)

Hängt den Wert an einen Eintrag mit dem gleichen Schlüssel an, der bereits in memcached existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (zusammenhangslos) verkettet werden sollen. Zum Beispiel,

    memc:append("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:append("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es niemals abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

prepend

syntax: ok, err = memc:prepend(key, value, exptime, flags)

Fügt den Wert an einen Eintrag mit dem gleichen Schlüssel an, der bereits in memcached existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (zusammenhangslos) verkettet werden sollen. Zum Beispiel,

    memc:prepend("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:prepend("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es niemals abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

get

syntax: value, flags, err = memc:get(key) syntax: results, err = memc:get(keys)

Holt einen einzelnen Eintrag oder mehrere Einträge im memcached-Server über einen einzelnen Schlüssel oder eine Tabelle von Schlüsseln.

Lassen Sie uns zuerst den Fall besprechen, wenn der Schlüssel ein einzelner String ist.

Der Wert des Schlüssels und der zugehörige Flags-Wert werden zurückgegeben, wenn der Eintrag gefunden wird und kein Fehler auftritt.

Im Fehlerfall werden nil-Werte für value und flags zurückgegeben, und ein dritter (String-)Wert wird ebenfalls zurückgegeben, um den Fehler zu beschreiben.

Wenn der Eintrag nicht gefunden wird, werden drei nil-Werte zurückgegeben.

Dann lassen Sie uns den Fall besprechen, wenn eine Lua-Tabelle mit mehreren Schlüsseln bereitgestellt wird.

In diesem Fall wird immer eine Lua-Tabelle mit den Schlüssel-Ergebnis-Paaren im Erfolgsfall zurückgegeben. Jeder Wert, der jedem Schlüssel in der Tabelle entspricht, ist ebenfalls eine Tabelle, die zwei Werte enthält, den Wert des Schlüssels und die Flags des Schlüssels. Wenn ein Schlüssel nicht existiert, gibt es keine entsprechenden Einträge in der results-Tabelle.

Im Fehlerfall wird nil zurückgegeben, und der zweite Rückgabewert ist eine Zeichenfolge, die den Fehler beschreibt.

gets

syntax: value, flags, cas_unique, err = memc:gets(key)

syntax: results, err = memc:gets(keys)

Genau wie die get-Methode, gibt aber auch den CAS-einzigartigen Wert zurück, der mit dem Eintrag verbunden ist, zusätzlich zum Wert und den Flags des Schlüssels.

Diese Methode wird normalerweise zusammen mit der cas-Methode verwendet.

cas

syntax: ok, err = memc:cas(key, value, cas_unique, exptime?, flags?)

Genau wie die set-Methode, führt jedoch eine Überprüfungs- und Setzoperation durch, was bedeutet: "Speichern Sie diese Daten, aber nur, wenn seit meinem letzten Abruf niemand anderes aktualisiert hat."

Das cas_unique-Argument kann von der gets-Methode abgerufen werden.

touch

syntax: ok, err = memc:touch(key, exptime)

Aktualisiert die Ablaufzeit eines vorhandenen Schlüssels.

Gibt 1 bei Erfolg oder nil mit einer Zeichenfolge zurück, die den Fehler beschreibt, andernfalls.

Diese Methode wurde erstmals in der Version v0.11 eingeführt.

flush_all

syntax: ok, err = memc:flush_all(time?)

Flushed (oder invalidiert) alle vorhandenen Einträge im memcached-Server sofort (standardmäßig) oder nach der Ablaufzeit, die durch das time-Argument (in Sekunden) angegeben ist.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

delete

syntax: ok, err = memc:delete(key)

Löscht den Schlüssel sofort aus memcached.

Der zu löschende Schlüssel muss bereits in memcached existieren.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

incr

syntax: new_value, err = memc:incr(key, delta)

Erhöht den Wert des angegebenen Schlüssels um den ganzzahligen Wert, der im delta-Argument angegeben ist.

Gibt den neuen Wert nach der Erhöhung im Erfolgsfall zurück und nil mit einer Zeichenfolge, die den Fehler beschreibt, im Fehlerfall.

decr

syntax: new_value, err = memc:decr(key, value)

Verringert den Wert des angegebenen Schlüssels um den ganzzahligen Wert, der im delta-Argument angegeben ist.

Gibt den neuen Wert nach der Verringerung im Erfolgsfall zurück und nil mit einer Zeichenfolge, die den Fehler beschreibt, im Fehlerfall.

stats

syntax: lines, err = memc:stats(args?)

Gibt Statistikinformationen des memcached-Servers mit einem optionalen args-Argument zurück.

Im Erfolgsfall gibt diese Methode eine Lua-Tabelle zurück, die alle Zeilen der Ausgabe enthält; im Fehlerfall gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

Wenn das args-Argument weggelassen wird, werden allgemeine Serverstatistiken zurückgegeben. Mögliche Werte für das args-Argument sind items, sizes, slabs und andere.

quit

syntax: ok, err = memc:quit()

Teilt dem Server mit, die aktuelle memcached-Verbindung zu schließen.

Gibt 1 im Erfolgsfall und nil andernfalls zurück. Im Fehlerfall wird ein weiterer Stringwert zurückgegeben, um den Fehler zu beschreiben.

Im Allgemeinen können Sie einfach direkt die close-Methode aufrufen, um denselben Effekt zu erzielen.

verbosity

syntax: ok, err = memc:verbosity(level)

Setzt das Verbositätsniveau, das vom memcached-Server verwendet wird. Das level-Argument sollte nur ganze Zahlen enthalten.

Gibt 1 im Erfolgsfall und nil andernfalls zurück. Im Fehlerfall wird ein weiterer Stringwert zurückgegeben, um den Fehler zu beschreiben.

init_pipeline

syntax: err = memc:init_pipeline(n?)

Aktiviert den Memcache-Pipelining-Modus. Alle nachfolgenden Aufrufe der Memcache-Befehlsmethoden werden automatisch gepuffert und beim Aufruf der Methode commit_pipeline in einem Durchgang an den Server gesendet oder durch Aufrufen der Methode cancel_pipeline abgebrochen.

Der optionale Parameter n ist die Größe der Puffertabellen. Standardwert ist 4.

commit_pipeline

syntax: results, err = memc:commit_pipeline()

Beendet den Pipelining-Modus, indem alle zwischengespeicherten Memcache-Abfragen in einem einzigen Durchgang an den Remote-Server übermittelt werden. Alle Antworten auf diese Abfragen werden automatisch gesammelt und werden zurückgegeben, als ob es sich um eine große Multi-Bulk-Antwort auf der höchsten Ebene handelt.

Diese Methode gibt bei Erfolg eine Lua-Tabelle zurück. Bei Misserfolg wird eine Lua-Zeichenfolge zurückgegeben, die den Fehler beschreibt.

cancel_pipeline

syntax: memc:cancel_pipeline()

Beendet den Pipelining-Modus, indem alle vorhandenen gepufferten Memcache-Befehle seit dem letzten Aufruf der Methode init_pipeline verworfen werden.

Die Methode gibt keinen Wert zurück. Erfolgt immer erfolgreich.

Automatische Fehlerprotokollierung

Standardmäßig protokolliert das zugrunde liegende ngx_lua-Modul Fehler, wenn Socket-Fehler auftreten. Wenn Sie bereits eine ordnungsgemäße Fehlerbehandlung in Ihrem eigenen Lua-Code durchführen, wird empfohlen, diese automatische Fehlerprotokollierung zu deaktivieren, indem Sie die lua_socket_log_errors-Direktive von ngx_lua deaktivieren, das heißt,

    lua_socket_log_errors off;

Einschränkungen

  • Diese Bibliothek kann nicht in Codekontexten wie set_by_lua*, log_by_lua* und header_filter_by_lua* verwendet werden, in denen die ngx_lua cosocket-API nicht verfügbar ist.
  • Die resty.memcached-Objektinstanz kann nicht auf Modulebene in einer Lua-Variablen gespeichert werden, da sie dann von allen gleichzeitigen Anfragen, die vom gleichen nginx-Arbeitsprozess bearbeitet werden, geteilt wird (siehe http://wiki.nginx.org/HttpLuaModule#Data_Sharing_within_an_Nginx_Worker) und schlechte Race-Conditions verursachen kann, wenn gleichzeitige Anfragen versuchen, dieselbe resty.memcached-Instanz zu verwenden. Sie sollten immer resty.memcached-Objekte in lokalen Funktionsvariablen oder in der ngx.ctx-Tabelle initiieren. Diese Orte haben alle ihre eigenen Datenkopien für jede Anfrage.

Siehe auch

GitHub

Sie finden zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-memcached.