用于 Rust-to-Rust ffi，重点关注创建在程序启动时加载的库，以及运行时类型检查。

此库允许定义可以在运行时加载的 Rust 库。由于默认（Rust）ABI 和表示形式是不稳定的，所以这是不可能的。

此库的一些用例

• 将 Rust 依赖树从编译成单个二进制文件转换为单个二进制文件（以及可能的许多动态库），允许在更改时分别重新编译。

• 创建一个插件系统（不提供卸载支持）。

功能

目前此库具有以下功能

• sabi_trait 属性宏，用于创建 ffi 安全的特质对象。

• 使用 DynTrait 的某些特质对象的 ffi 安全等效。

• 在 std_types 模块中提供许多标准库类型的 ffi 安全替代方案/包装器。

• 在 external_types 模块中提供一些外部crate定义的类型的 ffi 安全包装器。

• 提供 StableAbi 特质，用于断言类型是 ffi 安全的。

• 用于构建可扩展模块和 vtable 的 前缀类型 功能，而不破坏 ABI 兼容性。

• 支持用 nonexhaustive enums 包装的 ffi 安全 NonExhaustive。

• 在加载时检查动态库中的类型具有预期的布局，允许在检查类型布局的同时进行 semver 兼容的更改。

• 提供 StableAbi derive 宏，用于断言类型与ffi兼容，并在加载时获取类型的布局以检查其是否仍然兼容。

变更日志

变更日志位于 "Changelog.md" 文件中。

示例crates

对于使用 abi_stable 的 示例crates，您可以在该crates仓库的examples目录中查看。

要运行示例crates，通常需要构建 *_impl crate，然后运行 *_user crate（所有 *_user crates 应该有一个帮助信息）。

这些是示例crates

• 0 - 模块和接口类型：通过具有动态链接后端的命令行应用程序，演示了abi_stable "模块"（函数指针的结构体）和接口类型。

• 1 - 特例对象：通过创建最小插件系统，演示了ffi安全的特例对象（使用 sabi_trait 属性宏生成）。

• 2 - 不完整的枚举：演示了作为参数和返回值的非完整枚举，用于管理商店目录的应用程序。

示例

这是一个完整的示例，位于 examples/readme_example，演示了

• 用户crates（在下文架构部分定义）。

• 通过 sabi_trait 属性宏生成的ffi安全特例对象。

• DynTrait：一个ffi安全的用于一系列特例的多特例对象，也可以回溯到具体类型。

• 接口crates（在下文架构部分定义）。

• 实现crates（在下文架构部分定义）。

用户crate

此用户crate（也称为"应用程序crate"）依赖于接口crate，

[dependencies.readme_interface]
path = "../readme_interface" 

其Rust代码是

use abi_stable::std_types::RVec;

use readme_interface::{
    load_root_module_in_directory, AppenderBox, Appender_TO, BoxedInterface, ExampleLib_Ref,
};

fn main() {
    // The type annotation is for the reader
    let library: ExampleLib_Ref = load_root_module_in_directory("../../../target/debug".as_ref())
        .unwrap_or_else(|e| panic!("{}", e));

    {
        /////////////////////////////////////////////////////////////////////////////////
        //
        //       This block demonstrates `#[sabi_trait]` generated trait objects
        //
        ////////////////////////////////////////////////////////////////////////////////

        // The type annotation is for the reader
        let mut appender: AppenderBox<u32> = library.new_appender()();
        appender.push(100);
        appender.push(200);

        // The primary way to use the methods in the trait is through the inherent methods on
        // the ffi-safe trait object.
        Appender_TO::push(&mut appender, 300);
        appender.append(vec![500, 600].into());
        assert_eq!(
            appender.into_rvec(),
            RVec::from(vec![100, 200, 300, 500, 600])
        );
    }
    {
        ///////////////////////////////////////////////////////////////////////////////////
        //
        //  This block demonstrates the `DynTrait<>` trait object.
        //
        //  `DynTrait` is used here as a safe opaque type which can only be unwrapped back to
        //  the original type in the dynamic library that constructed the `DynTrait` itself.
        //
        ////////////////////////////////////////////////////////////////////////////////////

        // The type annotation is for the reader
        let mut unwrapped: BoxedInterface = library.new_boxed_interface()();

        library.append_string()(&mut unwrapped, "Hello".into());
        library.append_string()(&mut unwrapped, ", world!".into());

        assert_eq!(&*unwrapped.to_string(), "Hello, world!");
    }

    println!("success");
}

注意：在运行之前必须编译实现crate，否则您将得到运行时错误，因为库无法加载。

接口crate

use std::path::Path;

