ཕྱི་ཁའི་འགན་ཁུར་གྱི་འབྲེལ་མཐུད་འབད་ཐངས་ (FFI)

འདི་ཚུ་ iroha_ffi ཀེར་ཐིག་གིས་ C བཟོ་སྐྲུན་འབད་ནིའི་དོན་ལུ་ མཁའ་འགྲོ་དང་ཁྱད་ཆོས་ཚུ་ བྱིན་དོ་ཡོདཔ་ཨིན། ABI འབྲེལ་མཐུད་ཚུ་ Rust APIs. འདི་ནང་ལུ་ ལག་ལེན་འཐབ་ཨིན། Iroha རིགས་དབྱེ་བ་ཚུ་བརྒལ་དགོཔ་ཨིན། FFI ས་མཚམས་ དཔེར་ན་ SDK མཐུད་སྦྲེལ་འབད་ནི་དང་ host འབྲེལ་མཐུད་འབད་ནི་ཚུ་

ག་ཅི་འབད་ FFI

འགན་འཁྲི་འདི་ མང་ཤོས་ཀྱི་སྐད་ཡིག་ཚུ་ནང་ ལཱ་ག་ཅི་འབད་དགོཔ་ཨིན་ནའི་སྐོར་ལས་ ངོས་ལེན་ཡོདཔ་ཨིན་རུང་ འགན་འཁྲུལ་དེ་ ག་ཅི་སྦེ་ངོ་སྤྲོད་འབདཝ་ཨིན་ན་ འདི་ཡང་ ཁྱད་པར་སྦོམ་ཅིག་ཨིན་མས། དེ་མ་ཚད་ སྐད་ཡིག་ལ་ལུ་ཅིག་ནང་ དཔེར་ན་ Rust འདི་བཟུམ་སྦེ་ འགན་འཁྲི་ཅིག་ལུ་འབོ་པའི་གྲུབ་འབྲས་དང་ འབད་ཆོག་པའི་ལཱ་ཚུ་ཡང་ ཁྱད་པར་ཅན་ཨིན། ཁྱོད་ཀྱིས་ Rust APIs ལུ་ སྐད་ཡིག་གཞན་ལས་ ཡང་ན་ གནས་སྟངས་སོ་སོ་ནང་ལས་འབོ་དགོ་པ་ཅིན་ Iroha གིས་ རྩེད་འགྲན་གི་གནས་སྟངས་དེ་འདྲ་མཉམ་བཟོ་ནིའི་དོན་ལུ་ ཕྱི་ཁའི་འགན་ལེན་ཡིག་ལྟེ་ (FFI) ལག་ལེན་འཐབ་ཨིན།

ད་རེས་ལག་ལེན་འཐབ་མི་ གནས་ཚད་ངོ་མ་འདི་ C application binary interface ཨིན། འདི་འཇམ་ཏོང་ཏོ་དང་ ཁྱབ་ཚུགསཔ་ དེ་ལས་བརྟན་ཏོག་ཏོ་ཨིན། གཞི་རྩ་ནང་ ཁྱོད་ཀྱིས་ག་ར་ལག་ཐོག་ལུ་འབད་ཚུགས་ནི་ཨིན་རུང་ Iroha གིས་ iroha_ffi སྒྲོམ་ཅིག་ བཟོ་སྟེ་ཡོདཔ་ད་ འདི་གིས་ ཧེ་མ་ལས་ཡོད་པའི་ Rust API ལས་ FFI-compliant functions བཟོ་ཚུགས།

ཁྱོད་ཀྱིས་འདི་ རང་བཞིན་གྱིས་འབད་ཚུགསཔ་ཨིན། iroha_ffi སྒྲོམ་འདི་གིས་ ཁྱོད་ག་དེ་སྦེ་ཨིན་རུང་ ཐོན་སྐྱེད་འབད་དགོ་པའི་ ཀོ་ཌ་རྐྱངམ་ཅིག་བཟོཝ་ཨིན། དགོས་མཁོ་ཅན་གྱི་སྒྲོམ་འབྲི་ནི་ལུ་ བརྩོན་ཤུགས་དང་བཅའ་ཁྲིདཔ་དུམ་གྲ་ཅིག་དགོཔ་ཨིན། FFI གི་མཐའ་མཚམས་ལས་ འགན་འཁྲི་འབོ་མི་རེ་རེ་གིས་ unsafe བཟོ་ཚུགས་ཏེ་ བྱ་སྤྱོད་མ་ངེས་ཅན་ཅིག་ འབྱུང་བཅུགཔ་ཨིན། ང་བཅས་ཀྱིས་འདི་ སེལ་ཐབས་འབད་ཐངས་དེ་ སྒྲིང་སྒྲི་ཅན་གྱི་ repr(C) ཚོས་གཞི་ཚུ་ལག་ལེན་འཐབ་ཐོག་ལས་ བསྒྱུར་བཅོས་འབདཝ་ཨིན།

