Lua Garbage Collection

Lua uses automatic memory management. This means you don't need to worry about how memory for newly created objects is allocated, nor about how to free the memory they occupy after the objects are no longer used.

Lua runs agarbage collectorto collect alldead objects(i.e., objects that can no longer be accessed in Lua) to complete the work of automatic memory management. All memory used in Lua, such as strings, tables, user data, functions, threads, internal structures, etc., is subject to automatic management.

Lua implements an incremental mark-and-sweep collector. It uses these two numbers to control the garbage collection cycle: the garbage collector pause rate and the garbage collector step multiplier. Both numbers are in percent units (e.g., the value 100 is internally represented as 1).

The garbage collector pause controls how long the collector needs to wait before starting a new cycle. Increasing this value reduces the collector's enthusiasm. When this value is less than 100, the collector will not wait before starting a new cycle. Setting this value to 200 will cause the collector to wait until the total memory usage reaches twice the previous amount before starting a new cycle.

The garbage collector step multiplier controls the rate at which the collector operates relative to the memory allocation rate. 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, otherwise the collector will work too slowly to ever finish a cycle. The default value is 200, which means the collector works at a "twice" speed of memory allocation.

If you set the step multiplier to a very large number (10% larger than the number of bytes your program might use), the collector behaves like a stop-the-world collector. Then if you set the pause rate to 200, the collector behaves like previous Lua versions: every time Lua's memory usage doubles, a full collection is performed.

Garbage Collector Functions

Lua provides the following functionscollectgarbage ([opt [, arg]])to control automatic memory management:

  • collectgarbage("collect"): Performs a full garbage collection cycle. Through the opt parameter it provides a set of different functions:

  • collectgarbage("count"): Returns the total memory used by Lua in K bytes. This value has a fractional part, so simply multiply by 1024 to get the exact number of bytes used by Lua (unless overflow).

  • collectgarbage("restart"): Restarts the automatic operation of the garbage collector.

  • collectgarbage("setpause"): Sets arg as the collector's pause rate. Returns the previous value of the pause rate.

  • collectgarbage("setstepmul"): Returns the previous value of the step multiplier.

  • collectgarbage("step"): Runs the garbage collector in a single step. The "size" of the step is controlled by arg. When 0 is passed, the collector steps one (indivisible) step. When a non-zero value is passed, the collector performs work equivalent to Lua allocating that many (K bytes) of memory. If the collector finishes a cycle, it returns true.

  • collectgarbage("stop"): Stops the operation of the garbage collector. Until restart is called, the collector will only run when explicitly invoked.

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"))

Execute the above program, the output is as follows (note the change in memory usage):

20.9560546875
20.9853515625
0
19.4111328125
Other Extensions