Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -517,3 +517,59 @@ A: Enable `CompileConfig::debug_mode` to inspect logs and C code; use `GetLastRe

### Q: Is multithreading supported?
A: Each `State` is currently thread-local; in multithreaded environments, create an independent `State` per thread.

### GCC JIT filesystem cache

GCC JIT caches compiled shared libraries by default. `StateConfig::gcc_config`
has `enable_cache` (default `true`) and `cache_directory`. An empty directory uses
`<system-temp>/fakelua/cache/uid-<uid>` on POSIX (typically
`/tmp/fakelua/cache/uid-1000` on Linux), or `<system-temp>/fakelua/cache` on Windows.
The system temp directory is selected by the same helper as transient JIT files,
including platform temp environment settings; macOS/Windows may use a per-user
temp directory rather than `/tmp`. An explicit `cache_directory` overrides this.
POSIX cache directories must belong to the current user and have mode 0700;
untrusted writable/foreign-owned parent directories are rejected. Cache failures
fall back to normal compilation.

The key includes the complete generated C (including Lua debug path), optimization
mode, compiler, relevant compiler environment, and a source/build ABI fingerprint.
System header and compiler/backend/assembler/linker/support-library contents are
validated before reuse. Custom GCC include/library configurations, compiler search-path environment
overrides, wrapper scripts and coverage builds bypass caching. TCC remains in-memory; INTERP is unchanged. Compiler wrappers
with hidden inputs must disable caching or use a separate cache directory when
those inputs change. Do not modify a toolchain concurrently with compilation.

`cache_max_entries` defaults to **256 complete entries per cache directory**.
Set it to `0` for unlimited entries, or set `enable_cache=false` to disable caching.
Lookup/publication trims excess entries in publication order (FIFO, not LRU): hits
do not refresh an entry's age. A directory-wide thread/process lock coordinates
restore, publication and eviction; actual C compilation stays outside that lock.
Use the same limit for clients sharing a directory; each operation applies its
client's configured limit. Deletion failures are best effort and can temporarily
leave the directory above the limit; a later operation tries again. This is an
entry-count limit, not a byte limit; partial/staging and unrelated files do not count.

Striped key thread/process locks and atomic directory publication prevent partial hits;
corrupt/stale entries are rebuilt. Every load gets a private image, then binds State,
heap slots and interned string IDs once to generated C statics. This preserves
cross-module string identity, independent globals/closures and allocation lifetimes;
no runtime cache lookup is added. Hits skip C compilation/linking, not the Lua frontend; a cheap compiler-version
query still verifies the selected toolchain.

Cache directories contain executable code: keep them private and on a local
filesystem supporting advisory locks and atomic rename. System temp cleanup is
OS/admin-policy dependent, not guaranteed. Removing entries or the cache subtree
causes cache misses/recompilation, not loss of loaded modules (their images are
private copies outside the cache). If a cleaner unlinks a live POSIX lock inode,
advisory exclusion alone no longer holds: detached locks are detected where possible,
writer-private staging, atomic publication and image validation keep cleanup races
best effort rather than a source of partial executable images. Redundant compilation
and temporary cap overshoot are possible during external cleanup. Lock metadata
is bounded to 256 key stripes plus one index lock; eviction never unlinks locks.
For deterministic manual cleanup, stop cache users before removing its directory.
Interrupted writers may leave writer-private `.tmp.*` directories; these do not count
toward the limit and can be removed with the cache when it is idle. Old-format
`.tmp` staging for a key is cleared on its next publication. See
[the release benchmark harness](tools/benchmark_jit_cache.cpp) for measurement commands.

Cache synchronization does not make a State itself safe for concurrent use.
39 changes: 39 additions & 0 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -512,3 +512,42 @@ A: 启用 `CompileConfig::debug_mode` 查看日志和 C 代码;使用 `GetLast

### Q: 支持多线程吗?
A: 每个 `State` 当前为线程本地对象,多线程环境中应为每个线程创建独立的 `State`。

### GCC JIT 文件系统缓存

GCC JIT 默认缓存编译后的动态库。`StateConfig::gcc_config.enable_cache` 可关闭;
`cache_directory` 为空时使用原有临时目录下的 `cache` 子目录:POSIX 为
`<系统临时目录>/fakelua/cache/uid-<uid>`(Linux 通常如 `/tmp/fakelua/cache/uid-1000`),
Windows 为 `<系统临时目录>/fakelua/cache`。与临时 JIT 文件复用同一目录选择逻辑,
遵循平台临时目录环境设置;macOS/Windows 可能使用用户级临时目录而非 `/tmp`。
显式设置 `cache_directory` 仍可覆盖默认值。POSIX 下目录必须属于当前用户且权限为 0700,
不可信的可写/其他用户所有的父目录会被拒绝。缓存不可用时自动回退正常编译。