use abi_stable::{
    library::{LibraryError, RootModule},
    package_version_strings, sabi_trait,
    sabi_types::VersionStrings,
    std_types::{RBox, RString, RVec},
    DynTrait, StableAbi,
};

/// This struct is the root module,
/// which must be converted to `ExampleLib_Ref` to be passed through ffi.
///
/// The `#[sabi(kind(Prefix(prefix_ref = ExampleLib_Ref)))]`
/// attribute tells `StableAbi` to create an ffi-safe static reference type
/// for `ExampleLib` called `ExampleLib_Ref`.
///
/// The `#[sabi(missing_field(panic))]` attribute specifies that trying to
/// access a field that doesn't exist must panic with a message saying that
/// the field is inaccessible.
#[repr(C)]
#[derive(StableAbi)]
#[sabi(kind(Prefix(prefix_ref = ExampleLib_Ref)))]
#[sabi(missing_field(panic))]
pub struct ExampleLib {
    pub new_appender: extern "C" fn() -> AppenderBox<u32>,

    pub new_boxed_interface: extern "C" fn() -> BoxedInterface<'static>,

    /// The `#[sabi(last_prefix_field)]` attribute here means that this is the last
    /// field in this struct that was defined in the first compatible version of the library
    /// (0.1.0, 0.2.0, 0.3.0, 1.0.0, 2.0.0 ,etc),
    /// requiring new fields to always be added below preexisting ones.
    ///
    /// The `#[sabi(last_prefix_field)]` attribute would stay on this field until the
    /// library bumps its "major" version,
    /// at which point it would be moved to the last field at the time.
    ///
    #[sabi(last_prefix_field)]
    pub append_string: extern "C" fn(&mut BoxedInterface<'_>, RString),
}

/// The RootModule trait defines how to load the root module of a library.
impl RootModule for ExampleLib_Ref {
    abi_stable::declare_root_module_statics! {ExampleLib_Ref}

    const BASE_NAME: &'static str = "example_library";
    const NAME: &'static str = "example_library";
    const VERSION_STRINGS: VersionStrings = package_version_strings!();
}

/// This loads the root from the library in the `directory` folder.
pub fn load_root_module_in_directory(directory: &Path) -> Result<ExampleLib_Ref, LibraryError> {
    ExampleLib_Ref::load_from_directory(directory)
}

//////////////////////////////////////////////////////////

/// `#[sabi_trait]` is how one creates an ffi-safe trait object from a trait definition.
///
/// In this case, the trait object is `Appender_TO<'lt, Pointer<()>, Element>`,where:
///
/// - `'lt`:
///     Is the lifetime bound of the type that constructed the trait object
///     (`'static` is the lifetime bound of objects that don't borrow anything).
///
/// - `Pointer<()>`:
///     Is any pointer that implements some abi_stable specific traits,
///     this pointer owns the value that implements `Appender`.
///
/// - `Element`:
///     This is the element type of the collection that we operate on.
///     This is a type parameter because it's a trait object,
///     which turn associated types into type parameters.
///
#[sabi_trait]
pub trait Appender {
    /// The element type of the collection.
    type Element;

    /// Appends one element at the end of the collection.    
    fn push(&mut self, value: Self::Element);

    /// Appends many elements at the end of the collection.    
    fn append(&mut self, vec: RVec<Self::Element>);

