# `lune-std-ffi` ## Tests & Benchmarks See [tests/ffi](../../tests/ffi/README.md) ## TODO - [CString](./src/c/string_info.rs) - Add buffer as owned data support - Add math operation for numeric types > Provide related methods: `CTypeInfo:add(target, from1, from2, ...)` and `:sub` `:mul` `:div` `:mod` `:pow` `:max` `:min` `:gt` `:lt` > Luau cannot handle f64, i64 or i128, so we should provide math operation for it - Add bit operation for box/ref > Luau only supports 32bit bit operations - Add wchar and wstring support > For windows API support - Add varargs support - Array argument in cfn - [More box/ref methods](./src/data/helper.rs) - writeString - readString - writeBase64 - readBase64 ## Code structure ### /c Define C-ABI type information and provide conversion and casting **Structs:** C ABI type informations - [**Struct `CArrInfo`:**](./src/c/arr_info.rs) Represents C Array type - [**Struct `CPtrInfo`:**](./src/c/ptr_info.rs) Represents C Pointer type - [**Struct `CFnInfo`:**](./src/c/fn_info.rs) Represents C Function signature > provide `CallableData` and `ClosureData` creator - [**Struct `CStructInfo`:**](./src/c/struct_info.rs) Represents C Struct type - [**Struct `CTypeInfo`:**](./src/c/type_info.rs) Represents C type, extended in `/c/types`

Mod helper.rs: C ABI type helper

- **Function `get_conv`, `get_conv_list`:** get `FfiConvert` from userdata (CStruct, CArr, CPtr, CTypes) - **Function `get_middle_type`, `get_middle_type_list`:** get **`libffi::middle::Type`:** from userdata (CFn, CStruct, CArr, CPtr, CTypes) - **Function `get_size`:** get size from userdata - **Function `has_void`:** check table has void type - **Function `stringify`:** stringify any type userdata - **Function `get_name`:** get type name from ctype userdata, used for pretty-print - **Function `is_ctype`:** check userdata is ctype - **Mod `method_provider`:** provide common userdata method implements

#### /c/types Export fixed-size source time known types and non-fixed compile time known types mod.rs implememts type-casting for all CTypes

Mod ctype_helper: CTypeInfo helper

- **Function `get_conv`:** get `FfiConvert` from ctype userdata, used for struct and array conversion - **Function `get_middle_type`:** get **`libffi::middle::Type`:** from ctype userdata - **Function `get_size`:** get size from ctype userdata - **Function `get_name`:** get type name from ctype userdata, used for pretty-print - **Function `is_ctype`:** check userdata is ctype

--- ### /data **Structs:** Provide memory userdata - [**Struct `BoxData`:**](./src/data/box_data/mod.rs) A heap allocated memory with user definable lifetime - [**Struct `LibData`:**](./src/data/lib_data.rs) A dynamic opened library - [**Struct `RefData`:**](./src/data/ref_data/mod.rs) A reference that can be used for receiving return data from external function or pass pointer arguments **Structs:** Provide function(pointer) userdata - [**Struct `CallableData`:**](./src/data/callable_data.rs) A callable function, which can be created from function pointer - [**Struct `ClosureData`:**](./src/data/closure_data.rs) A closure pointer, which can be created from lua function and can be used for callback --- ### /ffi **Traits:** Provide ABI shared common type information trait - **Trait `FfiSize`** - **Trait `FfiSignedness`**

• Trait FfiConvert: Provide methods for read LuaValue from FfiData or write LuaValue into FfiData

  - **Method `value_into_data`:** set data with lua value - **Method `value_from_data`:** get lua value from data - **Method `copy_data`:** copy sized data into another data - **Method `stringify_data`:** stringify data with specific type

**Structs:** Provide call information - **Struct `FfiArg`:** Used for argument boundary checking and callback argument ref flag - **Struct `FfiResult`:** Used for result boundary checking

Trait FfiData: Provide common data handle, including methods below

- **Method `check_inner_boundary`:** check boundary with offset and size - **Method `get_inner_pointer`:** returns raw pointer `*mut ()` - **Method `is_writable`** - **Method `is_readable`** - **Method `copy_from`** copy data from another data

> Note: `GetFfiData` trait in `data/mod.rs` provides `(LuaValue | LuaAnyUserData).get_data_handle() -> FfiData` method **Mods:** Provide common helper functions - [**Mod `association.rs`:**](./src/ffi/association.rs) GC utility, used for inner, ret and arg type holding in subtype - [**Mod `bit_mask.rs`:**](./src/ffi/bit_mask.rs) u8 bitfield helper - [**Mod `cast.rs`:**](./src/ffi/cast.rs) num cast library wrapper - **Function `num_cast(from: FfiData, from: FfiData)`:** Cast number type value inno another number type

• Mod libffi_helper.rs: libffi library helper

  - **Const `FFI_STATUS_NAMES`:** Stringify `ffi_status` - **Function `get_ensured_size`:** Returns ensured size of `ffi_type` - **Const `SIZE_OF_POINTER`:** Platform specific pointer size (Compile time known) - **Function `ffi_status_assert`:** Convert `ffi_status` to `LuaResult<()>`