SharedTable

Pokaż przestarzałe

*Ta zawartość została przetłumaczona przy użyciu narzędzi AI (w wersji beta) i może zawierać błędy. Aby wyświetlić tę stronę w języku angielskim, kliknij tutaj.

Reprezentuje strukturę danych podobną do tabeli, którą można udostępniać między kontekstami wykonania.Chociaż może być używany do różnych rodzajów przechowywania ogólnych danych, jest przeznaczony specjalnie do użytku z Parallel Luau, gdzie może być używany do udostępniania stanu między skryptami powiązanymi z różnymi Actor.

Istnieją kilka idiomatycznych sposobów komunikacji wspólnych tabel między skryptami.Jedną z metod jest przechowywanie i odzyskiwanie obiektów SharedTable w SharedTableRegistry.Rejestr pozwala każdemu skryptowi w tym samym modelu danych uzyskać lub ustawić SharedTable nazwę.Inną metodą jest użycie Actor:SendMessage(), aby wysłać wspólny stół do innego Actor wewnątrz wiadomość.

Podobnie jak tablica Luau, obiekt SharedTable przechowuje zestaw pary kluczowo-wartościowych elementów.W przeciwieństwie do tabeli Luau, tylko wybrane rodzaje obiektów mogą być przechowywane w tabeli wspólnej, podobnie jak inne ograniczenia, które znajdziesz gdzie indziej w Roblox Engine.

Klucze muszą być (1) ciągiem lub (2) negatywnie nieujemną liczbą całkowitą mniejszą niż 2 32. Inne rodzaje kluczy nie są wspierane.

Wartości muszą mieć jeden z następujących typów: Boolean, Number, Vector, String, SharedTable lub wpisywaćdanych serializowalnych.Możliwość przechowywania SharedTable jako wartości w innym SharedTable pozwala na budowę struktur danych hierarchicznych i recursywnych.

SharedTable obiekty są odrębne i różne SharedTable obiekty nigdy nie są porównywane równe, nawet jeśli mają zawartość, która byłaby równa.

Podobnie jak w tabeli Luau, obiekt SharedTable może zostać zamrożony, w którym przypadku jest on odczytywany tylko w trybie odczytu.Próba zmodyfikowania zamrożonego SharedTable spowoduje wystąpienie błędu.Zamrożone SharedTable można utworzyć, najpierw utworzyć (nie zamrożone, edytowalne) SharedTable z żądaną zawartością, a następnie wezwać SharedTable.cloneAndFreeze() , aby stworzyć zamrożoną kopię tego.

Przykłady kodu

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.

Element Access
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))

The for loop can be used to iterate over the elements of a SharedTable. The elements of the SharedTable are not iterated directly. Instead, a shallow clone is made of the SharedTable, and its elements are iterated. This is done to ensure that a consistent view of the SharedTable is maintained throughout the iteration. Thus, both of the following for loops have the same behavior.

Note that this means that if the SharedTable is accessed directly from within the body of the iteration loop, its state may not be consistent with the state observed through the iteration.

The iteration order is partially specified. Elements with numeric keys are iterated before elements with string keys. Elements with numeric keys are iterated in ascending numeric order. Elements with string keys are iterated in an unspecified order.

Element Iteration
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

Podsumowanie

Konstruktorzy

Funkcje

Konstruktorzy

new

Zwraca nowy, pusty SharedTable.

local st = SharedTable.new()

new

Zwraca nowy SharedTable zawierający elementy równoważne tym w dostarczonej tabeli Luau.

Jeśli dostarczony stół Luau zawiera jakiekolwiek klucze lub wartości, które nie mogą być przechowywane w SharedTable, budowa SharedTable zawodzi.Zobacz podsumowanie na górze tej strony dla listy rodzajów obiektów, które można przechować w SharedTable .Jeśli tabela Luau zawiera jakąkolwiek tabelę jako wartość, ta tabela jest przekształcona w nową SharedTable.

local t = {}

t.x = 1

t.y = 2

t.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")

Zauważ, że w niektórych przypadkach możliwe jest przechowywanie SharedTable w SharedTableRegistry.Metoda Class.ShareTableRegistry:GetSharedTable() zapewnia wygodny sposób na osiągnięcie tego celu.

Parametry

t: table

Tabela Luau, której elementy mają być przechowywane w nowej SharedTable.

Funkcje

clear

()

Atomowo usuwa wszystkie elementy z SharedTable .

Jeśli SharedTable jest zamrożony, operacja nie powodzi się i zostanie podniesiony błąd.

local st = SharedTable.new({"a", "b", "c"})

assert(SharedTable.size(st) == 3)



SharedTable.clear(st)

assert(SharedTable.size(st) == 0)

Parametry

st: SharedTable

The SharedTable do czyścić.

Zwroty

()

clone

SharedTable

Tworzy kopię SharedTable i zwraca kopię.

Jeśli opcjonalny argument deep nie jest obecny, lub jeśli jest obecny i jego wartość jest false, to tworzy się płytki klon.Płytki klon kopiuje tylko najwyższy poziom SharedTable obiektu.Jeśli wartość w SharedTable sama w sobie jest SharedTable, wtedy zarówno oryginalny SharedTable jak i klon SharedTable odwołają się do tego samego SharedTable.

Operacja klonowania płytkiego jest atomowa, więc klon SharedTable będzie zawierał spójny zapis stanu w oryginalnym SharedTable, nawet jeśli jest modyfikowany równocześnie z innymi skryptami.

Jeśli opcjonalny argument deep jest obecny i jego wartość to true, to tworzy się głęboki klon.Głęboki klon kopiuje w sposób recursywny strukturę SharedTable obiektów, tak że nie ma stanu współdzielonego między oryginalnym SharedTable a klonem.

