SharedTable

显示已弃用

*此内容使用人工智能（Beta）翻译，可能包含错误。若要查看英文页面，请点按 此处。

表示一个类似表的数据结构，可以在执行上下文之间共享。 它可以用于各种类型的一般数据存储，但它特别设计用于使用 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.

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

概要

构造工具

职能

构造工具

new

返回一个新的、空的 SharedTable 。

local st = SharedTable.new()

new

返回一个新的 SharedTable 包含与提供的 Luau 表中的元素相等的元素。

如果提供的 Luau 表包含任何不能存储在 SharedTable 中的钥匙或值，SharedTable 的建造失败。请参阅此页面上的顶部的示例，了解存储在 SharedTable 中的对象类型。如果 Luau

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

注意，在某些情况下可能有必要将 SharedTable 存储在 SharedTableRegistry 中。 Class.ShareTableRegistry:GetSharedTable() 方法提供了一个方便的方法来实现此目标。

参数

t: table

新的 SharedTable 中要存储的 Luau 表。

职能

clear

void

原子移除SharedTable中的所有元素。

如果 SharedTable 被冻结，操作失败，并且会出现错误。

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

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



SharedTable.clear(st)

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

参数

st: SharedTable

Datatype.SharedTable 清除。

返回

void

clone

SharedTable

创建一个 SharedTable 克隆，并返回克隆。

如果不是否可选的 deep 参对象，或者它是存在的，但它的值是 false ，那么一个浅度克隆会创建。

浅层克隆操作是原子的，因此克隆的 SharedTable 将包含原始 SharedTable 中的一致截图，即使它们正在从其他脚本中修改中。

如果可选的 deep 参数存在，其值是 true ，那么就会创建一个深度克隆。深度克隆会递归一个 SharedTable 对象的结构，从而不会在原始 1> Datatype.SharedTable1> 和克隆之间共享状态。

在图形中的每个 SharedTable 内的克隆是原子的，但是深度克隆作为整体不是原子的。因此，在图形中的每个 SharedTable 内的克隆将包含一

正在克隆的 SharedTable 对象(s)可能会被冻结 (只读) 或不。无论如何，新创建的克隆对象都不是 冻结 (和因此可以修改) 的。要创建冰冻克隆对象，请使用 SharedTable.cloneAndFreeze 函数。

要说明深度克隆和浅度克隆的区别，请考虑以下示例。这个第一个示例创建了一个浅度克隆，而这个第二个示例创建了一个深度克隆。

参数

st: SharedTable

Datatype.SharedTable 对象，要克隆。

deep: bool

是否要创建一个深度克隆 ( true ) 或一个浅层克隆 ( false )。

默认值：false

返回

SharedTable

代码示例

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

创建一个冰封 (只读) 克隆的 SharedTable ，并返回克隆。该函数的行为与克隆的行为相同，除了冰封。

如果要求深度克隆，所有克隆的 SharedTable 对象都会被冻结。

参数

st: SharedTable

共享表对象。

deep: bool

是否要创建一个深度克隆 ( true ) 或一个浅层克隆 ( false )。

默认值：false

返回

SharedTable

increment

number

原子增加元素的值。一个具有指定钥匙的元素必须存在在 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 被冻结，操作失败，并且会出现错误。

参数

st: SharedTable

Datatype.SharedTable 对象需要更新。

key: string | number

在 SharedTable 对象中元素的钥匙。

delta: number

值将被添加到SharedTable中的元素。

返回

number

元素的原始值，在 delta 添加到它之前。

代码示例

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

bool

返回 true 如果 SharedTable 被冻结 (只读)。

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

assert(not SharedTable.isFrozen(st1))



local st2 = SharedTable.cloneAndFreeze(st1)

assert(SharedTable.isFrozen(st2))

参数

st: SharedTable

被要求查询的SharedTable对象的冰冻状态。

返回

bool

size

number

返回共享表中存储的元素数量。请注意，如果其他脚本在同时修改共享表，返回的大小可能无法正确，因为其他脚本可能已经从共享表中添加或移除元素。

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

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



st[2] = nil

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

参数

st: SharedTable

Datatype.SharedTable 个其大小需要查询的对象。

返回

number

update

void

原子更新元素的值。

当从不同的执行上下文中同时访问 SharedTable 时，它们的访问可能会意外地交叉。因此，代码如下列所示通常是错误的，因为值可能在第一行读取和第二行更新之间发生变更：

local oldValue = st["x"]

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

更新功能使元素的原子更新可能。它需要一个函数，该函数将以元素当前值的调用方式调用。然后函数可以计算和返回新值。注意，如果 SharedTable 正在从其他脚本中同时修改，那么函数可能需要多次调用。

如果 SharedTable 被冻结，操作失败，并且会出现错误。

参数

st: SharedTable

Datatype.SharedTable 对象需要更新。

key: string | number

在 SharedTable 对象中元素的钥匙。

f: function

将被调用的函数用于计算元素的新值。

返回

void

代码示例

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