INFO

གནད་དོན་གཅིག་པོའ ་ི བརྗོད་སྟོན་ཚུ་ཨིན། ནུལ་ལའི་བརྟག་དཔྱད་དང་ བདེན་ཁུངས་འདི་ འཛམ་གླིང་གི་གནས་ཚད་ནང་ བཏོན་མི་ཚུགས། འདི་འབདཝ་ལས་ བརྗོད་རྟགས་ངོ་མ་ (ཨ་རྟག་བཟུམ་སྦེ་) འདི་ལུ་ དམིགས་བསལ་གྱི་གནད་དོན་ནང་ལུ་རྐྱངམ་གཅིག་ ལག་ལེན་འཐབ་ཡོདཔ་ཨིན། འདི་འབདཝ་ལས་ ང་བཅས་ཀྱིས་ Iroha ཌའི་ཊ་ མոդելནང་ལུ་ གནད་སྡུད་ཀྱི་དཔེ་ཆ་རེ་རེ་ལུ་ མཐའ་འཁོར་གྱི་མཐའ་བསྐོར་ནང་ བསྒྲགས་འབད་དོ་ཡོདཔ་ལས་ ཁྱོད་ཀྱིས་ raw pointers ལག་ལེན་འཐབ་མ་དགོ་པར་སྡོད་འོང་།

དཔེ་གཅིག་

འ་ནཱ་གི་དཔེ་འདི་ བསྡུ་སྒྲིག་བཟོ་ནི་གི་ དཔེ་གཅིག་ཨིན།

#[derive(FfiType)]
struct DaysSinceEquinox(u32);

#[ffi_export]
impl DaysSinceEquinox {
    pub fn update_value(&mut self, a: &u8) {
        self.0 = *a as u32;
    }
}

གོང་གི་དཔེ་སྟོན་འདི་གིས་ DaysSinceEquinox དང་གཅིག་ཁར་ མཐུད་སྦྲེལ་འབད་མི་འདི་ འཕྱགས་བདར་ཅན་གྱི་བརྡ་མཚོན་སྦེ་ངོ་སྤྲོད་འབདཝ་ཨིན།

pub extern fn DaysSinceEquinox__update_value(handle: *mut DaysSinceEquinox, a: *const u8) -> FfiReturn {
    // function implementation
}

FFI བསྡུ་སྒྲིག་འབད་ཐངས་ Generation

iroha_ffi སྒྲོམ་འདི་ FFI གྱི་ཐོག་ལས་ ཀལ་འབད་བཏུབ་པའི་ འགན་ཁུར་ཚུ་ བཟོ་ནིའི་དོན་ལུ་ལག་ལེན་འཐབ་ཨིན། Rust གི་བཟོ་རྣམ་དང་ ཐབས་ལམ་ཚུ་བྱིན་ཞིནམ་ལས་ ཁྱོད་ཀྱིས་འབྲེལ་མཐུད་ཀྱི་མཐའ་མཚམས་བརྒལ་བའི་དོན་ལུ་ དགོས་མཁོ་ཅན་གྱི་ unsafe ལྡེ་མིག་ཚུ་བཟོ།

A Rust འདྲ་བཤུས་ཅིག་ལུ་ བསྒྱུར་བཅོས་འབད་ཡོདཔ་ཨིན། repr(C) ཐིག་ཁྲམ་ཚུ་སེལ་འཐུ་འབད་ཚུགས། FFI ཚད་གཞི་ཚུ་ FfiType::into_ffi. འདི་ཡང་ཚུར་ལོག་འགྱོ་དོ་ཡོདཔ་ཨིན། FFI ReprC འདྲ་བཤུས་འདི་ བསྒྱུར་བཅོས་འབད་འབདཝ་ཨིན། Rust རྒྱང་བསྒྲགས། FfiType::try_from_ffi.

WARNING

འདི་འབདཝ་ལས་ བསྒྱུར་བཅོས་འདི་ འཛོལ་བ་འབྱུང་ཚུགས་ནི་ཨིནམ་མ་ཚད་ བྱ་བ་སྤྱོད་ལམ་ཚུ་ ངེས་གཏན་མེདཔ་སྦེ་ འབྱུང་སྲིད་ནི་ཨིནམ་ཤེས་དགོ། ང་བཅས་ཀྱིས་མཐོ་བའི་འཛོལ་བ་ཚུ་ བཀག་ཐབས་ལུ་ རྩ་འགེངས་འབད་དགོ་རུང་ ཁྱོད་ཀྱིས་ ལས་རིམ་དེ་ ཁྱོད་ཀྱི་མཐའ་མ་ནང་ ཕྲང་བདེན་བཟོ་དགོ་ཟེར་ཨིན་པས།

འབྲེལ་མཐུད་བཟོ་སྐྲུན་འབད་ཚུགས་མི་ རྟགས་མཚན་ངོ་མ་འདི་ ReprC, FfiType དང་ FfiConvertཨིན།

