mbox: malloc 基于的盒子

此crate提供封装从 malloc 返回的指针的结构，并在丢弃时自动释放它们。这些类型允许您以Rust风格与指针和以null结尾的字符串和数组进行交互。

示例

extern crate libc;
extern crate mbox;

use libc::{c_char, malloc, strcpy};
use mbox::MString;

// Assume we have a C function that returns a malloc'ed string.
unsafe extern "C" fn create_str() -> *mut c_char {
    let ptr = malloc(12) as *mut c_char;
    strcpy(ptr, b"Hello world\0".as_ptr() as *const c_char);
    ptr
}

fn main() {
    // we wrap the null-terminated string into an MString.
    let string = unsafe { MString::from_raw_unchecked(create_str()) };

    // check the content is expected.
    assert_eq!(&*string, "Hello world");

    // the string will be dropped by `free` after the code is done.
}

注意：此crate通常不支持Windows。

Rust中的指针需要对齐以确保稳定性。然而，在Windows上没有同时兼容 free() 和支持对齐malloc的API。

因为此crate的主要目的是与使用 malloc() 与C代码进行互操作，所以我们无法切换到像 _aligned_malloc() （这需要 _aligned_free()）这样的安全版本。

在 Windows 上，尝试使用 MBox<T> 或 MArray<T>，其中 T 的对齐方式不为 1 时，将无法编译。

# #[cfg(not(windows))] { _ };

use mbox::MBox;
let value = MBox::new(1_u64); // will not compile,

安装

将以下内容添加到您的 Cargo.toml 文件中

[dependencies]
mbox = "0.7"

用法

此包提供三种主要类型，所有这些类型都使用系统的 malloc/free 作为分配器。

• MBox<T> —— 与 Box<T> 类似。
• MString —— 与 std::ffi::CString 类似。
• MArray<T> —— 一个以 null 结尾的数组，可以用来表示例如以 null 指针结尾的 C 字符串数组。

#![no_std]

您可以将 mbox 编译并禁用 std 功能，以不链接到 std（它仍然会链接到 core）。

[dependencies]
mbox = { version = "0.7", default-features = false }

当 #![no_std] 被激活时，您不能将 MString 转换为 std::ffi::CStr，因为该类型根本不存在 😅。

Nightly

要使用 nightly-channel 功能（如果您需要支持自定义动态大小类型），请启用 nightly 功能

[dependencies]
mbox = { version = "0.7", features = ["nightly"] }

从其他包迁移

请注意，MBox 不支持自定义分配器。如果类型需要自定义分配，则 MBox 无法满足您的需求。

• malloc_buf —— Malloc<T> 等同于 MBox<T>。但是请注意，MBox<[T]>::from_raw_parts 不允许 null、0 长度的缓冲区；使用悬空指针代替。

• cbox —— 当不使用自定义 DisposeRef 时，类型 CSemiBox<'static, T> 等同于 MBox<T>，而 CBox<T> 等同于 &'static T。

• c_vec —— 当使用 free 作为析构函数时，CVec<T> 等同于 MBox<[T]> 和 CSlice<T> 作为 [T]。

• malloced —— Malloced<T> 等同于 MBox<T>。但请注意，mbox 依赖于 libc（更稳定，但构建时间更长）并且不支持 dyn Any 降级。

• malloc-array —— HeapArray<T> 与 MBox<T> 类似，但这个crate更专注于原始内存管理。