缓存键覆盖完整生成 C(含 Lua 调试路径)、优化模式、编译器、相关编译环境和源码/构建 ABI
指纹;命中时校验系统头文件、编译后端、汇编器、链接器及编译支持库内容。
自定义 GCC 头文件/库配置、编译搜索路径环境覆盖、包装脚本及覆盖率构建不使用缓存;TCC 仍在内存编译,INTERP 不变。
有隐藏输入的编译器包装脚本需要关闭缓存,或在输入变化时换用新缓存目录。
不要在编译期间同时修改工具链。

`cache_max_entries` 默认限制每个目录 **256 个完整缓存条目**;`0` 表示不限数量,
完全禁用仍用 `enable_cache=false`。查询和发布时按生成/发布顺序淘汰最老条目(FIFO,
不是 LRU,命中不刷新顺序)。目录级线程/进程锁协调读取、发布和淘汰,实际 C 编译不持有
目录锁。共享目录的客户端应使用相同上限,每次操作按当前客户端配置执行;删除失败时尽力回收,
可能暂时超限,下次操作再尝试。这是条目数限制,不是字节上限,半成品、暂存目录和无关文件不计入。

分条带的键级线程/进程锁及原子发布保证正常并发不会读取半成品,损坏或过期条目自动重建。每次加载均使用独立动态库副本,
一次性绑定 State、堆槽和驻留字符串 ID 到生成 C 的静态变量,避免不同 State 的可变静态
数据互串,保持跨模块字符串身份及生命周期;执行热路径不查询文件缓存。
命中跳过 C 的实际编译/链接,但仍进行 Lua 前端处理及轻量的编译器版本校验。

缓存中是可执行代码,请使用私有本地目录(支持文件锁及原子重命名)。系统是否清理临时目录
取决于操作系统/管理员策略,并不保证清理。条目或缓存子树被删除会变成未命中/重新编译,
不会影响已加载模块(实际加载的是缓存目录外的独立副本)。POSIX 活动锁文件若被外部清理器
删除,不能单靠文件锁保证互斥;实现会尽量识别脱离路径的锁,并通过每个写入者独立暂存、原子
发布和产物校验回退,避免执行半成品。外部清理期间可能重复编译或暂时超限。
锁元数据最多为 256 个键条带锁及 1 个目录锁,淘汰永不删除锁文件。
手动清理最好先停止缓存使用者。进程中断可能遗留 `.tmp.*` 独立暂存目录,不计入上限,
可在缓存闲置时一起清理;旧格式 `.tmp` 由该键下一次发布回收。
可复现的 Release 测量见[基准代码](tools/benchmark_jit_cache.cpp)。

缓存的并发保护不改变 State 本身的线程安全约束。
45 changes: 45 additions & 0 deletions cmake/JitCacheIdentity.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# A content/build fingerprint for the host/JIT ABI, generated at build time.
# Reconfigure after source edits, including dirty/uncommitted changes; a version
# number or git revision alone would silently reuse stale machine code.
get_filename_component(_fl_jit_root "${CMAKE_CURRENT_LIST_DIR}/.." REALPATH)
file(GLOB_RECURSE _fl_jit_inputs
"${_fl_jit_root}/src/*.hh" "${_fl_jit_root}/src/*.hpp" "${_fl_jit_root}/src/*.h" "${_fl_jit_root}/src/*.cpp"
"${_fl_jit_root}/src/*.y" "${_fl_jit_root}/src/*.l"
"${_fl_jit_root}/include/*.h" "${_fl_jit_root}/cmake/*.cmake")
list(APPEND _fl_jit_inputs "${_fl_jit_root}/CMakeLists.txt" "${_fl_jit_root}/src/CMakeLists.txt")
list(SORT _fl_jit_inputs)
set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${_fl_jit_inputs})
set(_fl_jit_identity "${CMAKE_SYSTEM_NAME};${CMAKE_SYSTEM_PROCESSOR};${CMAKE_SIZEOF_VOID_P};${CMAKE_CXX_COMPILER_ID};${CMAKE_CXX_COMPILER_VERSION};${CMAKE_BUILD_TYPE}")
foreach(_input IN LISTS _fl_jit_inputs)
file(SHA256 "${_input}" _hash)
string(APPEND _fl_jit_identity ";${_input}:${_hash}")
endforeach()
foreach(_flag CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE
CMAKE_CXX_FLAGS_RELWITHDEBINFO CMAKE_CXX_FLAGS_MINSIZEREL
CMAKE_CXX_COMPILER_TARGET CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN CMAKE_CXX_STANDARD
CMAKE_SHARED_LINKER_FLAGS CMAKE_OSX_ARCHITECTURES CMAKE_OSX_SYSROOT
CMAKE_OSX_DEPLOYMENT_TARGET USE_ASAN USE_COV FAKELUA_NATIVE_OBJECT_DEBUG_HASH)
string(APPEND _fl_jit_identity ";${_flag}=${${_flag}}")
endforeach()
# Include custom configuration flags as well as the standard configurations.
get_cmake_property(_fl_jit_variables VARIABLES)
foreach(_flag IN LISTS _fl_jit_variables)
if(_flag MATCHES "^CMAKE_(CXX_FLAGS|SHARED_LINKER_FLAGS)(_|$)")
string(APPEND _fl_jit_identity ";${_flag}=${${_flag}}")
endif()
endforeach()
foreach(_property COMPILE_OPTIONS COMPILE_DEFINITIONS COMPILE_FEATURES CXX_STANDARD CXX_EXTENSIONS
POSITION_INDEPENDENT_CODE INCLUDE_DIRECTORIES LINK_OPTIONS LINK_LIBRARIES)
get_target_property(_value fakelua ${_property})
string(APPEND _fl_jit_identity ";${_property}=${_value}")
endforeach()
file(SHA256 "${CMAKE_CXX_COMPILER}" _fl_host_compiler_hash)
string(SHA256 _fl_jit_hash "${_fl_jit_identity};${_fl_host_compiler_hash}")
file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/jit_build_identity.h.tmp" "#pragma once\n#define FAKELUA_JIT_BUILD_ID \"${_fl_jit_hash}\"\n")
configure_file("${CMAKE_CURRENT_BINARY_DIR}/jit_build_identity.h.tmp" "${CMAKE_CURRENT_BINARY_DIR}/jit_build_identity.h" COPYONLY)
target_include_directories(fakelua PRIVATE "${CMAKE_CURRENT_BINARY_DIR}")
# CMAKE_BUILD_TYPE is empty for multi-config generators. A per-source definition
# records the actual configuration without a shared header that concurrent
# Debug/Release builds could overwrite.
set_property(SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/jit/gcc_cache.cpp" APPEND PROPERTY
COMPILE_DEFINITIONS "FAKELUA_JIT_BUILD_CONFIGURATION=\"$<CONFIG>\"")
5 changes: 3 additions & 2 deletions cmd/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ constexpr const char *kFiniEntry = "main.fini";