    /// Converts this collection into an `RVec`.
    ///
    /// As opposed to regular trait objects,
    /// it is possible to call by-value methods on trait objects generated by `#[sabi_trait]`.
    ///
    /// The `#[sabi(last_prefix_field)]` attribute here means that this is the last method
    /// that was defined in the first compatible version of the library
    /// (0.1.0, 0.2.0, 0.3.0, 1.0.0, 2.0.0 ,etc),
    /// requiring new methods to always be added below preexisting ones.
    ///
    /// The `#[sabi(last_prefix_field)]` attribute would stay on this method until the library
    /// bumps its "major" version,
    /// at which point it would be moved to the last method at the time.
    ///
    #[sabi(last_prefix_field)]
    fn into_rvec(self) -> RVec<Self::Element>;
}

/// A type alias for the Appender trait object.
///
/// `'static` here means that the trait object cannot contain any borrows.
pub type AppenderBox<T> = Appender_TO<'static, RBox<()>, T>;

// Impls of local traits for dependencies have to be implemented in
// the interface crate, because of the orphan rules.
//
// To avoid compiling more code than necessary,
// this impl is not compiled by default.
// it's enabled by the implementation crate but not the user crate.
#[cfg(feature = "impls")]
impl<T> Appender for RVec<T> {
    type Element = T;
    fn push(&mut self, value: Self::Element) {
        self.push(value);
    }
    fn append(&mut self, vec: RVec<Self::Element>) {
        self.extend(vec);
    }
    fn into_rvec(self) -> RVec<Self::Element> {
        self
    }
}

//////////////////////////////////////////////////////////

/// This type implements `ÌnterfaceType`
/// (because of the `#[sabi(impl_InterfaceType())]` helper attribute of `#[derive(StableAbi)]` ),
/// describing the traits required when constructing `DynTrait<_, TheInterface>`,
/// and are then implemented by it.
#[repr(C)]
#[derive(StableAbi)]
#[sabi(impl_InterfaceType(Sync, Send, Debug, Display))]
pub struct TheInterface;

/// An alias for the trait object used in this example
pub type BoxedInterface<'borr> = DynTrait<'borr, RBox<()>, TheInterface>;

实现crate

这是一个实现crate，它被编译为cdylib（动态库/共享对象），并在运行时由用户crate加载。

其Cargo.toml文件的重要部分是

[lib]
name = "readme_library"
crate-type = ["cdylib",'rlib']

[dependencies.readme_interface]
path = "../readme_interface" 
features = ["impls"]

其Rust代码是

use std::fmt::{self, Display};

use readme_interface::{AppenderBox, Appender_TO, BoxedInterface, ExampleLib, ExampleLib_Ref};

use abi_stable::{
    export_root_module,
    prefix_type::PrefixTypeTrait,
    sabi_extern_fn,
    sabi_trait::prelude::TD_Opaque,
    std_types::{RString, RVec},
    DynTrait,
};

/// The function which exports the root module of the library.
///
/// The root module is exported inside a static of `LibHeader` type,
/// which has this extra metadata:
///
/// - The abi_stable version number used by the dynamic library.
///
/// - A constant describing the layout of the exported root module,and every type it references.
///
/// - A lazily initialized reference to the root module.
///
/// - The constructor function of the root module.
///
#[export_root_module]
pub fn get_library() -> ExampleLib_Ref {
    ExampleLib {
        new_appender,
        new_boxed_interface,
        append_string,
    }
    .leak_into_prefix()
}

/// `DynTrait<_, TheInterface>` is constructed from this type in this example
#[derive(Debug, Clone)]
pub struct StringBuilder {
    pub text: String,
    pub appended: Vec<RString>,
}

impl Display for StringBuilder {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.text, f)
    }
}

impl StringBuilder {
    /// Appends the string at the end.
    pub fn append_string(&mut self, string: RString) {
        self.text.push_str(&string);
        self.appended.push(string);
    }
}

#[sabi_extern_fn]
pub fn new_appender() -> AppenderBox<u32> {
    // What `TD_Opaque` does here is specify that the trait object cannot be downcasted,
    // disallowing the `Appender_TO` from being unwrapped back into an `RVec<u32>`
    // when the `trait_object.obj.*_downcast_*()` methods are used.
    //
    // To be able to unwrap a `#[sabi_trait]` trait object back into the type it
    // was constructed with, you must:
    //
    // - Have a type that implements `std::anu::Any`
    // (it requires that the type doesn't borrow anything).
    //
    // - Pass `TD_CanDowncast` instead of `TD_Opaque` to
    // `Appender_TO::{from_const, from_value,from_ptr}`.
    //
    // - Unerase the trait object back into the original type with
    //     `trait_object.obj.downcast_into::<RVec<u32>>().unwrap()`
    //     (or the other downcasting methods).
    //
    // Downcasting a trait object will fail in any of these conditions:
    //
    // - It wasn't constructed in the same dynamic library.
    //
    // - It's not the same type.
    //
    // - It was constructed with `TD_Opaque`.
    //
    Appender_TO::from_value(RVec::new(), TD_Opaque)
}

/// Constructs a BoxedInterface.
#[sabi_extern_fn]
fn new_boxed_interface() -> BoxedInterface<'static> {
    DynTrait::from_value(StringBuilder {
        text: "".into(),
        appended: vec![],
    })
}

/// Appends a string to the erased `StringBuilder`.
#[sabi_extern_fn]
fn append_string(wrapped: &mut BoxedInterface<'_>, string: RString) {
    wrapped
        .downcast_as_mut::<StringBuilder>() // Returns `Result<&mut StringBuilder, _>`
        .unwrap() // Returns `&mut StringBuilder`
        .append_string(string);
}

安全性

此库确保通过这些机制加载的库是安全的。

• 检查库的abi_stable ABI，每个 0.y.0 版本和 x.0.0 版本的abi_stable定义了自己的ABI，与先前版本不兼容。

• 在调用任何函数之前，在动态库加载时递归检查类型。

[dependencies.abi_stable]
version = "<current_version>"
default-features = false
features = [  ]

    Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
    MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)