SharedTable

Returns a new, empty SharedTable.

local st = SharedTable.new()

Returns a new SharedTable containing elements equivalent to those in the provided Luau table.

If the provided Luau table contains any keys or values that cannot be stored in a SharedTable, construction of the SharedTable fails. See the summary at the top of this page for a list of types of objects that can be stored in a SharedTable. If the Luau table contains any table as a value, that table is converted into a new 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")

Note that in some cases it may be desirable to store a SharedTable in the SharedTableRegistry. The ShareTableRegistry:GetSharedTable() method provides a convenient way to accomplish this.

Atomically removes all of the elements from a SharedTable.

If the SharedTable is frozen, the operation fails and an error will be raised.

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

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

Creates a clone of a SharedTable and returns the clone.

If the optional deep argument is not present, or if it is present and its value is false, then a shallow clone is created. A shallow clone copies only the top-level SharedTable object. If any value in the SharedTable itself is a SharedTable, then both the original SharedTable and the clone SharedTable will refer to the same SharedTable.

The shallow clone operation is atomic, so the clone SharedTable will contain a consistent snapshot of the state in the original SharedTable, even if it is being modified concurrently from other scripts.

If the optional deep argument is present and its value is true, then a deep clone is created. A deep clone recursively copies a structure of SharedTable objects, such that there is no state shared between the original SharedTable and the clone.

The clone of each SharedTable within the graph of SharedTable objects is atomic, but the deep clone as a whole is not atomic. Thus, the clone of each SharedTable within the graph will contain a consistent snapshot of the state of the original SharedTable object from which it was cloned, but the states of different SharedTable objects may be inconsistent if the graph is being modified concurrently from other scripts.

The SharedTable object(s) being cloned may be frozen (read-only) or not. Regardless, the newly created clones are not frozen (and are thus modifiable). To create frozen clones, use the SharedTable.cloneAndFreeze function.

To illustrate the difference between a shallow clone and a deep clone, consider the following samples. This first sample creates a shallow clone and the second creates a deep clone.

Creates a frozen (read-only) clone of a SharedTable and returns the clone. The behavior of this function is the same as the behavior of clone, except that the clone is frozen.

If a deep clone is requested, then all of the cloned SharedTable objects are frozen.

Atomically increments the value of an element. An element with the specified key must exist in the SharedTable, and it must be of type number. The specified delta is added to the value, and the original value is returned.

The SharedTable.update function can also be used for this purpose; this increment function exists for convenience and performance (in general, increment is much faster than update, so it should be preferred where possible). The following two function calls have the same effect:

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)

If the SharedTable is frozen, the operation fails and an error will be raised.

Returns true if the SharedTable is frozen (read-only).

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

local st2 = SharedTable.cloneAndFreeze(st1)
assert(SharedTable.isFrozen(st2))

Returns the number of elements stored in the SharedTable. Note that if other scripts are concurrently modifying the SharedTable, the returned size may no longer be correct after it is returned, since other scripts may have added or removed elements from the SharedTable.

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

st[2] = nil
assert(SharedTable.size(st) == 2)

Atomically updates the value of an element.

When a SharedTable is accessed concurrently from scripts running in different execution contexts, it is possible for their accesses to interleave unpredictably. Because of this, code like the following is generally incorrect, because the value may have changed between the read on the first line and the update on the second line:

local st = SharedTable.new({ x = "a" })
local oldValue = st["x"]
st["x"] = oldValue .. ",x"
print(st["x"]) --> a,x

The update function makes it possible to perform an atomic update to an element. It takes a function that it will call with the current value of the element. The function can then compute and return the new value. Note that the function may be called multiple times if the SharedTable is being concurrently modified from other scripts.

If the SharedTable is frozen, the operation fails and an error will be raised.