API:collectgarbage

This function is a generic interface to the garbage collector. It performs different functions according to its first argument.

Arguments

 * opt
 * string - The action to perform:
 * "stop": stops the garbage collector.
 * "restart": restarts the garbage collector.
 * "collect": performs a full garbage-collection cycle.
 * "count": returns the total memory in use by Lua (in Kbytes).
 * "step": performs a garbage-collection step. The step "size" is controlled by arg (larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value of arg. Returns true if the step finished a collection cycle.
 * "setpause": sets arg as the new value for the pause of the collector (see §2.10). Returns the previous value for pause.
 * "setstepmul": sets arg as the new value for the step multiplier of the collector (see §2.10). Returns the previous value for step.
 * arg
 * number - The value used in the action taken.

Returns

 * retval
 * number|boolean - The return value depends on the opt given.
 * "count" returns memory usage.
 * "step" returns true if the garbage collection step is completed.
 * "setpause" returns the previous value for the pause.
 * "setstepmul" returns the previous value for the multiplier.

Background
Lua performs automatic memory management. This means that you have to worry neither about allocating memory for new objects nor about freeing it when the objects are no longer needed. Lua manages memory automatically by running a garbage collector from time to time to collect all dead objects (that is, objects that are no longer accessible from Lua). All memory used by Lua is subject to automatic management: tables, userdata, functions, threads, strings, etc.

Lua implements an incremental mark-and-sweep collector. It uses two numbers to control its garbage-collection cycles: the garbage-collector pause and the garbage-collector step multiplier. Both use percentage points as units (so that a value of 100 means an internal value of 1).

The garbage-collector pause controls how long the collector waits before starting a new cycle. Larger values make the collector less aggressive. Values smaller than 100 mean the collector will not wait to start a new cycle. A value of 200 means that the collector waits for the total memory in use to double before starting a new cycle.

The step multiplier controls the relative speed of the collector relative to memory allocation. Larger values make the collector more aggressive but also increase the size of each incremental step. Values smaller than 100 make the collector too slow and can result in the collector never finishing a cycle. The default, 200, means that the collector runs at "twice" the speed of memory allocation.

Example
This returns 200, the previous value of pause: