Closures in Lua

Analogy categoryAnalogies

A closure is a function bundled together with references to the non-local variables, called upvalues, from the lexical scope in which it was created. Because Lua supports lexical scoping and treats functions as first-class values, any function that refers to a variable from an enclosing scope automatically becomes a closure over that variable, and it keeps working correctly even after the enclosing function has returned.

🏏

Cricket analogy: A commentator who's followed a player's entire career carries that context, like 'he was dropped on 4 back in the 2019 series', into every remark, the same way a Lua closure carries its captured upvalues with it wherever the function goes.

How Closures Capture Upvalues

Lua closures capture upvalues by reference, not by value. When two functions created in the same scope both refer to the same local variable, they share that exact variable: if one function modifies it, the change is immediately visible to the other. This is what makes the classic counter idiom work — local count = 0; local function inc() count = count + 1 end — where repeated calls to inc() keep mutating the same shared count upvalue.

🏏

Cricket analogy: A shared 'team total' scoreboard variable updated by both the striker's and non-striker's run functions is exactly how two closures created in the same scope share the same upvalue by reference, updating it from either function updates both.

lua

local function makeCounter()
    local count = 0  -- upvalue captured by the closures below
    local function increment()
        count = count + 1
        return count
    end
    local function reset()
        count = 0
    end
    return increment, reset
end

local inc, reset = makeCounter()
print(inc())  --> 1
print(inc())  --> 2
reset()
print(inc())  --> 1

Closures for Private State and Encapsulation

Calling a factory function multiple times creates a fresh, independent set of upvalues on each call, so closures returned from separate calls never interfere with one another. This makes the closure-based factory pattern — local function makeThing() local state = ...; return function() ... end end — a lightweight way to build encapsulated, object-like instances in Lua without defining a class or reaching for metatables.

🏏

Cricket analogy: makeScorer() called separately for two different matches produces two completely independent closures, each with its own private runs upvalue, updating one match's score never touches the other's, the way each stadium's scoreboard is independent.

The closure-based factory pattern (local function makeThing() local state = ...; return function() ... end end) is Lua's lightweight alternative to classes for simple encapsulation — no metatables required. Each call to the factory creates a fresh, independent set of upvalues, so instances never interfere with each other.

Closures Inside Loops

Because each iteration of a Lua for loop creates a fresh local copy of the control variable, closures built inside the loop body correctly capture each iteration's own value, not one variable shared across all iterations. This is a place where Lua's behavior is more predictable than some other languages: there's no need for an extra 'capture' trick to get distinct values in each closure.

🏏

Cricket analogy: for i = 1, 11 do fielders[i] = function() return i end end gives every fielder function its own correctly captured jersey number, because Lua creates a brand-new local i each iteration, unlike languages where all eleven functions might mistakenly report the same final number.

lua

-- correct: each iteration binds a fresh local, so each closure
-- captures its own value of i
local fns = {}
for i = 1, 3 do
    fns[i] = function() return i end
end
print(fns[1](), fns[2](), fns[3]())  --> 1  2  3

-- contrast: reusing one outer variable across manual iterations
-- would share the same upvalue (a common bug pattern to avoid)
local sharedFns = {}
local j = 0
while j < 3 do
    j = j + 1
    local captured = j       -- must re-bind locally to avoid sharing
    sharedFns[j] = function() return captured end
end
print(sharedFns[1](), sharedFns[2](), sharedFns[3]())  --> 1  2  3

Common Uses: Callbacks, Memoization, and Iterators

Closures underlie three common Lua patterns: custom stateful iterators that remember their position between calls via an upvalue, memoized functions that cache expensive results in an upvalue table so repeated calls with the same input skip recomputation, and event callbacks that need to retain context from where they were registered.

🏏

Cricket analogy: A stateful custom iterator that 'remembers' which ball of the over it's on, returned as a closure from overIterator(), is the same pattern as memoizing an expensive player-rating calculation in an upvalue table so it's computed once per player, not every time it's queried.

Because closures hold a live reference to their upvalues, a memoizing closure's cache table keeps every result alive for as long as the closure itself exists, which can leak memory if the closure is long-lived and the cache keys are unbounded (for example, keyed by ever-changing input objects). Clear or bound the cache explicitly when memoizing long-running processes.

A closure is a function bundled together with references to the variables (upvalues) from the scope in which it was created.
Upvalues are captured by reference, not by value; multiple closures created in the same scope that reference the same local variable all see each other's updates.
Calling a factory function like makeCounter() multiple times creates independent sets of upvalues, giving each closure its own private state without needing a class or metatable.
Each iteration of a Lua for loop creates a fresh local control variable, so closures created inside a loop correctly capture each iteration's own value.
Closures are the mechanism behind custom stateful iterators, memoization caches, and callback-based APIs in Lua.
A long-lived closure keeps its upvalues, and anything they reference, alive for as long as the closure exists, which can cause memory to grow if not managed.