• 外部函数fn_name_stabbied(&stabby::abi::report::TypeReport) -> Option<.>将返回一个函数指针，如果类型报告与fn_name的签名匹配，确保它们确实具有相同的签名。
• 外部函数fn_name_stabbied_report() -> &static stabby::abi::report::TypeReport将返回fn_name的类型报告，允许在先前函数返回None时进行调试。

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

此工具适用于任何函数，包括FFI不安全的函数。除了在原始函数上添加#[no_mangle]之外，它还会在生成的共享库中添加一组小的fn_name_canary符号。这些金丝雀包括rustc的版本、优化级别以及其他可能使编译器使用不同ABI的属性。

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

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

使用此注解标注extern块相当于使用#[link(...)]，但符号将通过使用fn_name_stabbied进行懒加载初始化，确保在调用它之前函数参数的报告是一致的。

如果您想要在不恐慌的情况下处理潜在的不匹配错误，可以调用fn_name.as_ref()，这将在失败的情况下允许您检查fn_name的报告。

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

使用此方法注释extern块等价于#[link(...)]，但需要对应您规格的canaries才能实现链接。这类似于export(canaries)，它总是导出所有可用的canaries，但您可以从以下集合中选择要启用的canaries。

• paranoid：启用所有canaries，如果您使用canaries=""，则也会选择此项。
• rustc：启用rustc版本上的canary（始终是最新的commit版本）。
• opt_level：启用opt_level上的canary（对于extern "" fn是必要的，因为优化级别可能会改变调用约定）。
• target：启用用于构建对象的编译器目标三元组的canary。
• num_jobs（paranoid）：启用用于构建对象的作业数上的canary。这可能会影响优化，从而可能影响ABI（未经证实）。
• debug（paranoid）：启用是否使用调试符号构建对象的canary。对ABI的影响未经证实，但不是被排除的。
• host（paranoid）：启用编译器主机三元组上的canary，该三元组由编译器设置。对ABI的影响未经证实，但不是被排除的。
• none：主要在这里让您可以完全禁用canaries，风险自负。

stabby::libloading::StabbyLibrary特质

为libloading::Library提供的额外方法，这些方法公开了符号获取器，如果canaries不存在或报告不匹配，则这些获取器将失败。

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

异步

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

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

stabby 目前还不支持异步特性，但您可以使用以下模式来实现它们

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()
	}
}

增量稳定性

stabby 还允许您使用 stabby::abi::StableLike 告诉它某些事物即使您无法使用 #[stabby::stabby] 也能保持 ABI 稳定。

结合 stabby::compiler_version 中的 ZSTs，它们实现了 stabby::IStable，但仅在用相应的编译器版本编译时才有效。这使您可以声明某些类型仅在用适当的编译器版本编译时才是稳定的。但是，即使没有这样的 ZSTs，这些类型也仍然可以在任何没有 stabby::IStable 约束的地方使用。

stabby 的“宣言”

stabby 是为了解决 Rust 生态系统中缺乏 ABI 稳定性问题而构建的，这使得编写插件和其他基于动态链接的程序变得痛苦。目前，Rust 唯一的稳定 ABI 是 C ABI，它没有类型之和的概念，更不用说特定用途的利用了。

然而，我们的软件工程经验表明，类型大小对性能有很大影响，因此类型之和应该以占用空间最小的方式编码。

我对 stabby 的希望有两个方面

• Rust 生态系统的采用：这是我最不喜欢的选项，但至少在需要动态链接的情况下，人们可以用更好的方式使用 Rust。
• 引发了一场关于为Rust提供版本化ABI而不是稳定ABI的讨论：stabby通过所选版本的stabby-abicrate实际上已经提供了版本化ABI。然而，让库实现类型布局，这通常是编译器的任务，强迫abi-stability变得针对每种类型是明确的，而不是适用于整个编译单元。在我看来，在cargo清单中添加一个abi = "<stabby/crabi/c>"键将是一种更好的做法。更好的是，将这个想法与RFC 3435合并，允许基于每个函数选择ABI，并让编译器将所选稳定ABI污染注释函数接口的类型，这将更加粒度化，但仍然允许最终用户通过承诺依赖项的单个版本来实现ABI稳定性。

stabby的SemVer策略

Stabby将其所有stabby_abi::IStable实现包含在其公共API中：对IStable类型内存表示的任何更改都是一个破坏性更改，这将导致MAJOR版本更改。

从6.1.1开始，Stabby遵循SemVer Prime，使用api, abi作为键。以下是您可以解释的几种方式

• stabby.version[level] = 2^(api[level]) * 3^(abi[level])让您计算stabby的ABI和API的确切版本。
• 当升级stabby时，您可以通过将新版本除以旧版本来检查发生了什么更改：如果除法结果是2的倍数，则更改影响了API；如果是3的倍数，则影响了ABI。
  • ABI版本化
    • 向ABI稳定类型集合添加新类型将增加ABI补丁版本。
    • 以任何方式修改现有类型的ABI将增加ABI主版本。
  • API版本化严格遵循SemVer策略。任何在文档中可见的API都视为公共API，以及文档中提到的所有合同。