Refactor and documenting code structure (#243)

Author: qwreey

Cargo.lock

@@ -0,0 +1,79 @@
+# `lune-std-ffi`
+
+## Code structure
+
+### /c
+
+Define C-ABI type information and provide conversion and casting
+
+- [**Struct ` CArrInfo`:**](./src/c/struct_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 creation
+- [**Struct ` CStructInfo`:**](./src/c/struct_info.rs) Represents C Struct type
+- [**Struct ` CTypeInfo<T>`:**](./src/c/type_info.rs) 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`:**](./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 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

crates/lune-std-ffi/README.md

@@ -3,12 +3,11 @@ use std::cell::Ref;
 use libffi::middle::Type;
 use mlua::prelude::*;
 
-use super::{association_names::CARR_INNER, c_helper, method_provider};
-use crate::ffi::{
-    ffi_association::{get_association, set_association},
-    NativeConvert, NativeData, NativeSize,
+use super::{association_names::CARR_INNER, helper, method_provider};
+use crate::{
+    data::{FfiConvert, FfiData, FfiSize},
+    ffi::{association, libffi_helper::get_ensured_size},
 };
-use crate::libffi_helper::get_ensured_size;
 
 // This is a series of some type.
 // It provides the final size and the offset of the index,
@@ -19,19 +18,19 @@ use crate::libffi_helper::get_ensured_size;
 // We can simply provide array type with struct.
 // See: https://stackoverflow.com/a/43525176
 
-pub struct CArr {
+pub struct CArrInfo {
     struct_type: Type,
     length: usize,
     size: usize,
     inner_size: usize,
-    inner_conv: *const dyn NativeConvert,
+    inner_conv: *const dyn FfiConvert,
 }
 
-impl CArr {
+impl CArrInfo {
     pub fn new(
         element_type: Type,
         length: usize,
-        inner_conv: *const dyn NativeConvert,
+        inner_conv: *const dyn FfiConvert,
     ) -> LuaResult<Self> {
         let inner_size = get_ensured_size(element_type.as_raw_ptr())?;
         let struct_type = Type::structure(vec![element_type.clone(); length]);
@@ -51,11 +50,11 @@ impl CArr {
         type_userdata: &LuaAnyUserData<'lua>,
         length: usize,
     ) -> LuaResult<LuaAnyUserData<'lua>> {
-        let fields = c_helper::get_middle_type(type_userdata)?;
-        let conv = unsafe { c_helper::get_conv(type_userdata)? };
+        let fields = helper::get_middle_type(type_userdata)?;
+        let conv = unsafe { helper::get_conv(type_userdata)? };
         let carr = lua.create_userdata(Self::new(fields, length, conv)?)?;
 
-        set_association(lua, CARR_INNER, &carr, type_userdata)?;
+        association::set(lua, CARR_INNER, &carr, type_userdata)?;
         Ok(carr)
     }
 
@@ -70,13 +69,13 @@ impl CArr {
     // Stringify for pretty printing like:
     // <CArr( u8, length = 8 )>
     pub fn stringify(lua: &Lua, userdata: &LuaAnyUserData) -> LuaResult<String> {
-        let this = userdata.borrow::<CArr>()?;
+        let this = userdata.borrow::<CArrInfo>()?;
         if let Some(LuaValue::UserData(inner_userdata)) =
-            get_association(lua, CARR_INNER, userdata)?
+            association::get(lua, CARR_INNER, userdata)?
         {
             Ok(format!(
                 " {}, length = {} ",
-                c_helper::pretty_format(lua, &inner_userdata)?,
+                helper::pretty_format(lua, &inner_userdata)?,
                 this.length,
             ))
         } else {
@@ -85,18 +84,18 @@ impl CArr {
     }
 }
 
-impl NativeSize for CArr {
+impl FfiSize for CArrInfo {
     fn get_size(&self) -> usize {
         self.size
     }
 }
-impl NativeConvert for CArr {
+impl FfiConvert for CArrInfo {
     // FIXME: FfiBox, FfiRef support required
-    unsafe fn luavalue_into<'lua>(
+    unsafe fn value_into_data<'lua>(
         &self,
         lua: &'lua Lua,
         offset: isize,
-        data_handle: &Ref<dyn NativeData>,
+        data_handle: &Ref<dyn FfiData>,
         value: LuaValue<'lua>,
     ) -> LuaResult<()> {
         let LuaValue::Table(ref table) = value else {
@@ -106,7 +105,7 @@ impl NativeConvert for CArr {
             let field_offset = (i * self.inner_size) as isize;
             let data: LuaValue = table.get(i + 1)?;
 
-            self.inner_conv.as_ref().unwrap().luavalue_into(
+            self.inner_conv.as_ref().unwrap().value_into_data(
                 lua,
                 field_offset + offset,
                 data_handle,
@@ -116,18 +115,18 @@ impl NativeConvert for CArr {
         Ok(())
     }
 
-    unsafe fn luavalue_from<'lua>(
+    unsafe fn value_from_data<'lua>(
         &self,
         lua: &'lua Lua,
         offset: isize,
-        data_handle: &Ref<dyn NativeData>,
+        data_handle: &Ref<dyn FfiData>,
     ) -> LuaResult<LuaValue<'lua>> {
         let table = lua.create_table_with_capacity(self.length, 0)?;
         for i in 0..self.length {
             let field_offset = (i * self.inner_size) as isize;
             table.set(
                 i + 1,
-                self.inner_conv.as_ref().unwrap().luavalue_from(
+                self.inner_conv.as_ref().unwrap().value_from_data(
                     lua,
                     field_offset + offset,
                     data_handle,
@@ -138,12 +137,12 @@ impl NativeConvert for CArr {
     }
 }
 
-impl LuaUserData for CArr {
+impl LuaUserData for CArrInfo {
     fn add_fields<'lua, F: LuaUserDataFields<'lua, Self>>(fields: &mut F) {
         fields.add_field_method_get("size", |_, this| Ok(this.get_size()));
         fields.add_field_method_get("length", |_, this| Ok(this.get_length()));
         fields.add_field_function_get("inner", |lua, this: LuaAnyUserData| {
-            let inner: LuaValue = get_association(lua, CARR_INNER, this)?
+            let inner: LuaValue = association::get(lua, CARR_INNER, this)?
                 // It shouldn't happen.
                 .ok_or_else(|| LuaError::external("inner field not found"))?;
             Ok(inner)