CGlue

如果所有代码都粘合在一起，我们的粘合剂是市场上最安全的。

最完整的动态特征对象实现，当之无愧。

• 概述
• 深入了解
  • 安全假设
  • 命名生成
  • 分组泛型
    • 手动实现分组
  • 外部特征
  • 类型包装
  • 关联类型包装
  • 泛型关联类型
  • 插件系统
  • 与 cbindgen 一起工作
    • 设置
    • cglue-bindgen
• 限制
  • 不稳定特性
• 使用 CGlue 的项目
• 变更日志

概述

CGlue 以 FFI 安全方式暴露 dyn Trait。它桥接 Rust 特征与 C 和其他语言。它旨在无缝集成 - 只需在您的特征周围添加一些注释，它们就应该可以使用了！

use cglue::*;

// One annotation for the trait.
#[cglue_trait]
pub trait InfoPrinter {
    type Mark;
    fn print_info(&self, mark: Self::Mark);
}

struct Info {
    value: usize
}

impl InfoPrinter for Info {
    type Mark = u8;

    fn print_info(&self, mark: Self::Mark) {
        println!("{} - info struct: {}", mark, self.value);
    }
}

fn use_info_printer<T: InfoPrinter>(printer: &T, mark: T::Mark) {
    println!("Printing info:");
    printer.print_info(mark);
}

fn main() -> () {
    let mut info = Info {
        value: 5
    };

    // Here, the object is fully opaque, and is FFI and ABI safe.
    let obj = trait_obj!(&mut info as InfoPrinter);

    use_info_printer(&obj, 42);
}

Rust 无法保证您的代码将能与 两个不同的编译器版本冲突，也无法与 任何其他小更改兼容，CGlue 将它们全部粘合在一起，使其工作。

这是通过为指定的特征生成包装虚拟函数表（vtable）并创建一个具有匹配表的不可见对象来完成的。

cglue_trait 注解生成一个 InfoPrinterVtbl 结构，以及构建实现 InfoPrinter 特征所需的所有代码。然后，构建一个 CGlueTraitObj，它包装输入对象并实现 InfoPrinter 特征。

但这不是全部，您还可以将特征分组在一起！

use cglue::*;

// Extra trait definitions

#[cglue_trait]
pub trait InfoChanger {
    fn change_info(&mut self, new_val: usize);
}

impl InfoChanger for Info {
    fn change_info(&mut self, new_val: usize) {
        self.value = new_val;
    }
}

#[cglue_trait]
pub trait InfoDeleter {
    fn delete_info(&mut self);
}

// Define a trait group.
//
// Here, `InfoPrinter` is mandatory - always required to be implemented,
// whereas `InfoChanger` with `InfoDeleter` are optional traits - a checked
// cast must be performed to access them.
cglue_trait_group!(InfoGroup, InfoPrinter, { InfoChanger, InfoDeleter });

// Implement the group for `Info` structure, defining
// only that `InfoChanger` is optionally implemented.
// This is not required if `unstable` feature is being used!
cglue_impl_group!(Info, InfoGroup, InfoChanger);

let mut info = Info { value: 5 };

let mut obj = group_obj!(info as InfoGroup);

// Object does not implement `InfoDeleter`
assert!(as_ref!(&obj impl InfoDeleter).is_none());

change_info(&mut cast!(obj impl InfoChanger).unwrap(), 20);

fn change_info(change: &mut (impl InfoPrinter + InfoChanger), new_val: usize) {
    println!("Old info:");
    change.print_info();
    change.change_info(new_val);
    println!("New info:");
    change.print_info();
}

还有更多！以下是亮点

1. 能够使用自我消耗的特征函数。

2. 一些标准库特征被暴露（Clone）。

3. 将关联的特质类型包裹成新的CGlue特质对象和组的能力。

4. 上述能力也适用于可变和const引用的关联类型返回*。

5. 泛型特质及其组。

6. 库引用计数.

7. 可选的运行时ABI/API验证，使用abi_stable (启用 layout_checks 功能)。

深入了解

安全假设

此crate依赖于一个假设，即不可见对象不会被篡改，即vtable函数不会被修改。这是通过使用隐藏的子模块封装字段来确保的。然而，不可验证的用户（C库）仍然可能能够修改表。此库假设它们不是恶意的，并且不执行任何运行时验证。使用abi_stable进行API版本不匹配检查是一个可选功能（需要rustc 1.46+）。

