Lua Garbage Collection
Lua employs automatic memory management. This means you do not need to worry about how the memory for new objects is allocated, nor how to release the memory occupied by objects that are no longer in use.
Lua runs a garbage collector to collect all dead objects (i.e., objects that are no longer accessible in Lua) to perform automatic memory management. All memory used by Lua, such as strings, tables, userdata, functions, threads, internal structures, etc., is subject to automatic management.
Lua implements an incremental mark-and-sweep collector. It uses two numbers to control the garbage collection cycle: the garbage collector pause and the garbage collector step multiplier. These numbers are expressed as percentages (e.g., a value of 100 internally represents 1).
The garbage collector pause controls how long the collector waits before starting a new cycle. Increasing this value reduces the collector's aggressiveness. If this value is less than 100, the collector will not wait before starting a new cycle. Setting this value to 200 will make the collector wait until the total memory usage is twice the previous amount before starting a new cycle.
The garbage collector step multiplier controls the speed of the collector relative to memory allocation speed. Increasing this value not only makes the collector more aggressive but also increases the length of each incremental step. Do not set this value below 100, as the collector would then work too slowly to complete a cycle. The default value is 200, which means the collector works at "twice" the speed of memory allocation.
If you set the step multiplier to a very large number (larger than 10% of the maximum number of bytes your program might use), the collector behaves like a stop-the-world collector. If you then set the pause to 200, the collector behaves as it did in previous versions of Lua: it performs a full collection each time Lua's memory usage doubles.
Garbage Collector Functions
Lua provides the following function collectgarbage ([opt [, arg]]) to control automatic memory management:
-
collectgarbage("collect"): Performs a full garbage collection cycle. It provides a set of different functionalities through the parameter opt:
-
collectgarbage("count"): Returns the total memory used by Lua in Kbytes. This value has a fractional part, so multiplying it by 1024 gives the exact number of bytes used by Lua (unless overflow occurs).
-
collectgarbage("restart"): Restarts the automatic execution of the garbage collector.
-
collectgarbage("setpause"): Sets arg as the collector's pause. Returns the previous value of the pause.
-
collectgarbage("setstepmul"): Returns the previous value of the step multiplier.
-
collectgarbage("step"): Runs the garbage collector for a step. The "size" of the step is controlled by arg. Passing 0 causes the collector to perform an (indivisible) step. Passing a non-zero value causes the collector to collect an amount of work proportional to the amount of memory allocated by Lua in Kbytes. If the collector completes a cycle, it returns true.
-
collectgarbage("stop"): Stops the execution of the garbage collector. The collector will only run due to explicit calls until it is restarted.
The following demonstrates a simple garbage collection example:
Example
mytable = {"apple", "orange", "banana"}
print(collectgarbage("count"))
mytable = nil
print(collectgarbage("count"))
print(collectgarbage("collect"))
print(collectgarbage("count"))
Executing the above program yields the following output (note the changes in memory usage):
20.9560546875
20.9853515625
0
19.4111328125