gc
Lua manages memory automatically by running a garbage collector 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: strings, tables, userdata, functions, threads, internal structures, etc.
Functions
gc.collect | Performs a full garbage-collection cycle. |
gc.getMemory | The value has a fractional part, so that it multiplied by 1024 gives the exact number of bytes in use by Lua (except fo… |
gc.getTableRules | Returns info about the garbage collector rules for the given table. |
gc.isRunning | Returns a boolean that tells whether the collector is running (i.e., not stopped). |
gc.restart | Restarts automatic execution of the garbage collector. |
gc.setPause | The garbage-collector pause controls how long the collector waits before starting a new cycle. |
gc.setStep | The garbage-collector step multiplier controls the relative speed of the collector relative to memory allocation. |
gc.setStepMultiplier | If you set the step multiplier to a very large number (larger than 10% of the maximum number of bytes that the program… |
gc.setTableRules | Sets the garbage-collector rules for the given table. |
gc.setup | Registers the table for automatic cleanup: when an object of the given type is destroyed, its key is removed from the t… |
gc.stop | Stops automatic execution of the garbage collector. |
gc.unsetup | Stops the automatic cleanup of the table for the given type. |
#gc.collect
function gc.collect()Performs a full garbage-collection cycle.
#gc.getMemory
function gc.getMemory(): numberThe value has a fractional part, so that it multiplied by 1024 gives the exact number of bytes in use by Lua (except for overflows).
| Type | Name | Description |
|---|---|---|
number | count | The total memory in use by Lua in Kbytes. |
#gc.getTableRules
function gc.getTableRules(tbl: table): boolean, booleanReturns info about the garbage collector rules for the given table.
| Name | Type | Description |
|---|---|---|
tbl | table | The table to query. |
| Type | Name | Description |
|---|---|---|
boolean | key_mode | true if key c ollection is allowed, false otherwise. |
boolean | value_mode | true if value collection is allowed, false otherwise. |
#gc.isRunning
function gc.isRunning(): booleanReturns a boolean that tells whether the collector is running (i.e., not stopped).
| Type | Name | Description |
|---|---|---|
boolean | is_running | Returns true if the collector is running, false otherwise. |
#gc.restart
function gc.restart()Restarts automatic execution of the garbage collector.
#gc.setPause
function gc.setPause(value: number): numberThe 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.
| Name | Type | Description |
|---|---|---|
value | number | The new value for the pause of the collector. |
| Type | Name | Description |
|---|---|---|
number | pause_value | The previous value for pause. |
#gc.setStep
function gc.setStep(size: number): booleanThe garbage-collector 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.
You should not use values smaller than 100, because they make the collector too slow and can result in the collector never finishing a cycle. The default is 200, which means that the collector runs at "twice" the speed of memory allocation.
| Name | Type | Description |
|---|---|---|
size | number | With a zero value, the collector will perform one basic (indivisible) step. For non-zero values, the collector will perform as if that amount of memory (in KBytes) had been allocated by Lua. |
| Type | Name | Description |
|---|---|---|
boolean | finished | Returns true if the step finished a collection cycle. |
#gc.setStepMultiplier
function gc.setStepMultiplier(value: number): numberIf you set the step multiplier to a very large number (larger than 10% of the maximum number of bytes that the program may use), the collector behaves like a stop-the-world collector. If you then set the pause to 200, the collector behaves as in old Lua versions, doing a complete collection every time Lua doubles its memory usage.
| Name | Type | Description |
|---|---|---|
value | number | The new value for the step multiplier of the collector. |
| Type | Name | Description |
|---|---|---|
number | previous_value | The previous value for step. |
#gc.setTableRules
function gc.setTableRules(tbl: table, key?: boolean, value?: boolean)Sets the garbage-collector rules for the given table.
| Name | Type | Description |
|---|---|---|
tbl | table | The table to set the rules for. |
keyoptional | boolean | true if key collection is allowed, false otherwise. |
valueoptional | boolean | true if value collection is allowed, false otherwise. |
#gc.setup
function gc.setup(tbl: table, type_name: gc.Type, instruction?: gc.Instruction)Registers the table for automatic cleanup: when an object of the given type is destroyed, its key is removed from the table with raw.set, bypassing __newindex.
Calling it again with the same table and type replaces the instruction, one table can be registered for several types.
NOTE: The registry does not keep the table alive, but LuaJIT weak tables are not ephemerons, so an
instructionthat capturestblas an upvalue keeps it alive forever.
NOTE: The
instructionis called during the entity removal and must not callgc.setupor raise errors, an error skips the cleanup of the remaining tables.
| Name | Type | Description |
|---|---|---|
tbl | table | The table to clean up. |
type_name | gc.Type | The type of objects used as keys in the table. |
instructionoptional | gc.Instruction | The function that maps the destroyed object to the key, by default the object itself is the key. |
#gc.stop
function gc.stop()Stops automatic execution of the garbage collector. The collector will run only when explicitly invoked, until a call to restart it.
#gc.unsetup
function gc.unsetup(tbl: table, type_name: gc.Type)Stops the automatic cleanup of the table for the given type.
| Name | Type | Description |
|---|---|---|
tbl | table | The table to stop cleaning up. |
type_name | gc.Type | The type the table was registered with. |