རྟགས་མཚན་	འགྲེལ་བཤད་
ReprC	འ་ནི་ཁྱད་ཆོས་འདི་ C ABI དང་གཅིག་ཁར་མཐུན་ལམ་ཅན་ཅིག་ཨིནམ་ཨིན། བཟོ་བཀོད་འདི་ FFI གི་ས་མཚམས་ཚུ་ནང་ ཉེན་སྲུང་ལྡན་པའི་ཐོག་ལས་བགོ་བཤའ་རྐྱབ་ཚུགས།
FfiType	འ་ནི་ཁྱད་ཆོས་འདི་ Rust གི་དབྱེ་བ་ཅིག་གི་དོན་ལུ་ འོས་འབབ་ཅན་གྱི་ ReprC ཐིག་ཁྲམ་ཅིག་ ངེས་འཛིན་འབདཝ་ཨིན། བཟོ་བཀོད་འབད་ཡོད་པའི་ ReprC གྱི་དབྱེ་བ་དེ་ ཐོན་སྐྱེད་འབད་མི་ FFI འགན་ཁུར་གི་ API ནང་ Rust ཀྱི་ཚབ་ལུ་ ལག་ལེན་འཐབ་ཨིན།
FfiConvert	འ་ནི་ཁྱད་ཆོས་འདི་གིས་ ཐབས་ལམ་གཉིས་ into_ffi དང་ try_from_ffi བཟོ་བཀོད་འབད་མི་དེ་ ལག་ལེན་འཐབ་སྟེ་ Rust གི་དབྱེ་བ་ལུ་ ཡང་ན་ ReprC གྱི་དབྱེ་བ་ལུ་བསྒྱུར་བཅོས་འབདཝ་ཨིན།

FFI གི་ནང་འཁོད་ལུ་ སྦྱིན་བདག་གྱི་བགོ་བཤའ་དེ་མེད་ཟེར་དྲན་གསོ་འབད་དགོ་ དྭངས་གསལ་མེད་པའི་བརྡ་སྟོན་དབྱེ་བ་ཚུ་མ་གཏོགས་གཞན་ཨིན། གཞན་ཡང་སྦྱིན་བདག་གི་རིགས་ཚུ་ དཔེར་ན་ Vec<T> འདི་ཚུ་ ཀྲོན་འབདཝ་ཨིན།

མིང་བཏགས་ Mangling

FFI འདྲ་མཉམ་ཚུ་གི་མིང་ནང་ལུ་ double undercores གི་ལག་ལེན་འཐབ་ནི་འདི་དྲན་གསོ་འབད་:

• StructName བཟོ་བཀོད་ནང་ལུ་ གསལ་བཀོད་འབད་ཡོད་མི་ inherent_fn ཐབས་ལམ་གྱི་དོན་ལུ་ FFI ཟེར་མི་མིང་འདི་ StructName__inherent_fn ཨིན་པས།

• TraitNameགི་དབྱེ་བ་ལས་ MethodNameགི་ཐབས་ལམ་གྱི་དོན་ལུ་ StructName བཟོ་བཀོད་ནང་ FFI གི་མིང་འདི་ StructNameTraitNameMethodName འབད་ནི་ཨིན།

• StructName བཟོ་བཀོད་ནང་ལུ་ field_name ས་ཁོངས་དེ་ གཞི་སྒྲིག་འབད་བ་ཅིན་ FFI འགན་ཁུར་གི་མིང་འདི་ StructName__set_field_name འབད་ནི་ཨིན།

• StructName བཟོ་བཀོད་ནང་ལུ་ field_name ས་ཁོངས་ཐོབ་ནིའི་དོན་ལུ་ FFI འགན་ཁུར་གི་མིང་འདི་ StructName__field_name འབད་ནི་ཨིན།

• StructName བཟོ་བཀོད་ནང་ལུ་འགྱུར་ལྡོག་ཅན་གྱི་ field_name ས་ཁོངས་ཐོབ་ནིའི་དོན་ལུ་ FFI འགན་ཁུར་གི་མིང་འདི་ StrucuName__field_name_mut འབད་ནི་ཨིན།

• རང་དབང་གནས་ཚད་ཅན་གྱི་ module_name::fn_nameགི་དོན་ལུ་ མིང་འདི་ FFI འབད་ནི་ཨིན། module_name::__fn_name

• རིགས་དབྱེ་བ་ཚུ་ སྤྱིར་བཏང་མེནམ་དང་ ཁོང་རའི་ལག་ལེན་ནང་ བརྗེ་སོར་འབད་ནིའི་གོ་སྐབས་བྱིན་ FFI (བལྟ་ར) Clone འོག་གི་ཤོག་ལེབ་ཚུ་ FFI མིང་འདི་ module_name::__clone.

  impl Clone for Type1 {
      fn clone(&self) -> Self;
  }
  impl Clone for Type2 {
      fn clone(&self) -> Self;
  }