Deterministic Resource Cleanup in Lua 5.4 with To-Be-Closed Variables

When a skipped error path leaks a file descriptor

You open a file, write a few lines, then call a function that fails. In Lua 5.3 and earlier, the file handle stays open unless you explicitly close it in a cleanup path. If that path is skipped by an early return, a break, or a runtime error, the descriptor leaks. In a long-running script or an embedded application, repeated leaks eventually exhaust the process file-descriptor limit.

The standard workaround is wrapping logic in pcall or xpcall and duplicating cleanup code for every exit branch. It works, but it is verbose and easy to get wrong when control flow grows.

To-be-closed variables move cleanup into the language

Lua 5.4 introduces to-be-closed variables. You declare them with a <close> attribute, and the interpreter guarantees that the value is closed when the variable goes out of scope—whether that happens through normal execution, a return, or an error. The mechanism is the __close metamethod. For userdata that wraps C resources such as sockets or prepared statements, the host application defines __close to release the underlying handle.

During error unwinding, __close receives the object and an optional error object. That lets cleanup code distinguish a normal exit from an error propagation, though in practice the metamethod should stay simple and avoid raising new errors.

Worked example: a file handle that survives an error

The following script illustrates the pattern. It is written for Lua 5.4 or newer and is intended as a reference, not as tested output.

local path = "/tmp/lua_close_demo.txt"

local f <close> = io.open(path, "w")
if not f then error("cannot open " .. path) end

f:write("first line\n")
error("simulated failure after write")

-- Execution never reaches this point, but f is closed
-- automatically when the stack unwinds.

In Lua 5.3, the same script would leak the handle because the error call bypasses any cleanup that is not inside a protected call. With <close>, the file is closed as the variable leaves scope, even though the error propagates.

Trade-offs and hard boundaries

The feature is not a universal replacement for explicit resource management. Three constraints matter in production code:

• Version lock-in. Lua 5.1, 5.2, and 5.3 do not parse the <close> syntax or recognize the __close metamethod. If your deployment targets an older interpreter, the script will fail with a syntax error before any logic runs.
• Fragile cleanup code. Because __close runs during error unwinding, it must not raise new errors. Attempting to close an already-closed or invalid handle inside __close can produce a second error that masks the original exception and makes debugging harder.
• Memory pressure. The metamethod executes while the stack is unwinding. Heavy allocation or complex logic inside __close risks failure under low-memory conditions, which is exactly when you least want cleanup to break.

There is also a semantic limitation: <close> releases the resource when the variable goes out of scope, not when you are individually finished with it. If you need to release a handle early and continue using the same variable name, you still need an explicit close.

Verifying the behavior in your environment

Before adopting the pattern, confirm the interpreter version and observe the close behavior directly.

1. Run lua -v in your terminal or shell. The output must report Lua 5.4 or newer. If it reports 5.3 or earlier, the <close> syntax is unavailable and the script will not parse.
2. Save the worked example to a file, for example close_demo.lua, replacing /tmp/lua_close_demo.txt with a path your process can write to. Run it with lua close_demo.lua. The script will stop with the simulated error; the expected check is that the file handle is released despite the error. You can confirm this by attempting to remove or overwrite the file from another process, or by inspecting open descriptors with a tool such as lsof on Unix-like systems. If the path is not writable, io.open returns nil and the script errors before reaching the interesting part.
3. Review the Lua 5.4 manual sections on variables and the __close metamethod in your installed distribution to confirm exact semantics for your minor version.

To-be-closed variables do not remove the need to think about resource lifetimes, but they shift the default from leak-prone manual cleanup to deterministic scope-based release. For embedded applications and scripts that touch files, sockets, or database handles, that shift removes an entire class of forgotten-cleanup bugs.