SharedTable
*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.
Representa uma estrutura de dados semelhante a uma mesa que pode ser compartilhada entre contextos de execução.Embora possa ser usado para vários tipos de armazenamento geral de dados, foi projetado especialmente para uso com Parallel Luau, onde pode ser usado para compartilhar estado entre scripts parentados sob diferentes Actor.
Existem algumas maneiras idiomáticas de comunicar tabelas compartilhadas entre scripts.Um método é armazenar e recuperar SharedTable objetos no SharedTableRegistry.O registro permite que qualquer script no mesmo modelo de dados obtenha ou defina um SharedTable por nome.Outro método é usar Actor:SendMessage() para enviar uma tabela compartilhada para outra Actor dentro de uma mensagem.
Como uma tabela Luau, um objeto SharedTable armazena um conjunto de pares de elementos chave-valor.Ao contrário de uma tabela Luau, apenas tipos selecionados de objetos podem ser armazenados em uma Tabela Compartilhada, semelhante a outras restrições que você encontrará em outros lugares do Roblox Engine.
Chaves devem ser (1) uma string ou (2) um número inteiro negativo menor que 2 32. Outros tipos de chaves não são suportados.
Os valores devem ter um dos seguintes tipos: Boolean, Número, Vetor, String, SharedTable ou um digitarde dado serializável.A capacidade de armazenar um SharedTable como um valor em outro SharedTable permite a construção de estruturas de dados aninhadas e recursivas.
SharedTable objetos são distintos e diferentes SharedTable objetos nunca se compararão iguais, mesmo que tenham conteúdo que se comparará igual.
Como uma tabela Luau, um objeto SharedTable pode ser congelado, no qual caso ele é leitura-somente.Uma tentativa de modificar um congelado SharedTable vai levantar um erro.Um congelado SharedTable pode ser criado primeiro criando um (não congelado, modificável) SharedTable com o conteúdo desejado, e então chamando SharedTable.cloneAndFreeze() para criar um clone congelado dele.
Amostras de código
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))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.
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)
endResumo
Construtores
- new()
Retorna um novo, vazio SharedTable.
Retorna um novo SharedTable contendo elementos equivalentes aos da tabela Luau fornecida.
Funções
Remove todos os elementos da SharedTable .
Cria e retorna um clone do fornecido SharedTable .
Cria e retorna um clone congelado (somente leitura) do fornecido SharedTable.
Adiciona delta ao valor com a chave fornecida e retorna o valor original.
Retorna true se o SharedTable estiver congelado (somente leitura).
Retorna o número de elementos armazenados no SharedTable.
Atualiza o valor com a chave fornecida através da função de atualização fornecida.
Construtores
new
Retorna um novo SharedTable contendo elementos equivalentes aos da tabela Luau fornecida.
Se a tabela Luau fornecida contiver quaisquer chaves ou valores que não possam ser armazenados em um SharedTable, a construção do SharedTable falha.Veja o resumo no topo desta página para uma lista de tipos de objetos que podem ser armazenados em um SharedTable .Se a tabela Luau contiver qualquer tabela como valor, essa tabela é convertida em uma nova SharedTable.
Observe que, em alguns casos, pode ser desejável armazenar um SharedTable em SharedTableRegistry.O método Class.ShareTableRegistry:GetSharedTable() fornece uma maneira conveniente de realizar isso.
Parâmetros
A tabela Luau cujos elementos devem ser armazenados no novo SharedTable.
Funções
clear
Remove atomivamente todos os elementos de um SharedTable .
Se o SharedTable for congelado, a operação falha e um erro será levantado.
Parâmetros
O SharedTable para limpar.
Devolução
clone
Cria um clone de um SharedTable e retorna o clone.
Se o argumento opcional deep não estiver presente ou se estiver presente e seu valor for false, então um clone superficial é criado.Uma cópia de clone superficial só copia o Objetode nível superior SharedTable.Se algum valor no próprio SharedTable for um SharedTable, então tanto o original SharedTable quanto o clone SharedTable se referirão ao mesmo SharedTable.
A operação de clonagem superficial é atômica, então o clone SharedTable conterá um instantâneo consistente do estado no original SharedTable, mesmo que esteja sendo modificado simultaneamente por outros scripts.
Se o argumento opcional deep opcional estiver presente e seu valor for true, então um clone profundo é criado.Um clone profundo copia recursivamente uma estrutura de SharedTable objetos, de modo que não haja nenhum estado compartilhado entre o original SharedTable e o clone.
O clone de cada SharedTable dentro do gráfico de objetos SharedTable é atômico, mas o clone profundo como um todo não é atômico.Assim, o clone de cada SharedTable dentro do gráfico conterá um instantâneo consistente do estado do objeto original SharedTable que foi clonado, mas os estados de diferentes objetos SharedTable podem ser inconsistentes se o gráfico estiver sendo modificado simultaneamente de outros scripts.
Os ObjetoSharedTable clonados podem ser congelados (somente leitura) ou não.Independentemente disso, os clones recém-criados não estão congelados (e, portanto, são modificáveis).Para criar clones congelados, use a função SharedTable.cloneAndFreeze.
Para ilustrar a diferença entre um clone superficial e um clone profundo, considere os seguintes exemplos.Esta primeira amostra cria um clone superficial e a segunda cria um clone profundo.
Parâmetros
O objeto SharedTable para clonar.
Se criar um clone profundo ( true ) ou um clone superficial ( false ).
Devolução
Amostras de código
This code sample creates a shallow 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, 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.
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
Cria um clone congelado (somente leitura) de um SharedTable e retorna o clone.O comportamento dessa função é o mesmo do comportamento do clone, exceto que o clone está congelado.
Se um clone profundo for solicitado, então todos os objetos clonados SharedTable congelados são congelados.
Parâmetros
O objeto SharedTable para clonar.
Se criar um clone profundo ( true ) ou um clone superficial ( false ).
Devolução
increment
Aumenta atomicamente o valor de um elemento.Um elemento com a chave especificada deve existir no SharedTable e deve ser do tipo number.O especificado delta é adicionado ao valor e o valor original é retornado.
A função SharedTable.update também pode ser usada para esse propósito; essa função increment existe para conveniência e desempenho (em geral, increment é muito mais rápida que update, portanto, deve ser preferida onde possível).As seguintes duas chamadas de função têm o mesmo efeito:
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 o SharedTable for congelado, a operação falha e um erro será levantado.
Parâmetros
O objeto SharedTable que deve ser atualizado.
A chave do elemento no objeto SharedTable a ser atualizado.
O valor a ser adicionado ao elemento na SharedTable .
Devolução
O valor original do elemento, antes de delta ser adicionado a ele.
Amostras de código
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
Retorna true se o SharedTable estiver congelado (somente leitura).
Parâmetros
O objeto SharedTable que seu estado congelado deve ser consultado.
Devolução
size
Retorna o número de elementos armazenados na Tabela Compartilhada.Observe que, se outros scripts estiverem modificando simultaneamente a Tabela Compartilhada, o tamanho retornado pode não ser mais correto após ser retornado, pois outros scripts podem ter adicionado ou removido elementos da Tabela Compartilhada.
Parâmetros
O objeto SharedTable que tem tamanho a ser consultado.
Devolução
update
Atualiza atomicamente o valor de um elemento.
Quando um SharedTable é acessado simultaneamente por scripts executados em diferentes contextos de execução, é possível que seus acessos se sobreponham de forma imprevisível.Devido a isso, código como o seguinte geralmente é incorreto, porque o valor pode ter mudado entre a leitura na primeira linha e a atualização na segunda linha:
A função de atualização torna possível realizar uma atualização atômica a um elemento.Leva uma função que será chamada com o valor atual do elemento.A função pode então calcular e retornar o novo valor.Observe que a função pode ser chamada várias vezes se o SharedTable estiver sendo modificado simultaneamente de outros scripts.
Se o SharedTable for congelado, a operação falha e um erro será levantado.
Parâmetros
O objeto SharedTable que deve ser atualizado.
A chave do elemento no objeto SharedTable a ser atualizado.
A função que será chamada para calcular o novo valor para o elemento.
Devolução
Amostras de código
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")