SharedTable
*Dieser Inhalt wurde mit KI (Beta) übersetzt und kann Fehler enthalten. Um diese Seite auf Englisch zu sehen, klicke hier.
Repräsentiert eine tabellartige Datenstruktur, die über Ausführungskontexte hinweg geteilt werden kann.Während es für verschiedene Arten der allgemeinen Datenaufbewahrung verwendet werden kann, ist es speziell für den Einsatz mit Parallel Luau entwickelt, wo es verwendet werden kann, um den Zustand über Skripte zu teilen, die unter verschiedenen Actor untergebracht sind.
Es gibt ein paar idiomatische Wege, um gemeinsame Tabellen zwischen Skripten zu kommunizieren.Eine Methode besteht darin, SharedTable Objekte im SharedTableRegistry zu speichern und abzurufen.Die Registrierung lässt jedes Skript im selben Datenmodell einen SharedTable per Namen erhalten oder festlegen.Eine andere Methode besteht darin, Actor:SendMessage() zu verwenden, um eine gemeinsame Tabelle an einen anderen Actor innerhalb einer Nachricht zu senden.
Wie ein Luau-Table, speichert ein SharedTable -Objekt eine Reihe von Schlüssel-Wert-Elementpaaren.Im Gegensatz zu einem Luau-Tabellen können nur ausgewählte Arten von Objekten in einer gemeinsamen Tabelle gespeichert werden, ähnlich wie andere Einschränkungen, die du anderswo in der Roblox-Engine findest.
Schlüssel müssen entweder (1) ein String oder (2) eine nicht negative Ganzzahl sein, die weniger als 2 32 ist. Andere Arten von Schlüsseln werden nicht unterstützt.
Werte müssen einen der folgenden Arten haben: Boolean, Number, Vector, String, SharedTable oder einen seriellen Daten eingeben.Die Fähigkeit, eine SharedTable als Wert in einer anderen SharedTable zu speichern, ermöglicht die Konstruktion von verschachtelten und rekursiven Datenstrukturen.
SharedTable objekte sind unterschiedlich und unterscheiden sich nie von SharedTable objekten, auch wenn sie inhalte haben, die sich gleich vergleichen würden.
Wie ein Luau-Table, kann ein SharedTable Objekt eingefroren werden, in dem es lesbar ist.Ein Versuch, eine gefrorene SharedTable zu modifizieren, wird einen Fehler verursachen.Ein gefrorenes SharedTable kann erstellt werden, indem zuerst ein (nicht gefrorenes, modifizierbares) SharedTable mit dem gewünschten Inhalt erstellt wird, und dann SharedTable.cloneAndFreeze() angerufen wird, um einen gefrorenen Klon davon zu erstellen.
Code-Beispiele
Elements in a SharedTable are accessed in the same way as elements of Luau tables, using the st[k] syntax or, for string keys, st.k.
local st = SharedTable.new()
st[1] = "a"
st["x"] = true
st.y = 5
assert(st[1] == "a")
assert(st["x"] == true)
assert(st.x == true)
assert(st["y"] == 5)
assert(st.y == 5)
-- true is not a valid SharedTable key, so attempting to set that key
-- fails:
assert(not pcall(function() st[true] = 100 end))
-- A function is not a valid SharedTable value, so attempting to set a
-- value to a function fails:
assert(not pcall(function() st["f"] = function() end end))
Die for -Schleife kann verwendet werden, um die Elemente eines SharedTable zu durchlaufen.Die Elemente der SharedTable werden nicht direkt iteriert.Stattdessen wird ein flacher Klon aus der SharedTable erstellt, und seine Elemente werden wiederholt. Dies wird getan, um sicherzustellen, dass während der Iteration eine konsistente Ansicht der SharedTable aufrechterhalten wird.Daher haben beide der folgenden für Schleifen das gleiche Verhalten.
Beachten Sie, dass dies bedeutet, dass, wenn der SharedTable direkt vom Körper der Iterationsschleife aus aufgerufen wird, sein Zustand möglicherweise nicht mit dem Zustand übereinstimmt, der durch die Iteration beobachtet wird.
Die Iterations顺序 wird teilweise angegeben.Elemente mit numerischen Schlüsseln werden vor Elementen mit Zeichenschlüsseln iteriert.Elemente mit numerischen Schlüsseln werden in aufsteigender numerischer Reihenfolge iteriert.Elemente mit Sternenschlüsseln werden in einer unbestimmten Reihenfolge iteriert.
local st = SharedTable.new({"a", "b", "c"})
for k, v in SharedTable.clone(st, false) do
print(k, ": ", v)
end
for k, v in st do
print(k, ": ", v)
end
Zusammenfassung
Konstrukteure
- new()
Gibt eine neue, leere SharedTable zurück.
Gibt eine neue SharedTable zurück, die Elemente enthält, die den in der bereitgestellten Luau-Tabelle entsprechen.
Funktionen
Entfernt alle Elemente aus der SharedTable.
Erstellt und gibt einen Klon des bereitgestellten SharedTable zurück.
Erstellt und gibt einen gefrorenen (nur lesenden) Klon des bereitgestellten SharedTable zurück.
Fügt delta dem Wert mit dem angegebenen Schlüssel hinzu und gibt den ursprünglichen Wert zurück.
Gibt true zurück, wenn das SharedTable eingefroren ist (nur lesend).
Gibt die Anzahl der Elemente zurück, die in der SharedTable gespeichert sind.
Aktualisiert den Wert mit dem bereitgestellten Schlüssel über die bereitgestellte Aktualisierungsfunktion.
Konstrukteure
new
Gibt eine neue SharedTable zurück, die Elemente enthält, die den in der bereitgestellten Luau-Tabelle entsprechen.
Wenn der bereitgestellte Luau-Tabelle irgendwelche Schlüssel oder Werte enthält, die nicht in einem SharedTable gespeichert werden können, scheitert die Konstruktion des SharedTable .Siehe die Zusammenfassung oben auf dieser Seite für eine Liste von Arten von Objekten, die in einem SharedTable gespeichert werden können.Wenn der Luau-Tab eine Tabelle als Wert enthält, wird diese Tabelle in eine neue SharedTable umgewandelt.
local t = {}t.x = 1t.y = 2t.z = {"a", "b", "c"}local st = SharedTable.new(t)assert(st.x == 1)assert(st.y == 2)assert(st.z[1] == "a")assert(st.z[2] == "b")assert(st.z[3] == "c")
Beachten Sie, dass in einigen Fällen es wünschenswert sein kann, eine SharedTable in der SharedTableRegistry zu speichern.Die Class.ShareTableRegistry:GetSharedTable() -Methode bietet einen bequemen Weg, dies zu erreichen.
Parameter
Der Luau-Tabelle, deren Elemente in der neuen SharedTable gespeichert werden sollen.
Funktionen
clear
Atomar entfernt alle Elemente aus einem SharedTable.
Wenn das SharedTable eingefroren ist, scheitert die Operation und ein Fehler wird erhoben.
local st = SharedTable.new({"a", "b", "c"})assert(SharedTable.size(st) == 3)SharedTable.clear(st)assert(SharedTable.size(st) == 0)
Parameter
Die SharedTable zum löschen.
Rückgaben
clone
Erstellt einen Klon von einem SharedTable und gibt den Klon zurück.
Wenn das optionale deep-Argument nicht vorhanden ist oder es vorhanden ist und sein Wert false ist, wird ein flacher Klon erstellt.Ein oberflächlicher Klon kopiert nur das oberste SharedTable Objekt.Wenn ein Wert in der SharedTable selbst ein SharedTable ist, dann beziehen sich sowohl das ursprüngliche SharedTable als auch der Klon SharedTable auf dasselbe SharedTable.
Die oberflächliche Klonoperation ist atomar, so dass der Klon SharedTable einen konsistenten Schnappschuss des Zustands im ursprünglichen SharedTable enthält, auch wenn er gleichzeitig von anderen Skripten modifiziert wird.
Wenn das optionale deep-Argument vorhanden ist und sein Wert true ist, wird ein tiefer Klon erstellt.Ein tiefer Klon kopiert recursiv eine Struktur von SharedTable Objekten, so dass es keinen Zustand gibt, der zwischen dem ursprünglichen SharedTable und dem Klon geteilt wird.
Der Klon jedes SharedTable innerhalb des Graphs von SharedTable Objekten ist atomar, aber der tiefe Klon insgesamt ist nicht atomar.Daher wird der Klon jedes SharedTable innerhalb des Graphs einen konsistenten Schnappschuss des Zustands des ursprünglichen SharedTable Objekts enthalten, aus dem es kopiert wurde, aber die Zustände verschiedener SharedTable Objekte können unkonsistent sein, wenn der Graph gleichzeitig von anderen Skripten modifiziert wird.
Die SharedTable Objekte, die geklont werden, können eingefroren (nur lesend) oder nicht sein.Unabhängig davon sind die neu erstellten Klone nicht eingefroren (und damit modifizierbar).Um gefrorene Klone zu erstellen, verwende die SharedTable.cloneAndFreeze Funktion.
Um den Unterschied zwischen einem oberflächlichen Klon und einem tiefen Klon zu veranschaulichen, betrachte die folgenden Beispiele.Diese erste Probe erstellt einen flachen Klon und die zweite erstellt einen tiefen Klon.
Parameter
Das SharedTable Objekt zum Klonen.
Ob ein tiefer Klon ( true ) oder ein flacher Klon ( false ) erstellt werden soll.
Rückgaben
Code-Beispiele
Dieses Codebeispiel erstellt einen flachen Klon eines SharedTable.
local original = SharedTable.new()
original["a"] = "original a"
original["b"] = "original b"
original["c"] = SharedTable.new()
original["c"]["d"] = "original d"
local clone = SharedTable.clone(original, false)
clone["a"] = "new a"
clone["b"] = "new b"
clone["c"]["d"] = "new d"
assert(original["a"] == "original a")
assert(original["b"] == "original b")
-- Da dies ein oberflächlicher Klon war, sind original ["c"] und clone ["c"]
-- das gleiche SharedTable-Objekt.
assert(original["c"] == clone["c"])
assert(original["c"]["d"] == "new d")
This code sample creates a deep clone of a SharedTable.
local original = SharedTable.new()
original["a"] = "original a"
original["b"] = "original b"
original["c"] = SharedTable.new()
original["c"]["d"] = "original d"
local clone = SharedTable.clone(original, true)
clone["a"] = "new a"
clone["b"] = "new b"
clone["c"]["d"] = "new d"
assert(original["a"] == "original a")
assert(original["b"] == "original b")
-- Because this was a deep clone, clone["c"] is a clone of original["c"];
-- they are distinct SharedTable objects.
assert(original["c"] ~= clone["c"])
assert(original["c"]["d"] == "original d")
cloneAndFreeze
Erstellt einen gefrorenen (nur lesenden) Klon von einem SharedTable und gibt den Klon zurück.Das Verhalten dieser Funktion ist das gleiche wie das Verhalten von Klon, außer dass der Klon eingefroren ist.
Wenn ein tiefer Klon angefordert wird, werden alle geklonten SharedTable-Objekte eingefroren.
Parameter
Das SharedTable-Objekt zum Klonen.
Ob ein tiefer Klon ( true ) oder ein flacher Klon ( false ) erstellt werden soll.
Rückgaben
increment
Erhöht atomar den Wert eines Elements.Ein Element mit dem angegebenen Schlüssel muss in der SharedTable existieren und vom Typ number sein.Der angegebene delta wird dem Wert hinzugefügt, und der ursprüngliche Wert wird zurückgegeben.
Die SharedTable.update-Funktion kann auch zu diesem Zweck verwendet werden; diese increment-Funktion existiert aus Gründen der Benutzerfreundlichkeit und Leistung (im Allgemeinen ist increment viel schneller als update, daher sollte sie, wo immer möglich, bevorzugt werden).Die folgenden zwei Funktionsaufrufe haben den gleichen Effekt:
local st = SharedTable.new()
st["x"] = 1
local oldValue = SharedTable.increment(st, "x", 1)
SharedTable.update(st, "x", function(v)
oldValue = v
return v + 1
end)
Wenn das SharedTable eingefroren ist, scheitert die Operation und ein Fehler wird erhoben.
Parameter
Das SharedTable Objekt, das aktualisiert werden soll.
Der Schlüssel des Elements im SharedTable Objekt, das aktualisiert werden soll.
Der Wert, der zum Element in der SharedTable hinzugefügt werden soll.
Rückgaben
Der ursprüngliche Wert des Elements, bevor delta hinzugefügt wurde.
Code-Beispiele
This code sample demonstrates usage of SharedTable.increment().
local st = SharedTable.new()
st["x"] = 1
local oldValue = SharedTable.increment(st, "x", 1)
assert(oldValue == 1)
assert(st["x"] == 2)
-- The value of the specified key must be a number. If it is not a
-- number, the call will fail:
st["y"] = "test"
assert(not pcall(function() SharedTable.increment(st, "y", 1) end))
isFrozen
Gibt true zurück, wenn das SharedTable eingefroren ist (nur lesend).
local st1 = SharedTable.new({"a", "b", "c"})assert(not SharedTable.isFrozen(st1))local st2 = SharedTable.cloneAndFreeze(st1)assert(SharedTable.isFrozen(st2))
Parameter
Das SharedTable Objekt, dessen gefrorener Zustand abgefragt werden soll.
Rückgaben
size
Gibt die Anzahl der Elemente zurück, die in der gemeinsamen Tabelle gespeichert sind.Beachten Sie, dass, wenn andere Skripte gleichzeitig die gemeinsame Tabelle modifizieren, die zurückgegebene Größe möglicherweise nicht mehr korrekt ist, nachdem sie zurückgegeben wurde, da andere Skripte möglicherweise Elemente der gemeinsamen Tabelle hinzugefügt oder entfernt haben.
local st = SharedTable.new({"a", "b", "c"})assert(SharedTable.size(st) == 3)st[2] = nilassert(SharedTable.size(st) == 2)
Parameter
Das SharedTable Objekt, dessen Größe abgefragt werden soll.
Rückgaben
update
Aktualisiert atomar den Wert eines Elements.
Wenn ein SharedTable gleichzeitig von Skripten aufgerufen wird, die in verschiedenen Ausführungskontexten laufen, ist es möglich, dass ihre Zugriffe unberechenbar vermischt werden.Daher ist Code wie der folgende in der Regel falsch, weil der Wert zwischen der Lektüre auf der ersten Zeile und der Aktualisierung auf der zweiten Zeile geändert worden sein kann:
local oldValue = st["x"]st["x"] = oldValue .. ",x"
Die Update-Funktion ermöglicht es, ein atomares Update an einem Element durchzuführen.Es nimmt eine Funktion, die es mit dem aktuellen Wert des Elements aufrufen wird.Die Funktion kann dann den neuen Wert berechnen und zurückgeben.Beachten Sie, dass die Funktion möglicherweise mehrmals aufgerufen werden kann, wenn die SharedTable gleichzeitig von anderen Skripten modifiziert wird.
Wenn das SharedTable eingefroren ist, scheitert die Operation und ein Fehler wird erhoben.
Parameter
Das SharedTable Objekt, das aktualisiert werden soll.
Der Schlüssel des Elements im SharedTable Objekt, das aktualisiert werden soll.
Die Funktion, die aufgerufen wird, um den neuen Wert für das Element zu berechnen.
Rückgaben
Code-Beispiele
This code sample demonstrates usage of SharedTable.update().
local st = SharedTable.new()
st["x"] = "abcd"
SharedTable.update(st, "x", function(v)
assert(v == "abcd")
return v .. "e"
end)
assert(st["x"] == "abcde")