除了在关联类型包裹中使用的2位之外，此crate应该是安全的。

此crate使用了一些unsafe特质，这些特质会自动实现，或者具有unsafe函数的特质。它们在代码生成器中的使用应该是安全的，它们被标记得如此，以至于手动实现不能引入未定义的行为。

命名生成

#[cglue_trait]宏为MyTrait将生成以下重要类型

只有不可见类型提供功能。不可见类型可以作为Into特质界限使用，并且需要类型检查特质界限。

这些是需要用于界限检查的泛型类型

最后，以下底层类型存在，但不需要在Rust中交互

相反，每个不可见CGlue对象都实现了MyTraitOpaqueObj特质，它包含vtable的类型。

为 MyGroup 定义的 cglue_trait_group! 宏将生成以下主要类型

基本类型如下

容器类型（对 Rust 用户不可见），放置在组内

最后，对象需要实现以便成为可分组的填充特性

宏生成还会为使用所有可选特性的组合生成结构。为了更方便的宏使用，内部可选特性的名称已按字母顺序排序。如果不使用宏，请查看 MyGroup 文档以获取底层转换函数定义。

分组泛型

组相当灵活 - 它不仅限于基本类型。它们还可以包含泛型参数、关联类型和 self 返回（这也适用于单个 traits 对象）。

在 traits 组中使用泛型相当简单，但有几个细微差别。

使用标准模板语法定义组

cglue_trait_group!(GenGroup<T>, Getter<T>, { TA });

也可以指定 traits 约束

cglue_trait_group!(GenGroup<T: Eq>, Getter<T>, { TA });

或者

cglue_trait_group!(GenGroup<T> where T: Eq {}, Getter<T>, { TA });

在泛型类型上实现组

cglue_impl_group!(GA<T: Eq>, GenGroup<T>, { TA });

请注意，在上面的情况下，GA<T> 只有当它实现了 Getter<T> 和 TA 对于 T: Eq 时才能分组。如果 GA 实现了具有不同类型参数的不同集合的可选 traits，则提供多个实现，并指定类型。在每个实现中，仍然添加一个泛型类型 T，但指定其类型在行中的某个位置上的等号

cglue_impl_group!(GA<T = u64>, GenGroup<T>, {});
cglue_impl_group!(GA<T>, GenGroup<T = usize>, { TA });

在此，GA<u64> 仅实现了 Getter<T>，而 GA<usize> 则同时实现了 Getter<usize> 和 TA。

最后，你也可以混合使用这两个，前提是最通用的实现定义了最多的可选特性。

cglue_impl_group!(GA<T: Eq>, GenGroup<T>, { TA });
cglue_impl_group!(GA<T = u64>, GenGroup<T>, {});

手动实现组

注意：如果启用了 unstable 功能，则不支持此功能。相反，你不需要做任何事情！

也可以通过实现 MyGroupVtableFiller 来手动实现组。下面是上述两个宏调用展开后的内容

impl<
        'cglue_a,
        CGlueInst: ::core::ops::Deref<Target = GA<T>>,
        CGlueCtx: cglue::trait_group::ContextBounds,
        T: Eq,
    > GenGroupVtableFiller<'cglue_a, CGlueInst, CGlueCtx, T> for GA<T>
where
    Self: TA,
    &'cglue_a TAVtbl<'cglue_a, GenGroupContainer<CGlueInst, CGlueCtx, T>,
    >:
        'cglue_a + Default,
    T: cglue::trait_group::GenericTypeBounds,
{
    fn fill_table(
        table: GenGroupVtables<'cglue_a, CGlueInst, CGlueCtx, T>,
    ) -> GenGroupVtables<'cglue_a, CGlueInst, CGlueCtx, T> {
        table.enable_ta()
    }
}
impl<
        'cglue_a,
        CGlueInst: ::core::ops::Deref<Target = GA<u64>>,
        CGlueCtx: cglue::trait_group::ContextBounds,
    > GenGroupVtableFiller<'cglue_a, CGlueInst, CGlueCtx, u64> for GA<u64>
{
    fn fill_table(
        table: GenGroupVtables<'cglue_a, CGlueInst, CGlueCtx, u64>,
    ) -> GenGroupVtables<'cglue_a, CGlueInst, CGlueCtx, u64> {
        table
    }
}

