SharedTable
*Questo contenuto è tradotto usando AI (Beta) e potrebbe contenere errori. Per visualizzare questa pagina in inglese, clicca qui.
Rappresenta una struttura dati tabellare che può essere condivisa tra contesti di esecuzione.Mentre può essere utilizzato per varie tipologie di archiviazione dati generali, è progettato specialmente per l'uso con Parallel Luau, dove può essere utilizzato per condividere lo stato tra gli script parentizzati sotto diverse Actor.
Ci sono un paio di modi idiomatici per comunicare tabelle condivise tra gli script.Un metodo è quello di archiviare e recuperare SharedTable oggetti nel SharedTableRegistry .Il registro consente a qualsiasi script nello stesso modello di dati di ottenere o impostare un SharedTable per nome.Un altro metodo è quello di utilizzare Actor:SendMessage() per inviare una tabella condivisa a un altro Actor all'interno di un Messaggio.
Come un tavolo Luau, un oggetto SharedTable memorizza un set di coppie di elementi chiave-valore.A differenza di una tabella Luau, solo i tipi di oggetti selezionati possono essere memorizzati in una tabella condivisa, simile ad altre restrizioni che troverai altrove nel motore Roblox.
Le chiavi devono essere (1) una stringa o (2) un numero intero non negativo inferiore a 2 32 . Altri tipi di chiavi non sono supportati.
I valori devono avere uno dei seguenti tipi: Boolean, Number, Vector, String, SharedTable , o un inserisci / scrividi dati serializzabile.La capacità di memorizzare un SharedTable come valore in un altro SharedTable consente la costruzione di strutture dati nidate e ricorsive.
SharedTable gli oggetti sono distinti e diversi SharedTable gli oggetti non si confrontano mai uguali, anche se hanno contenuti che potrebbero essere uguali.
Come un tavolo Luau, un oggetto SharedTable può essere congelato, in cui caso è in lettura solo.Un tentativo di modificare un congelato SharedTable porterà un errore.Un congelato SharedTable può essere creato prima creando un (non congelato, modificabile) SharedTable con i contenuti desiderati, e poi chiamando SharedTable.cloneAndFreeze() per creare un clone congelato di esso.
Campioni di codice
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))Il ciclo for può essere utilizzato per itterare sugli elementi di un SharedTable .Gli elementi del SharedTable non vengono iterati direttamente.Invece, un clone superficiale è fatto di SharedTable , e i suoi elementi vengono iterati.Questo viene fatto per garantire che venga mantenuta una vista coerente del SharedTable durante l'iterazione.Pertanto, entrambi i seguenti per i cicli hanno lo stesso comportamento.
Nota che questo significa che se l'SharedTable è accessibile direttamente dal corpo del ciclo di iterazione, il suo stato potrebbe non essere coerente con lo stato osservato attraverso l'iterazione.
L'ordine di iterazione è parzialmente specificato.Gli elementi con chiavi numeriche vengono iterati prima degli elementi con chiavi di stringa.Gli elementi con chiavi numeriche vengono iterati in ordine crescente numerico.Gli elementi con chiavi di stringa vengono iterati in un ordine non specificato.
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)
endSommario
Costruttori
- new()
Restituisce un nuovo, vuoto SharedTable .
Restituisce un nuovo SharedTable contenente elementi equivalenti a quelli nella tabella Luau fornita.
Funzioni
Rimuove tutti gli elementi dal SharedTable .
Crea e restituisce un clone del fornito SharedTable .
Crea e restituisce un clone congelato (read-only) del fornito SharedTable .
Aggiunge delta alla valenza con la chiave fornita e restituisce il valore originale.
Restituisce true se il SharedTable è congelato (read-only).
Restituisce il numero di elementi memorizzati nel SharedTable .
Aggiorna il valore con la chiave fornita attraverso la funzione di aggiornamento fornita.
Costruttori
new
Restituisce un nuovo SharedTable contenente elementi equivalenti a quelli nella tabella Luau fornita.
Se la tabella Luau fornita contiene qualsiasi chiave o valore che non può essere memorizzato in un SharedTable, la costruzione del SharedTable fallisce.Vedi la sintesi nella parte superiore di questa pagina per un elenco di tipi di oggetti che possono essere memorizzati in un SharedTable .Se la tabella Luau contiene qualsiasi tabella come valore, quella tabella viene convertita in una nuova SharedTable .
Si noti che in alcuni casi potrebbe essere desiderabile archiviare un SharedTable in SharedTableRegistry.Il metodo Class.ShareTableRegistry:GetSharedTable() fornisce un modo conveniente per realizzarlo.
Parametri
La tabella Luau i cui elementi devono essere memorizzati nel nuovo SharedTable .
Funzioni
clear
Rimuove atomicamente tutti gli elementi da un SharedTable .
Se il SharedTable è congelato, l'operazione fallisce e verrà sollevata un'errore.
Parametri
Il SharedTable per Eliminare/Pulire.
Restituzioni
clone
Crea un clone di un SharedTable e restituisce il clone.
Se l'argomento opzionale deep non è presente, o se è presente e il suo valore è false , viene creato un clonaggio superficiale.Un clone superficiale copia solo l'oggetto di alto livello SharedTable .Se qualsiasi valore nell'SharedTable stesso è un SharedTable , allora sia l'originale SharedTable che il clone SharedTable si riferiranno allo stesso SharedTable .
L'operazione di clonazione superficiale è atomica, quindi il clone SharedTable conterrà uno snapshot coerente dello stato nell'originale SharedTable, anche se viene modificato contemporaneamente da altri script.
Se l'argomento opzionale deep è presente e il suo valore è true, viene creato un clone profondo.Un clone profondo copia ricorsivamente una struttura di SharedTable oggetti, in modo che non ci sia uno stato condiviso tra l'originale SharedTable e il clone.
Il clone di ciascun SharedTable all'interno del grafico di oggetti SharedTable è atomico, ma il deep clone nel suo complesso non è atomico.Pertanto, il clone di ogni SharedTable all'interno del grafico conterrà uno snapshot coerente dello stato dell'oggetto originale SharedTable da cui è stato clonato, ma gli stati di diversi oggetti SharedTable possono essere incoerenti se il grafico viene modificato contemporaneamente da altri script.
Gli oggettoSharedTable in clonamento possono essere congelati (lettura solo) o no.Indipendentemente da ciò, le nuove cloni create sono non congelate (e sono quindi modificabili).Per creare cloni congelati, usa la funzione SharedTable.cloneAndFreeze.
Per illustrare la differenza tra un clone superficiale e un clone profondo, considera i seguenti esempi.Questo primo campione crea un clone superficiale e il secondo crea un clone profondo.
Parametri
L'oggetto SharedTable da clonare.
Se creare un clone profondo ( true ) o un clone superficiale ( false ).
Restituzioni
Campioni di codice
Questo esempio di codice crea un clone superficiale di un 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")
-- Poiché questo era un clone superficiale, original ["c"] e clone ["c"] sono
-- lo stesso oggetto SharedTable condiviso.
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
Crea un clone congelato (read-only) di un SharedTable e restituisce il clone.Il comportamento di questa funzione è lo stesso del comportamento del clone, tranne che il clone è congelato.
Se viene richiesta una clonazione profonda, tutti gli oggetti clonati SharedTable vengono congelati.
Parametri
L'oggetto SharedTable da clonare.
Se creare un clone profondo ( true ) o un clone superficiale ( false ).
Restituzioni
increment
Aumenta atomicamente il valore di un elemento.Un elemento con la chiave specificata deve esistere nel SharedTable, e deve essere di tipo number.Il delta viene aggiunto al valore e viene restituito il valore originale.
La funzione SharedTable.update può essere utilizzata anche a questo scopo; questa funzione increment esiste per comodità e prestazioni (in Generale, increment è molto più veloce di update, quindi dovrebbe essere preferita dove possibile).Le seguenti due chiamate di funzione hanno lo stesso effetto:
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)
Se il SharedTable è congelato, l'operazione fallisce e verrà sollevata un'errore.
Parametri
L'oggetto SharedTable da aggiornare.
La chiave dell'elemento nell'oggetto SharedTable da aggiornare.
Il valore da aggiungere all'elemento in SharedTable .
Restituzioni
Il valore originale dell'elemento, prima che delta fosse aggiunto ad esso.
Campioni di codice
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
Restituisce true se il SharedTable è congelato (read-only).
Parametri
L'oggetto SharedTable il cui stato congelato deve essere interrogato.
Restituzioni
size
Restituisce il numero di elementi memorizzati nella tabella condivisa.Si noti che se altri script stanno modificando contemporaneamente la tabella condivisa, la dimensione restituita potrebbe non essere più corretta dopo il suo ritorno, poiché altri script possono aver aggiunto o rimosso elementi dalla tabella condivisa.
Parametri
L'oggetto SharedTable il cui dimension è da interrogare.
Restituzioni
update
Aggiorna atomicamente il valore di un elemento.
Quando un SharedTable è accessibile contemporaneamente da script in esecuzione in diversi contesti di esecuzione, è possibile che i loro accessi si mescolino in modo imprevedibile.A causa di ciò, il codice come il seguente è generalmente errato, poiché il valore potrebbe essere cambiato tra la lettura sulla prima linea e l'aggiornamento sulla seconda linea:
La funzione di aggiornamento rende possibile eseguire un aggiornamento atomico a un elemento.Prende una funzione che chiamerà con il valore attuale dell'elemento.La funzione può quindi calcolare e restituire il nuovo valore.Nota che la funzione può essere chiamata più volte se il SharedTable viene modificato contemporaneamente da altri script.
Se il SharedTable è congelato, l'operazione fallisce e verrà sollevata un'errore.
Parametri
L'oggetto SharedTable da aggiornare.
La chiave dell'elemento nell'oggetto SharedTable da aggiornare.
La funzione che verrà chiamata per calcolare il nuovo valore per l'elemento.
Restituzioni
Campioni di codice
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")