filtergc

Filters objects in the garbage collector based on specified criteria.

Syntax

filtergc(type: "function" | "table", options: table, returnOne?: boolean) -> any? | {any}

Parameters

Parameter	Type	Description
`type`	`string`	The type of object to find ("function" or "table")
`options`	`table`	Filter options
`returnOne`	`boolean?`	Return the first match instead of an array (default: false)

Returns

Type	Description
`any?` or `table`	The first match when `returnOne` is true; otherwise an array of matches

Description

filtergc efficiently searches through garbage-collected objects with specific filter criteria. This is more performant than manually iterating through getgc().

Option	Type	Description
`Name`	`string`	Match function name
`Constants`	`table`	Match constants in function
`Upvalues`	`table`	Match upvalue values
`Hash`	`string`	Match the value returned by `getfunctionhash`
`IgnoreExecutor`	`boolean`	Exclude Volt-created functions (default: true)
`Environment`	`table`	Match the function's global environment
`StartLine`	`number`	Match the function's starting source line
`Source`	`string`	Match the function's short source name
`UpvalueCount`	`number`	Match the exact upvalue count
`ConstantCount`	`number`	Match the exact constant count

Option	Type	Description
`Keys`	`table`	Match table keys
`Values`	`table`	Match table values
`KeyValuePairs`	`table`	Match key-value pairs
`Metatable`	`table`	Match metatable

Example: Find Function by Name

local functions = filtergc("function", {
    Name = "targetFunction",
    IgnoreExecutor = false
})

for _, func in ipairs(functions) do
    print("Found:", func)
end

Example: Find Function by Constants

local functions = filtergc("function", {
    Constants = {"SomeUniqueString", "AnotherString"},
    IgnoreExecutor = false
})

Example: Find Table by Keys

local tables = filtergc("table", {
    Keys = {"Health", "MaxHealth", "Damage"}
})

for _, tbl in ipairs(tables) do
    print("Found table with game stats")
end

Example: Return the First Match

local function targetFunction()
    return "unique constant"
end

local match = filtergc("function", {
    Name = "targetFunction",
    IgnoreExecutor = false
}, true)

print(match == targetFunction) -- true

Notes

Function filters narrow the result: every supplied criterion must match
Constants, Upvalues, and Hash do not apply to C closures

getgc - Get all GC objects

filtergc

On this page