Kopia każdego SharedTable wewnątrz grafu obiektów SharedTable jest atomowa, ale głęboki klon jako całość nie jest atomowy.Tak więc klon każdego SharedTable w ramach grafu będzie zawierał spójny zapis stanu oryginalnego obiektu SharedTable, z którego został sklonowany, ale stany różnych obiektów SharedTable mogą być niezgodne, jeśli graf jest modyfikowany równocześnie z innymi skryptami.

Przedmioty SharedTable zostające w klonowaniu mogą być zamrożone (do odczytu) lub nie.Niezależnie od tego, nowo utworzone klony nie są zamrożone (i są więc modyfikowalne).Aby stworzyć zamrożone klony, użyj funkcji SharedTable.cloneAndFreeze.

Aby zilustrować różnicę między płytkim klonem a głębokim klonem, rozważ następujące przykłady.Ten pierwszy przykład tworzy płytki klon, a drugi tworzy głęboki klon.

Parametry

st: SharedTable

Przedmiot SharedTable do sklonowania.

deep: boolean

Czy utworzyć głęboką kopię ( true ) lub płytką kopię ( false ).

Wartość domyślna: false

Zwroty

SharedTable

Przykłady kodu

This code sample creates a shallow clone of a SharedTable.

Shallow Clone
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")



-- Because this was a shallow clone, original["c"] and clone["c"] are

-- the same SharedTable object.

assert(original["c"] == clone["c"])

assert(original["c"]["d"] == "new d")

This code sample creates a deep clone of a SharedTable.

Deep Clone
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

SharedTable

Tworzy zamrożoną (tylko do odczytu) kopię SharedTable i zwraca kopię.Zachowanie tej funkcji jest takie same jak zachowanie klonu, z wyjątkiem tego, że klon jest zamrożony.

Jeśli wymagany jest głęboki klon, wszystkie klonowane obiekty SharedTable są zamrażane.

Parametry

st: SharedTable

Obiekt SharedTable do klonowania.

deep: boolean

Czy utworzyć głęboką kopię ( true ) lub płytką kopię ( false ).

Wartość domyślna: false

Zwroty

SharedTable

increment

number

Atomowo zwiększa wartość elementu.Element z określonym kluczem musi istnieć w SharedTable, a musi być typu number.Określony delta zostaje dodany do wartości i zwracana jest oryginalna wartość.

Funkcja SharedTable.update może być również używana do tego celu; ta funkcja increment istnieje dla wygody i wydajności (ogólnerzecz biorąc, increment jest znacznie szybsza niż update, więc powinna być preferowana tam, gdzie to możliwe).Następujące dwie wezwania funkcji mają ten sam efekt:

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)

Jeśli SharedTable jest zamrożony, operacja nie powodzi się i zostanie podniesiony błąd.

Parametry

st: SharedTable

Przedmiot SharedTable , który ma zostać zaktualizowany.

key: string | number

Klucz elementu w obiekcie SharedTable, który ma zostać zaktualizowany.

delta: number

Wartość, którą należy dodać do elementu w SharedTable.

Zwroty

number

Pierwotna wartość elementu, zanim delta została do niego dodana.

Przykłady kodu

This code sample demonstrates usage of SharedTable.increment().

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

boolean

Wyświetla true jeśli SharedTable jest zamrożone (tylko do odczytu).

local st1 = SharedTable.new({"a", "b", "c"})

assert(not SharedTable.isFrozen(st1))



local st2 = SharedTable.cloneAndFreeze(st1)

assert(SharedTable.isFrozen(st2))

Parametry

st: SharedTable

Obiekt SharedTable, którego zamrożony stan ma być zapytany.

Zwroty

boolean

size

number

Zwraca liczbę elementów przechowanych w SharedTable.Zauważ, że jeśli inne skrypty jednocześnie modyfikują SharedTable, rozmiar zwrócony po jego powrocie może nie być już poprawny, ponieważ inne skrypty mogły dodać lub usunąć elementy z SharedTable.

local st = SharedTable.new({"a", "b", "c"})

assert(SharedTable.size(st) == 3)



st[2] = nil

assert(SharedTable.size(st) == 2)

Parametry

st: SharedTable

Obiekt SharedTable, którego rozmiar ma być zapytany.

Zwroty

number

update

()

Atomowo aktualizuje wartość elementu.

Gdy SharedTable jest dostępny równocześnie z wykonywanymi w różnych kontekstach wykonania skryptami, możliwe jest, że ich dostępy będą się wzajemnie przenikać nieprzewidywalnie.Z tego powodu kod takich jak poniższy jest ogólnie nieprawidłowy, ponieważ wartość może się zmienić między odczytaniem na pierwszej linii a aktualizacją na drugiej linii:

local oldValue = st["x"]

st["x"] = oldValue .. ",x"

Funkcja aktualizacji umożliwia wykonanie atomowej aktualizacji do elementu.Wymaga funkcji, którą wezwie z obecną wartością elementu.Funkcja może następnie obliczyć i zwrócić nową wartość.Zauważ, że funkcja może być wywołana wielokrotnie, jeśli SharedTable jest jednocześnie modyfikowana z innych skryptów.

Jeśli SharedTable jest zamrożony, operacja nie powodzi się i zostanie podniesiony błąd.

Parametry

st: SharedTable

Przedmiot SharedTable , który ma zostać zaktualizowany.

key: string | number

Klucz elementu w obiekcie SharedTable, który ma zostać zaktualizowany.

f: function

Funkcja, która zostanie wywołana, aby obliczyć nową wartość dla elementu.

Zwroty

()

Przykłady kodu

This code sample demonstrates usage of SharedTable.update().

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")