LuaJIT FFI type specialization persists after module reload — how to safely invalidate stale ctype caches

Question

Stale FFI type specialization after reloading a LuaJIT module

I am working with LuaJIT's FFI and have run into a design question around type-specialization caching. When a module is reloaded via require (for example after redefining a C struct layout), the recorded type specialization appears to persist, so conversions may still follow the old struct layout. My understanding is that the cache key is derived from the FFI function pointer and type ID, which means a reused pointer after a library reload could silently keep the old specialization active.

The goal is a reliable way to guarantee that, after a struct redefinition or module reload, all subsequent FFI calls use the new type information rather than the cached specialization. I am also unsure whether garbage-collecting the old userdata invalidates anything, since collected objects may still trigger the cached conversion path.

Specific questions:

Is there a documented, supported mechanism to invalidate FFI type specializations, or is ffi.flushctype() the only option despite being described as an undocumented workaround?
Does the cache behavior differ between LuaJIT 2.0 and 2.1, and would jit.dump output confirm which specialization is active after a reload?
Is redefining a ctype with the same name between reloads itself undefined behavior that should simply be avoided?

Tasadduq Burney · Answer

AnswerThe only supported way to guarantee that FFI calls use the new type information after a module reload is to call ffi.flushctype() before any further FFI usage.Likely explanationLuaJIT’s FFI caches type specializations. The cache key is built from the FFI function pointer (or library handle) and the type definition string. When a Lua module is reloaded via require, the underlying C library may be reloaded or the cdef may be re‑executed, but the cache entry is not automatically removed because the key does not incorporate a reload event. Consequently, subsequent FFI conversions can continue to use the stale specialization that matches the old struct layout.Confirmed factsffi.flushctype() flushes the entire ctype cache and is the documented API for global invalidation; there is no per‑ctype or per‑library flush function in the public LuaJIT API.Redefining a ctype with the same name after a reload does not automatically invalidate the old specialization; the old entry remains active until the cache is flushed.LuaJIT 2.0 and 2.1 share the same cache semantics; no fundamental difference in invalidation behavior exists between the two releases.jit.dump can reveal the generated FFI IR, but interpreting it to determine whether a particular specialization is cached requires familiarity with the dump format and is not a simple staleness flag.Steps to safely reload a module with FFI typesReload the Lua module (e.g., local mod = require('mymod') after it has been changed).Immediately call ffi.flushctype() to clear all cached specializations.If needed, re‑execute the ffi.cdef definitions (this is usually done automatically when the module is loaded).Resume normal FFI usage; subsequent calls will now generate fresh specializations based on the updated type definitions.Verification (optional)After flushing, you can confirm that the new layout is used by checking ffi.sizeof or field offsets against the expected values.

LuaJIT FFI type specialization persists after module reload — how to safely invalidate stale ctype caches

Stale FFI type specialization after reloading a LuaJIT module

1 answer

Answer

Likely explanation

Confirmed facts

Steps to safely reload a module with FFI types

Verification (optional)

Your perspective belongs here.

0 question comments