lune/crates/lune-std-ffi/README.md

lune-std-ffi

Tests & Benchmarks

See tests/ffi

TODO

• CString
• 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
  • writeString
  • readString
  • writeBase64
  • readBase64

Code structure

/c

Define C-ABI type information and provide conversion and casting

Structs: C ABI type informations

• Struct CArrInfo: Represents C Array type
• Struct CPtrInfo: Represents C Pointer type
• Struct CFnInfo: Represents C Function signature

  provide CallableData and ClosureData creator

• Struct CStructInfo: Represents C Struct type
• Struct CTypeInfo<T>: 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: A heap allocated memory with user definable lifetime
• Struct LibData: A dynamic opened library
• Struct RefData: A reference that can be used for receiving return data from external function or pass pointer arguments

Structs: Provide function(pointer) userdata

• Struct CallableData: A callable function, which can be created from function pointer
• Struct ClosureData: 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: GC utility, used for inner, ret and arg type holding in subtype
• Mod bit_mask.rs: u8 bitfield helper
• Mod cast.rs: num cast library wrapper
  • Function num_cast<From, Into>(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<()>