Auto Free GC

Auto-Free GC

CoreTrace auto-free has two layers:

• compile-time feature enable (--ct-autofree)
• optional conservative runtime scanning (CT_AUTOFREE_SCAN*)

1) Compile-time enable

Auto-free is disabled by default in compile-time runtime config. Enable it when building instrumented binaries:

./build/cc --instrument --ct-alloc --ct-autofree main.c -o app

2) Runtime scan enable

Without scan variables, auto-free only uses compile-time reachability decisions. To enable conservative root scanning:

CT_AUTOFREE_SCAN=1 ./app

To enable periodic GC thread:

CT_AUTOFREE_SCAN=1 CT_AUTOFREE_SCAN_START=1 ./app

Scan variables

Variable	Default	Meaning
CT_AUTOFREE_SCAN	0	Enable conservative scan system
CT_AUTOFREE_SCAN_START	0	Start background periodic scan thread
CT_AUTOFREE_SCAN_STACK	1	Scan stack roots
CT_AUTOFREE_SCAN_REGS	1	Scan register roots
CT_AUTOFREE_SCAN_GLOBALS	1	Scan globals (__DATA/image data)
CT_AUTOFREE_SCAN_INTERIOR	1	Count interior pointers as roots
CT_AUTOFREE_SCAN_PTR	1	Run per-pointer check before auto-free
CT_DEBUG_AUTOFREE_SCAN	0	Debug level (0/1/2)

Timing controls

Period precedence:

1. CT_AUTOFREE_SCAN_PERIOD_NS
2. CT_AUTOFREE_SCAN_PERIOD_US
3. CT_AUTOFREE_SCAN_PERIOD_MS
4. fallback 1000ms when START=1 and no period is set

Budget precedence:

1. CT_AUTOFREE_SCAN_BUDGET_NS
2. CT_AUTOFREE_SCAN_BUDGET_US
3. CT_AUTOFREE_SCAN_BUDGET_MS (default 5.0)

Compatibility interval:

• CT_AUTOFREE_SCAN_INTERVAL_MS sets a minimum interval for per-pointer scans.

Example profiles

Safer debug profile

CT_AUTOFREE_SCAN=1 \
CT_AUTOFREE_SCAN_START=1 \
CT_AUTOFREE_SCAN_PTR=1 \
CT_AUTOFREE_SCAN_GLOBALS=1 \
CT_AUTOFREE_SCAN_PERIOD_MS=1000 \
CT_AUTOFREE_SCAN_BUDGET_MS=20 \
./app

Lower overhead profile

CT_AUTOFREE_SCAN=1 \
CT_AUTOFREE_SCAN_START=1 \
CT_AUTOFREE_SCAN_GLOBALS=0 \
CT_AUTOFREE_SCAN_PTR=0 \
CT_AUTOFREE_SCAN_PERIOD_MS=5000 \
CT_AUTOFREE_SCAN_BUDGET_MS=5 \
./app

Practical caveats

• Conservative roots can keep dead allocations alive (false negatives).
• If budget is exceeded, scan avoids freeing in that pass for safety.
• Pointer scanning and global scanning can be expensive on large processes.