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

lune-std-ffi

Code structure

/c

Define C-ABI type information and provide conversion and casting

• Struct CArrInfo: Represents C Array type
• Struct CPtrInfo: Represents C Pointer type
• Struct CFnInfo: Represents C Function signature provide CallableData and ClosureData creation
• Struct CStructInfo: Represents C Struct type
• Struct CTypeInfo<T>: Represents C type, extended in /c/types

/c/types

Export fixed-size source time known types and non-fixed compile time known types Implememt type-casting for all CTypes

Mod ctype_helper:

• Function get_conv: get FfiConvert from some ctype userdata, used for struct and array conversion
• Function get_size: get size from some ctype userdata, used for call return and arguments boundary checking
• Function get_name: get type name from some ctype userdata, used for pretty-print
• Function get_middle_type: get libffi::middle::Type: from some ctype userdata
• 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 read LuaValue from FfiData or write LuaValue into FfiData

Trait FfiData: Provide common data handle, including methods below

• Method check_boundary: check boundary with offset and size
• Method get_pointer: returns raw pointer *mut ()
• Method is_writable
• Method is_readable

Note: GetFfiData trait in data/mod.rs provides AnyUserData.get_data_handle() -> FfiData method

Mods: Provide common helper functions

• association.rs: GC utility, used for inner, ret and arg type holding in subtype
• bit_mask.rs: u8 bitfield helper
• cast.rs: library
  • Function num_cast<From, Into>(from: FfiData, from: FfiData): Cast number type value inno another number type
• libffi_helper.rs:
  • Const FFI_STATUS_NAMES: Used for ffi_status stringify
  • Function get_ensured_size: Returns ensured ffi_type size
  • Const SIEE_OF_POINTER: Platform specific pointer size (Compile time known)

TODO