联合体

如果您想创建自己的内部标记联合体，您可以使用 #[stabby::stabby] 标记它们，让 stabby 确保您只使用了稳定的变体，并让它知道您联合体的大小和对齐方式。请注意，stabby 总是认为联合体没有空间。

特质

当您使用 #[stabby::stabby] 注解特质时，将为其生成一个 ABI 稳定的 v-table。然后，您可以使用以下类型等价性中的任何一个：

• &'a dyn Traits → DynRef<'a, vtable!(Traits)> 或 dynptr!(&'a dyn Trait)
• &'a mut dyn Traits → Dyn<&'a mut (), vtable!(Traits)> 或者 dynptr!(&'a mut dyn Traits)
• Box<dyn Traits + 'a> → Dyn<'a, Box<()>, vtable!(Traits)> 或者 dynptr!(Box<dyn Traits + 'a>)
• Arc<dyn Traits + 'a> → Dyn<'a, Arc<()>, vtable!(Traits)> 或者 dynptr!(Arc<dyn Traits + 'a>)

请注意，vtable!(Traits) 和 dynptr!(..dyn Traits..) 支持任何数量的特质：例如 vtable!(TraitA + TraitB<Output = u8>) 或者 dynptr!(Box<dyn TraitA + TraitB<Output = u8>>) 都是有效的，但顺序必须保持一致。

然而，stabby生成的v表不会考虑超特质。

为了使 stabby::dynptr!(Box<dyn Traits + 'a>) 具有特质 Trait 的方法，您需要使用 use trait::{TraitDyn, TraitDynMut};，确保您不会意外地密封这些特质，这些特质会自动与您的 Trait 具有相同的可见性。

stabby::closure 导出 CallN、CallMutN 和 CallOnceN 特质，其中 N（在 0..=9）是参数数量，分别是 Fn、FnMut 和 FnOnce 的 ABI 稳定等价物。

从版本 1.0.1 开始，#[stabby::stabby] 生成的 v-table 假定所有方法参数都是 ABI 稳定的，以防止 rustc 冻结的风险。除非您的特质有引用其自身 v-table 的方法，否则建议使用 #[stabby::stabby(checked)] 来避免即使其接口中的一些类型实际上不稳定，v-table 仍被标记为稳定。

由于 stabby 在放置在特质上时会产生一个额外的 struct，您可能想要向该 struct 的声明中添加属性。您可以这样做，您可以使用 #[stabby::vt_attr(your_attribe = "goes here")]。任何其他属性都将放置在原始特质上。

函数

#[stabby::stabby]

使用 #[stabby::stabby] 标注函数会使其成为 extern "C"（但不是 #[no_mangle]），并检查其签名以确保所有交换的类型都标记为 stabby::abi::IStable。您还可以指定您选择的调用约定。

#[stabby::导出]

与 #[stabby::stabby] 工作方式相同，但会在标注的函数中添加 #[no_mangle]，并生成另外两个无混叠函数

• extern "C" fn <fn_name>_stabbied(&stabby::abi::report::TypeReport) -> Option<...>，如果类型报告与 <fn_name> 的签名匹配，将返回 <fn_name> 作为函数指针，确保它们确实具有相同的签名。
• extern "C" fn <fn_name>_stabbied_report() -> &'static stabby::abi::report::TypeReport 将返回 <fn_name> 的类型报告，允许在之前函数返回 None 时进行调试。

#[stabby::导出(金丝雀)]

适用于任何函数，包括那些会被 FFI-不安全函数。除了在原始函数中添加 #[no_mangle]，它还会向生成的共享库中添加一组小的 <fn_name>_<canary> 符号。这些金丝雀包括 rustc 的版本、优化级别以及其他可能导致编译器为 <fn_name> 使用不同 ABI 的属性。

当加载共享库时，链接器可以检查这些符号的存在，防止在加载器请求不兼容版本的金丝雀时进行链接。

#[stabby::导入(...)]

使用此功能注释一个 extern 块与以下代码等效：#[link(...)]，但符号将使用 <fn_name>_stabbied 进行惰性初始化，确保在调用之前函数参数的报告中保持一致。

如果您想在出现潜在不匹配错误时避免恐慌，可以调用 <fn_name>.as_ref()，这将允许您在失败的情况下检查 <fn_name> 的报告。

#[stabby::导入(金丝雀="rustc, opt_level", ...)]

使用此功能注释一个 extern 块与以下代码等效：#[link(...)]，但需要对应您的规范的canary才能进行链接。这类似于 export(canaries)，它总是导出所有可用的canary，但您可以从以下集合中选择您想启用的canary。

• paranoid：启用所有canary，如果您使用 canaries=""，则会选择此选项。
• rustc：启用对 rustc 版本（总是到 commit 版本）的canary。
• opt_level：启用对 opt_level 的canary（对于 extern "rust" fn 是必要的，因为优化级别可能会更改调用约定）。
• target：启用用于构建对象的编译器目标三联组的canary。
• num_jobs（paranoid）：启用用于构建对象的作业数量的canary。这可能影响优化，因此可能会影响ABI（未经证实）。
• debug（paranoid）：启用是否使用调试符号构建对象的canary。对ABI的影响未经证实，但未排除。
• host（paranoid）：启用由编译器设置的编译器主机三联组的canary。对ABI的影响未经证实，但未排除。
• none：主要是在您自己的风险下完全禁用canary。

stabby::libloading::StabbyLibrary 特性

为 libloading::Library 添加了额外的功能，这些功能公开了符号获取器，如果canary不存在或报告不匹配，则这些获取器会失败。

这些方法仍然被认为是非安全的，但它们将减少意外加载ABI不兼容代码的风险。报告还充当运行时类型检查，降低误写符号的风险。

异步

在稳定类型上实现 core::future::Future 的工作，无论该稳定类型是在 FFI 边界哪一侧构建的，都是通用的。然而，由异步块和异步函数创建的 future 不可作为 ABI 稳定使用，因此必须通过特质对象使用。

stabby 通过 stabby::future::Future 特质支持 future。异步函数通过 #[stabby::stabby] 转换为返回 Dyn<Box<()>, vtable!(stabby::future::Future + Send + Sync)>（可以通过使用 #[stabby::stabby(unsync, unsend)] 来移除 Send 和 Sync 的界限），它本身实现了 core::future::Future。

use stabby::{slice::SliceMut, future::DynFuture};
#[stabby::stabby]
pub trait AsyncRead {
	fn read<'a>(&'a mut self, buffer: SliceMut<'a, [u8]>) -> DynFuture<'a, usize>;
}
impl MyAsyncTrait for SocketReader {
	extern "C" fn read<'a>(&'a mut self, mut buffer: SliceMut<'a, [u8]>) -> DynFuture<'a, usize> {
		Box::new(
			async move {
				let slice = buffer.deref_mut();
				let read = SocketReader::read_async(&mut self.socket, slice).await;
				buffer = slice.into();
				read
			}
		).into()
	}
}