Lua Weak Tables Guide — Weak References, Caches, and Memory Management

In this tutorial, you will learn about Lua Weak Tables Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Lua weak tables allow keys or values to be collected by the garbage collector when no strong references remain -- controlled by the __mode metatable field set to "k" (weak keys), "v" (weak values), or "kv" (both weak).

Weak Keys

local cache = {}
setmetatable(cache, {__mode = "k"})

-- Keys are weak, values are strong
local key = {}
cache[key] = "expensive computation"

print(cache[key])  --> "expensive computation"

key = nil  -- key is now eligible for GC
-- collectgarbage() would remove the entry

Weak Values

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

-- Keys are strong, values are weak
registry["obj1"] = {data = "temporary"}
registry["obj2"] = {data = "also temporary"}

-- When nothing else references the value objects,
-- they will be collected despite being in the table

Caching Pattern

local function memoize(func)
    local cache = {}
    setmetatable(cache, {__mode = "v"})
    
    return function(key)
        if cache[key] then
            return cache[key]
        end
        local result = func(key)
        cache[key] = result
        return result
    end
end

local heavyComputation = memoize(function(n)
    local sum = 0
    for i = 1, n do sum = sum + i end
    return sum
end)

print(heavyComputation(10000))  --> 50005000

Object Association

local properties = {}
setmetatable(properties, {__mode = "k"})

function setProperty(obj, key, value)
    if not properties[obj] then
        properties[obj] = {}
    end
    properties[obj][key] = value
end

function getProperty(obj, key)
    if properties[obj] then
        return properties[obj][key]
    end
    return nil
end

Common Mistakes

1. Using weak tables with string keys

String keys are always strong (strings are values, not objects). Weak tables work best with table or userdata keys.

2. Expecting immediate collection

Weak table entries are collected during GC cycles, not immediately when references are dropped.

3. Creating weak-key tables with number keys

Numbers are immediate values in Lua, not garbage collected. Weak keys only work for reference types.

Practice Questions

1. What does __mode = "v" do? Creates a table where values are weak references. If nothing else references a value, it can be collected.

2. Can weak tables prevent memory leaks? Yes. Weak tables allow caches to release entries when memory pressure triggers GC.

3. What types work with weak references? Tables, functions, threads, and userdata. Strings, numbers, and booleans are value types and cannot be weak.

FAQ

{{< faq question="How do I check if an entry has been collected?" >}} Access the key and check for nil. If the key or value was collected, accessing the entry returns nil. {{< /faq >}}

{{< faq question="Do weak tables affect performance?" >}} Yes. Weak table operations are slightly slower than regular tables because the GC must track and clear weak references. {{< /faq >}}

{{< faq question="Can I have weak keys and strong values?" >}} Yes. Set __mode = "k". The entry is removed when the key is collected, even if the value is still referenced elsewhere. {{< /faq >}}

What's Next

Now learn about Garbage Collection.