Expand and clarify the __mode metaproperty

[Aseminaunz]

Changes

Clarified and expanded the use of the __mode metaproperty.

The current description makes it seem to me as if a reference to a Roblox instance is ALWAYS strong, which is not true. This is only true if the instance isn't parented to nil as there is then a reference to it in the datamodel. Weak tables containing Roblox instances are subject to garbage collection, as per my own test:

local gcForcer = setmetatable({}, { __mode = "v" })

for i = 1, 10000 do
	gcForcer[i .. "buffer"] = buffer.create(50000)
	gcForcer[i .. "rbx"] = Instance.new("Part")
end

print("Done!")
task.wait(2)

local gcedBuffers = 0
local gcedInstances = 0

for i = 1, 1000 do
	if not gcForcer[i .. "buffer"] then
		gcedBuffers += 1
	end
	if not gcForcer[i .. "rbx"] then
		gcedInstances += 1
	end
end

print("GC'ed buffers", gcedBuffers)
print("GC'ed instances", gcedInstances)
-- All show up as garbage collected

Not all userdata, however, are subject to garbage collection, as duly noted. For example, Vector3:

local gcForcer = setmetatable({}, { __mode = "v" })

for i = 1, 10000 do
	gcForcer[i .. "buffer"] = buffer.create(50000)
	gcForcer[i .. "vec"] = Vector3.new(math.random())
end

print("Done!")
task.wait(2)

local gcedBuffers = 0
local gcedVectors = 0

for i = 1, 1000 do
	if not gcForcer[i .. "buffer"] then
		gcedBuffers += 1
	end
	if not gcForcer[i .. "vec"] then
		gcedVectors += 1
	end
end

print("GC'ed buffers", gcedBuffers)
print("GC'ed vectors", gcedVectors)
-- All buffers collected, no Vector3s are gone

This expanded explanation also clarifies what "weak" means, and links to the Lua manual for a more in-depth explanation.

Checks

By submitting your pull request for review, you agree to the following:

• This contribution was created in whole or in part by me, and I have the right to submit it under the terms of this repository's open source licenses.
• I understand and agree that this contribution and a record of it are public, maintained indefinitely, and may be redistributed under the terms of this repository's open source licenses.
• To the best of my knowledge, all proposed changes are accurate.

[github-actions]

Hi @Aseminaunz, thanks so much for helping improve the Roblox creator documentation! Our technical writing team will review your pull request soon. In the meantime, please ensure you've read through the README.md, contribution guidelines, and style recommendations.

[Aseminaunz]

"Not all userdata" being garbage collectible might be a mistake now that I've learned Vector3.new simply returns a vector type. Some internal feedback on whether if all userdata is subject to garbage collection (which I assume they are, unless the engine keeps a reference) or not would be nice before I change that statement.

[vegorov-rbx]

All userdata types as well as well as thread objects (from coroutine and task libraries) are garbage-collectable and can be weak.
Vector3 is a primitive type instead of userdata now.

One other exception are string values.
Quoting Lua 5.3 manual (Luau is based on 5.1, but manual for that did not specify this):

Although strings are subject to garbage collection, they do not have an explicit construction, and therefore are not removed from weak tables.

[github-actions]

This pull request has been inactive for 14 days. If there's no activity in the next 7 days, it will be automatically closed. To keep it open, please comment or push new commits. Alternatively, add the label do-not-close to exempt it from auto-closing. 🫡 🙏