表示一个类似表的数据结构,可以在执行上下文之间共享。 它可以用于各种类型的一般数据存储,但它特别设计用于使用 Parallel Luau ,在不同 Actor 实例下,可以用于共享状态。
在脚本之间通信共享表时,有几种 idiomatic 方法来通信共享表。一个方法是存储和检索 SharedTable 对象在 SharedTableRegistry 。注册允许任何数据模型中的任何脚本获取或设置一个 Datatype
像 Luau 表一样,一个 SharedTable 对象存储一组键值元素对。与 Luau 表不同,只有选定的对象类型才能存储在共享表中,与您在 Roblox 引擎中找到的其他限制类似。
钥匙必须是 (1) 一个字符串或 (2) 一个不为 2 32 的非负数整数。其他类型的钥匙不是支持的。
值必须有一个以下类型之一:Boolean、Number、Vector、String、SharedTable 或串型数据输入。 允许存储一个 SharedTable 作为值在另一个 SharedTable 中的值。 允许通过将 1> Datatype.SharedTable1> 作为值在另一个 4> Datatype.SharedTable4> 中的值来构建递归递
SharedTable 对象是不同的,不同的 SharedTable 对象永远不会比平等,即使它们有容纳相同的内容。
像 Luau 表一样,一个 SharedTable 对象可能会被冻结,在此情况下它只能读取。尝试修改冰冻的 SharedTable 将会提出错误。冰冻的
代码示例
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)
end
概要
构造工具
- new()
返回一个新的、空的 SharedTable 。
返回一个新的 SharedTable 包含与提供的 Luau 表中的元素相等的元素。
职能
从SharedTable中移除所有元素。
创建并返回提供的 SharedTable 的克隆。
创建并返回提供的 SharedTable 的冰冷克隆。
添加 delta 到值与提供的钥匙,并返回原始值。
返回 true 如果 SharedTable 被冻结 (只读)。
返回 SharedTable 中存储的元素数。
使用提供的更新函数更新值。
构造工具
new
返回一个新的 SharedTable 包含与提供的 Luau 表中的元素相等的元素。
如果提供的 Luau 表包含任何不能存储在 SharedTable 中的钥匙或值,SharedTable 的建造失败。请参阅此页面上的顶部的示例,了解存储在 SharedTable 中的对象类型。如果 Luau
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")
注意,在某些情况下可能有必要将 SharedTable 存储在 SharedTableRegistry 中。 Class.ShareTableRegistry:GetSharedTable() 方法提供了一个方便的方法来实现此目标。
参数
新的 SharedTable 中要存储的 Luau 表。
职能
clear
原子移除SharedTable中的所有元素。
如果 SharedTable 被冻结,操作失败,并且会出现错误。
local st = SharedTable.new({"a", "b", "c"})assert(SharedTable.size(st) == 3)SharedTable.clear(st)assert(SharedTable.size(st) == 0)
参数
Datatype.SharedTable 清除。
返回
clone
创建一个 SharedTable 克隆,并返回克隆。
如果不是否可选的 deep 参对象,或者它是存在的,但它的值是 false ,那么一个浅度克隆会创建。
浅层克隆操作是原子的,因此克隆的 SharedTable 将包含原始 SharedTable 中的一致截图,即使它们正在从其他脚本中修改中。
如果可选的 deep 参数存在,其值是 true ,那么就会创建一个深度克隆。深度克隆会递归一个 SharedTable 对象的结构,从而不会在原始 1> Datatype.SharedTable1> 和克隆之间共享状态。
在图形中的每个 SharedTable 内的克隆是原子的,但是深度克隆作为整体不是原子的。因此,在图形中的每个 SharedTable 内的克隆将包含一
正在克隆的 SharedTable 对象(s)可能会被冻结 (只读) 或不。无论如何,新创建的克隆对象都不是 冻结 (和因此可以修改) 的。要创建冰冻克隆对象,请使用 SharedTable.cloneAndFreeze 函数。
要说明深度克隆和浅度克隆的区别,请考虑以下示例。这个第一个示例创建了一个浅度克隆,而这个第二个示例创建了一个深度克隆。
参数
Datatype.SharedTable 对象,要克隆。
是否要创建一个深度克隆 ( true ) 或一个浅层克隆 ( false )。
代码示例
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
创建一个冰封 (只读) 克隆的 SharedTable ,并返回克隆。该函数的行为与克隆的行为相同,除了冰封。
如果要求深度克隆,所有克隆的 SharedTable 对象都会被冻结。
参数
共享表对象。
是否要创建一个深度克隆 ( true ) 或一个浅层克隆 ( false )。
increment
原子增加元素的值。一个具有指定钥匙的元素必须存在在 SharedTable 中,并且必须是 型 number 。 原始 delta 是添加到值中,并且返回原始值。
SharedTable.updat更新 函数也可以用于此目的,这个 increment 函数存在于方便和性能 (一般来通用,increment 比 1> 更新pdate1> 快得多) ,因此在可能的地方应该优先使用。以下两个函数调用都有相同的效果:
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)
如果 SharedTable 被冻结,操作失败,并且会出现错误。
参数
返回
元素的原始值,在 delta 添加到它之前。
代码示例
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
返回 true 如果 SharedTable 被冻结 (只读)。
local st1 = SharedTable.new({"a", "b", "c"})assert(not SharedTable.isFrozen(st1))local st2 = SharedTable.cloneAndFreeze(st1)assert(SharedTable.isFrozen(st2))
参数
被要求查询的SharedTable对象的冰冻状态。
返回
size
返回共享表中存储的元素数量。请注意,如果其他脚本在同时修改共享表,返回的大小可能无法正确,因为其他脚本可能已经从共享表中添加或移除元素。
local st = SharedTable.new({"a", "b", "c"})assert(SharedTable.size(st) == 3)st[2] = nilassert(SharedTable.size(st) == 2)
参数
Datatype.SharedTable 个其大小需要查询的对象。
返回
update
原子更新元素的值。
当从不同的执行上下文中同时访问 SharedTable 时,它们的访问可能会意外地交叉。因此,代码如下列所示通常是错误的,因为值可能在第一行读取和第二行更新之间发生变更:
local oldValue = st["x"]st["x"] = oldValue .. ",x"
更新功能使元素的原子更新可能。它需要一个函数,该函数将以元素当前值的调用方式调用。然后函数可以计算和返回新值。注意,如果 SharedTable 正在从其他脚本中同时修改,那么函数可能需要多次调用。
如果 SharedTable 被冻结,操作失败,并且会出现错误。
参数
返回
代码示例
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")