Performance plan¶
Working plan for improving DFHack’s per-tick CPU budget. Based on
microarchitecture analysis (Intel VTune capture r120ue, Jan 2026)
and code review of the Lua integration. Not user-facing documentation.
Baseline findings¶
From r120ue (uarch exploration, whole-system sampling; ~24k
CPU_CLK_UNHALTED.THREAD samples):
DFHack-side code is ~21% of sampled CPU:
lua53.dll3322,dfhooks_dfhack.dll1750, plugins ~110.DFHack owns ~11% of
STALLS_L3_MISSand ~11% of DTLBWALK_ACTIVEsamples.Top lua53 stallers are data-layout problems, not dispatch:
luaH_getshortstr(hash-chain walk, 17 stall samples),luaD_precall,lua_geti,luaH_next(pairsiteration),lua_getmetatable,mainposition,luaC_checkfinalizer.Top CPU consumers are the C<->Lua transition layer:
luaV_execute759,luaD_precall260,index2addr115,luaV_finishget(metamethod resolution) 90,luaG_traceexec82 (the always-armedLUA_MASKCOUNTinterrupt hook),match/singlematch~88 (Lua pattern matching per frame), pluslua_tolstring/luaS_hashchurn.C++ side: MSVC
std::_Hash/std::_Treeinternals,std::stringconstruct/destroy churn,matchFocusString,Units::isActive— chained-node STL containers have the same miss problem as Lua’s tables.
Working hypothesis (operator model): DF’s own memory traffic evicts essentially all DFHack data from L3 between simulation ticks, so every tick starts cold and each pointer-chase (hash chain, GC list, metatable walk) pays full miss latency. Goal: make the per-tick cold walk sequential (prefetcher-trackable) rather than pointer-chasing, and reduce the number of misses by shortening dependent-load chains.
Overlay processing is believed to dominate the per-tick budget; this is consistent with the data but not yet proven — see the attribution step below.
Constraints and rejected directions¶
No PGO/LTO (deferred). DFHack does questionable things to DF’s vtables and binary; whole-program optimization changes codegen assumptions the interpose/binpatch machinery relies on. Would need a dedicated validation effort before it is safe to enable. Revisit only if cheaper items are exhausted.
Hugepages: optional-only.
VirtualAlloc(MEM_LARGE_PAGES)needsSeLockMemoryPrivilegeand often fails for normal users; Linux needs THP/hugetlbfs. Steam Deck (Linux) is a significant user population and we have no Linux profiling. Any allocator work must function with ordinary pages; hugepages may be an opt-in bonus path (madvise(MADV_HUGEPAGE)on Linux,MEM_LARGE_PAGESon Windows) with mandatory fallback.No LLVM-JIT Lua (Ravi etc.). The miss profile is in
ltable/lgc/ldo(data layout + transitions), notlvmdispatch. A JIT keeps identical object layout and would also have to reproduce ourlua_lockthreading patch,LUA_MASKCOUNTinterrupt hooks,lstate.hfield access, yieldable pcall, and debug-hook fidelity. Wrong tool for this problem.LuaJIT has the best-in-class data layout but is Lua 5.1 semantics; incompatible with our 5.3 corpus.
Action items¶
Ordered by leverage-per-effort. All are architecture-independent unless noted.
Measurement¶
Per-tick attribution.
perf_counters.update_lua_ms/update_plugin_ms(Core.cpp:1668-1682) already isolate Lua update time;script-manager.luaprints them. Baseline a real fort first.Callsite-stack attribution on VTune captures:
dd_callsiteparent links indicer.dballow rebuilding stacks and splitting Lua-side stalls between overlay widgets, timers, and plugin events. (Scratch query script:%TEMP%/vtune_agg.py; accepts adicer.dbpath for other captures.)Lua-level: run
profiler.luascoped to the update window, or a count hook aggregating by Proto, to identify which script functions dominate ticks.Object-level (if needed): we own the Lua source — log
luaC_newobj/luaM_realloc_(addr, type, size, phase) during a session, dump live objects by walkingallgcat a tick boundary, cross-reference VTune miss addresses.
Cheap knobs¶
Raise the interrupt-hook interval.
interrupt_initarmsLUA_MASKCOUNT, 256unconditionally (LuaTools.cpp:508) —luaG_traceexecshows 82 samples. Raising the count trades runaway-script interrupt latency for less hook dispatch. Tune and verify interrupt still fires acceptably.GC tuning on the core state (
lua_gcpause/stepmul) — never configured today; onlyscripts/dwarf-op.luacallscollectgarbage. One-line experiments; watch memory growth.Audit per-frame Lua string work:
match/singlematchsamples implystring.find/patterns in a per-frame path;luaS_hash/lua_tolstringchurn implies string building per frame. Fix at the call site once attribution identifies it.Audit
pairs()iteration over hash-part tables in hot loops (luaH_nextstalls): array-part iteration is contiguous and prefetchable; hash-part is not.
Structural: Lua heap layout¶
Custom
lua_Allocwith type/lifetime-segregated arenas.All GC objects funnel through
luaC_newobj(L, tt, sz)— one place to tag by type; other allocs vialuaM_realloc_by size class.Permanent bump region for everything allocated during
Lua::Open+require dfhack+ script load (protos, interned strings, metatables, fieldtables, module tables) — init order approximates tick access order; GC’sallgcwalk becomes quasi-sequential. Phase flag can live inlua_extra_state(already used bydfhack_llimits.h).Separate churn region for post-init garbage.
Only 3 state-creation sites:
Core.cpp:1394,LuaTools.cpp:1793,LuaTools.test.cpp.Portable: works with plain VirtualAlloc/mmap; hugepages are a strictly optional overlay on top (see constraints).
Caveat:
lua_Allocmust implement realloc semantics (alloc+copy+free is fine); Lua GC never moves objects (push_adhoc_pointerrelies on this already).
Software prefetch at tick entry in
Lua::Core::onUpdate(LuaTools.cpp:2073): prefetchG(State), registry, and each due coroutine’sstack/cibeforelua_resume— portable via_mm_prefetch/__builtin_prefetch. Cheap; converts serial cold misses into overlapped ones.
Binding layer (the userdata proxy question)¶
Kill the double lookup in the field path.
meta_struct_index→find_field→lookup_field(LuaTypes.cpp:422-454) probes a Lua field-table and walks the enum metatable per access. Short strings are interned, soTString*pointer equality = name equality: a small direct-mapped cache keyed(fieldtable, TString*), or a per-type dense index assigned to each field name at metatable build time, collapses this to one load. Highest-confidence fix — hitsluaV_finishget/luaH_getshortstr/lua_getmetatablesimultaneously.Reduce per-access userdata churn.
push_object_refallocates a fresh userdata (+object_ref_header: tag_ptr, tag_identity, tag_attr, field_info) for every nested struct/container access —unit.pos.xgarbage-per-hop. Options, in increasing scope:arena allocation makes the churn cheap and local (item 9);
memoize refs via weak-valued cache keyed
(ptr, identity)— adds a hash probe, only worth it for expensive chains;bulk getters for hot access patterns (e.g. one call returning
x,y,zforpos) — semantic addition, avoids N allocations and N metamethod hops per vector;pack/shrink
object_ref_header— review which of its four pointers are needed on the common path; union-tag fields could live in a side table populated only for unions.
Keep the proxy model; make the ref cheaper. A full move away from userdata proxies isn’t practical (scripts rely on reference identity,
__indexpolymorphism,_field), but the identity-layer work in PR #5959 already removes one virtual dispatch from every primitive field read — that direction (moreif constexprstatic knowledge in the access path) is the right way to slim the proxy rather than replacing it.
C++-side containers¶
MSVC STL
unordered_map/unordered_set/mapon per-tick paths are chained-node structures with the same miss signature (_Fnv1a_append_value,_Hashloops appear in the stall list — e.g. insideUnits::isActive). Swap hot-path instances for flat maps / sorted vectors / precomputed indices.matchFocusStringallocatesstd::stringper call per frame — make it allocation-free (string_view, cached split).
Overlay / script layer¶
Once attribution lands (item 2/3): batch the overlay render path.
dfhack.penarraybulk tile ops already exist (LuaApi.cpp:997+). Per-cellPenwrites through metamethods per frame should move to bulk APIs or C++ rendering. If overlay is indeed the budget owner, this is likely the largest single user-visible win.
Verification methodology¶
For each change: measure update_lua_ms / update_plugin_ms
before/after on the same save; VTune Hotspots (not uarch exploration
— less noise) filtered to the sim thread; compare
MEMORY_ACTIVITY.STALLS_L3_MISS and MEM_LOAD_RETIRED.L3_MISS
inside lua53.dll/dfhooks_dfhack.dll. Each item above is
independently revertable.
Lua 5.4/5.5 upgrade assessment¶
The __ipairs blocker is narrower than it appears:
__ipairsis registered on all generated metatables (LuaTypes.cppSetPairsMethodx4;LuaWrapper.cppwtype_ipairs/complex_enum_ipairs). It exists because some proxy__indeximplementations never return nil for integer keys (enum attrs — DFHack/dfhack#1860), so plainipairswould not terminate.Under 5.4,
__ipairsis ignored entirely;ipairsindexest[i]until nil. Migration path: make every proxy__indexbounded for integer keys (containers already bound by item_count; enum attrs need an explicit bound — the enum count is known), then audit direct__ipairsusers (one script:scripts/test/fix/stuck-written-materials.lua; plustest/structures/enum_attrs.luasemantics).Real benefits for our profile: generational GC (young-gen collections over small dense sets directly attack the cold-sweep problem), ~10-25% faster VM,
lua_newuserdatauvuservalues (could foldobject_ref_headerinto a uservalue — see item 12d).Costs: semantic audit of ~500 scripts (integer/string coercion strictness,
math.randomalgorithm change breaks seeded determinism,lua_resumesignature change — we call it directly inLuaTools.cpp:880), bytecode format change (dumper.luastring.dumproundtrips). Moderate project.Recommendation: pursue items 9-12 first (larger wins per risk); revisit 5.4 as a GC-locality lever afterward. 5.5 is not yet a stable target; track it but don’t plan against it.
PR #5959 review (performance notes)¶
Net-positive for the hot path, with watch-items:
Win:
type_identity_for<T>::lua_read/lua_writeinline*(T*)ptrviaif constexpr— removes the second virtual call (oldinteger_identity_base::lua_read→ virtualread()) on every primitive field access. This is exactly theread_field/write_fieldhot path.Watch:
mapped<T>containers (std::map/unordered_map) now get identities with O(n)item_pointeriteration. Any struct field of map type newly exposed to Lua (check thelibrary/xmlsubmodule bump) becomes O(n^2) underipairs-style iteration — audit which types gain this.Watch:
container_storage<C<E*,A...>>generalizes the “vector<T*> == vector<void*>” layout assumption to any random-access pointer container (deque etc.). The assumption holds for same-width pointer instantiations in practice, but the blast radius widened.Note: removing
BUILD_DFHACK_LIBguards lets plugins instantiatecontainer_impl/type_identity_forlocally, creating non-canonical identity objects —is_type_compatiblecompares identity pointers, so a plugin-side local instance of an existing identity could yield false type mismatches. Document that identities must come fromidentity_traits/canonical sources only.field_error/get_object_internalnewlyDFHACK_EXPORT— required by header-side template instantiation; fine.LuaTools.hnow includesDataIdentity.h— heavier include in every consumer TU; compile-time only.boolmoved toNUMBER_IDENTITY_TRAITSwith correctisInteger()==falseand bool-specific read/write — semantics preserved (type()stillIDTYPE_PRIMITIVE, name “bool”).c_string→primitive_identity_basepreserves “raw pointer string” write error and push-string read semantics.push_adhoc_pointerretains the “GC never moves objects” hack — reinforces that any allocator work must stay non-moving.
Suggested order¶
Callsite attribution (who owns the Lua stalls).
Cheap knobs: hook count, GC tuning, string-work audit.
Field-lookup inline cache (item 11).
Arena allocator (items 9-10).
C++ container swaps +
matchFocusString(items 14-15).Overlay batching per attribution (item 16).
Lua 5.4 evaluation (generational GC) once 1-6 land.