std::atomic<bool> g_exit_requested{false};
std::atomic<int> g_exit_code{0};

bool ExitRequested() {
return g_exit_requested.load(std::memory_order_acquire);
}
Expand Down Expand Up @@ -117,7 +118,7 @@ std::vector<std::string> CollectLuaFiles(const std::string &path) {
}
return files;
}
return { path };
return {path};
}

[[noreturn]] void ReportMissingEntry(const char *name) {
Expand Down Expand Up @@ -199,7 +200,7 @@ int RunLifecycle(State *s, JITType jit) {
return exit_code;
}

} // namespace
}// namespace

int main(int argc, char **argv) {
gflags::SetUsageMessage("usage: ./flua <file.lua | dir/> [options]\n"
Expand Down
23 changes: 18 additions & 5 deletions include/fakelua.h
Original file line number Diff line number Diff line change
Expand Up @@ -302,8 +302,14 @@ enum JITType {
struct JitTypeSpan {
JITType data[JIT_MAX]{};
int size = 0;
const JITType *begin() const { return data; }
const JITType *end() const { return data + size; }

const JITType *begin() const {
return data;
}

const JITType *end() const {
return data + size;
}
};

inline const char *JitTypeName(JITType t) {
Expand Down Expand Up @@ -400,6 +406,14 @@ struct StateGCCConfig {
std::vector<std::string> include_paths;
std::vector<std::string> library_paths;
std::vector<std::string> libraries;
// Best-effort persistent shared-library cache. Empty directory uses the
// system-temp/fakelua/cache (POSIX: /uid-<uid>), not a home cache.
// System cleanup is policy-dependent. Custom include/library configs bypass it.
bool enable_cache = true;
std::string cache_directory;
// Maximum complete entries per directory, evicted in publication order (FIFO).
// Zero means unlimited; enable_cache=false disables caching entirely.
size_t cache_max_entries = 256;
};

struct StateConfig {
Expand Down Expand Up @@ -968,9 +982,8 @@ void RegisterNativeVarFunction(State *s, const std::string &name, int arg_count,
// 可变参数时,用上面的 5 参回调形式自己读参数(GetNativeIntArg / GetNativeStringArg)。
template<typename Ret, typename... Args>
void RegisterNativeFunction(State *s, const std::string &name, bool is_vararg, std::function<Ret(State *, Args...)> func) {
static_assert(!std::is_function_v<Ret>,
"RegisterNativeFunction: Ret is a function type, so the signature was passed as a template argument. "
"Write std::function<Ret(State*, Args...)> instead - see the example above RegisterNativeFunction.");
static_assert(!std::is_function_v<Ret>, "RegisterNativeFunction: Ret is a function type, so the signature was passed as a template argument. "
"Write std::function<Ret(State*, Args...)> instead - see the example above RegisterNativeFunction.");
constexpr int arg_count = static_cast<int>(sizeof...(Args));
RegisterNativeFunction(s, name, arg_count, is_vararg, [func](State *state, CVar *args, int n) -> CVar {
auto unpack_helper = [state, args, n]<std::size_t... I>(std::index_sequence<I...>) {
Expand Down
2 changes: 2 additions & 0 deletions src/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -609,3 +609,5 @@ install(TARGETS fakelua
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

include(${CMAKE_CURRENT_SOURCE_DIR}/../cmake/JitCacheIdentity.cmake)
Loading
Loading