Using Lua 5.4’s __close Metamethod for Deterministic Cleanup

Deterministic cleanup with Lua 5.4’s __close metamethod

Lua 5.4 introduces the __close metamethod, which can be triggered automatically when a local variable marked with the <close> attribute leaves its scope. This provides RAII‑style resource management without explicit pcall cleanup.

Worked example: automatic file closing

-- example.lua
local f  = assert(io.open('tmp.txt', 'w'))
f:write('hello')
-- If an error occurs here, f:close() is still called
-- error('test')   -- uncomment to test error path

The variable f is a file handle returned by io.open. File handles in Lua already implement __close that invokes the :close method. When the block ends—either normally or because of an error—the interpreter calls f:__close(), which closes the file.

How the mechanism works

• The <close> attribute tells the compiler to generate a cleanup call for the variable when its scope ends.
• The cleanup looks up the __close metamethod on the variable’s value (must be a table or userdata).
• If the metamethod returns a value, that value is ignored; returning nil is customary to avoid accidental reuse.

Limits and common mistakes

1. Version requirement: __close and the <close> syntax exist only in Lua 5.4 and later. Lua 5.3, LuaJIT, and earlier versions will raise a syntax error.
2. The variable must hold a table or userdata that provides a __close metamethod. Applying <close> to a number, string, or plain function results in a syntax error.
3. If the __close method does not return nil, the interpreter may treat the returned value as the new variable contents, leading to unexpected behavior or multiple calls.
4. Using <close> in tight loops adds a small overhead due to metamethod dispatch; for performance‑critical code consider manual close calls.
5. Code that relies on <close> is not portable to older Lua runtimes. A portable fallback wraps the resource in a pcall block and calls the cleanup function explicitly in the finally‑style section.

Verification steps (do not claim execution)

To check that the cleanup works:

1. Run the script with a Lua 5.4 interpreter: lua5.4 example.lua.
2. After execution, verify that tmp.txt contains exactly the string hello and that no file handle remains open (e.g., by checking lsof on Unix or Process Explorer on Windows).
3. Optionally uncomment the error('test') line, run again, and confirm the file is still closed and contains the written data.