From 7548c68c7cf5848946b24a0d32f95cce96f9296a Mon Sep 17 00:00:00 2001 From: luaneko Date: Tue, 24 Jun 2025 10:36:42 +1000 Subject: [PATCH] Add more documentation on why to use out-param --- crates/luaffi_impl/src/metatype.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/crates/luaffi_impl/src/metatype.rs b/crates/luaffi_impl/src/metatype.rs index 9a2e453..675307d 100644 --- a/crates/luaffi_impl/src/metatype.rs +++ b/crates/luaffi_impl/src/metatype.rs @@ -157,7 +157,18 @@ fn get_ffi_functions(imp: &mut ItemImpl) -> Result> { ReturnType::Type(_, ref ty) => (**ty).clone(), }; - // whether to use out-param for return values + // whether to use out-param for return values. + // + // out-param return convention isn't strictly necessary (luajit can handle them fine), + // but luajit doesn't jit compile aggregate returns yet, so this is more of a + // performance optimisation. https://luajit.org/ext_ffi_semantics.html#status + // + // right now this just heuristically looks for common primitive identifiers like `i32` + // and `usize` which has its limitations when it comes to type aliases (proc-macro can't + // see them), but the worst thing that can happen with a false detection is an + // unnecessarily boxed primitive that gets just unwrapped, or an aggregate suboptimally + // returned by-value. it should be correct for 99% of rust code that isn't doing + // anything weird. let ret_by_out = !is_primitive(&ret); funcs.push(FfiFunction {