#[cglue_trait_ext]
pub trait Clone {
    fn clone(&self) -> Self;
}

cglue_trait_group!(MaybeClone, { }, { ext::Clone }, {
    pub trait Clone {
        fn clone(&self) -> Self;
    }
});

cglue_trait_group!(MaybeClone, { }, { Clone });

cglue_trait_group!(MaybeAsRef<T>, { }, { ::ext::core::convert::AsRef<T> });

fn with_slice(&self, slice: &[usize]) {}

// Generated vtable entry:

with_slice: extern "C" fn(&CGlueC, slice: CSlice<usize>),

fn non_npo_option(&self, opt: Option<usize>) {}

// Generated vtable entry:

non_npo_option: extern "C" fn(&CGlueC, opt: Option<usize>),

fn with_cresult(&self) -> Result<usize, usize> {}

// Generated vtable entry:

with_cresult: extern "C" fn(&CGlueC) -> CResult<usize, usize>,

#[int_result]
fn with_int_result(&self) -> Result<usize> {}

// Generated vtable entry:

with_int_result: extern "C" fn(&CGlueC, ok_out: &mut MaybeUninit<usize>) -> i32,

use cglue::*;
#[cglue_trait]
pub trait ObjReturn {
    #[wrap_with_obj(InfoPrinter)]
    type ReturnType: InfoPrinter + 'static;

    fn or_1(&self) -> Self::ReturnType;
}

struct InfoBuilder {}

impl ObjReturn for InfoBuilder {
    type ReturnType = Info;

    fn or_1(&self) -> Self::ReturnType {
        Info {
            value: 80
        }
    }
}

let builder = InfoBuilder {};

let obj = trait_obj!(builder as ObjReturn);

let info_printer = obj.or_1();

info_printer.print_info();

use cglue::*;
#[cglue_trait]
pub trait LendingPrinter {
    #[wrap_with_obj(InfoPrinter)]
    type Printer<'a>: InfoPrinter + 'a where Self: 'a;

    fn borrow_printer<'a>(&'a mut self) -> Self::Printer<'a>;
}

impl<'a> InfoPrinter for &'a mut Info {
    fn print_info(&self) {
        (**self).print_info();
    }
}

struct InfoStore {
    info: Info,
}

impl LendingPrinter for InfoStore {
    type Printer<'a> = &'a mut Info;

    fn borrow_printer(&mut self) -> Self::Printer<'_> {
        &mut self.info
    }
}

let builder = InfoStore { info: Info { value: 50 } };

let mut obj = trait_obj!(builder as LendingPrinter);

let info_printer = obj.borrow_printer();

info_printer.print_info();

use cglue::prelude::v1::*;

#[cglue_trait]
pub trait PluginRoot {
    // ...
}

impl PluginRoot for () {}

let root = ();
// This could be a `libloading::Library` arc.
let ref_to_count = CArc::from(());
// Merely passing a tuple is enough.
let obj = trait_obj!((root, ref_to_count) as PluginRoot);
// ...

#[cglue_trait]
pub trait PluginRoot {
    #[wrap_with_obj(InfoPrinter)]
    type PrinterType: InfoPrinter;

    fn get_printer(&self) -> Self::PrinterType;
}

impl PluginRoot for () {
    type PrinterType = Info;

    fn get_printer(&self) -> Self::PrinterType {
        Info { value: 42 }
    }
}

let root = ();
// This could be a `libloading::Library` arc.
let ref_to_count = CArc::from(());
let obj = trait_obj!((root, ref_to_count) as PluginRoot);
let printer = obj.get_printer();
// It is safe to drop obj now:
std::mem::drop(obj);
printer.print_info();

[parse]
parse_deps = true
include = ["cglue", "your-crate"]

[parse.expand]
crates = ["cglue", "your-crate"]

rustup run nightly cbindgen --config cbindgen.toml --crate your_crate --output output_header.h

language = "C"

[export]
include = ["FeaturesGroupArcBox", "PluginInnerRef", "PluginInnerMut"]

cglue-bindgen +nightly -- --config cbindgen.toml --crate your_crate --output output_header.h