unsafe Trait ​

核心概念 ​

unsafe trait 是一种特殊的 trait 声明方式,表示实现该 trait 的类型必须满足某些编译器无法自动验证的安全契约(invariant)。trait 被标记为 unsafe 不是因为它的方法有危险,而是因为实现者必须手动保证某些语义上的承诺。标准库中最典型的 unsafe trait 是 Send 和 Sync——编译器会自动推导大多数类型是否实现这两个 trait,但如果你用 unsafe impl 手动实现,就必须自己保证类型确实可以安全地跨线程发送或共享。

rust
// 声明一个 unsafe trait
// 实现者必须保证 validate 返回 true 时数据确实有效
unsafe trait Validated {
    fn validate(&self) -> bool;
    fn data(&self) -> &str;
}

struct Email {
    address: String,
}

// 实现 unsafe trait 需要 unsafe impl
// SAFETY: Email 的 validate 方法正确检查了 @ 符号,
// data 方法返回的地址只在 validate 为 true 时有意义。
unsafe impl Validated for Email {
    fn validate(&self) -> bool {
        self.address.contains('@') && self.address.len() > 3
    }

    fn data(&self) -> &str {
        &self.address
    }
}

// 使用 unsafe trait 的函数可以信赖安全契约
fn process_validated(item: &impl Validated) {
    if item.validate() {
        println!("有效数据: {}", item.data());
    } else {
        println!("数据无效");
    }
}

fn main() {
    let valid = Email { address: "user@example.com".to_string() };
    let invalid = Email { address: "bad".to_string() };

    process_validated(&valid);
    process_validated(&invalid);
}

标准库中的 unsafe trait ​

rust
use std::cell::UnsafeCell;

// === Send ===
// 表示类型的值可以安全地跨线程转移所有权
// 大多数类型自动实现 Send
// Rc<T> 不实现 Send(引用计数不是原子的)

// === Sync ===
// 表示类型的引用可以安全地在多个线程间共享
// 如果 &T 是 Send,那么 T 就是 Sync
// RefCell<T> 不是 Sync(运行时借用检查不是线程安全的)

// 手动实现 Send 和 Sync 的例子
struct MyWrapper {
    // UnsafeCell 内部可变性,不自动实现 Sync
    data: UnsafeCell<i32>,
}

// SAFETY: MyWrapper 的内部 UnsafeCell 只在持有锁的情况下被访问
// (这里只是演示,实际需要确保线程安全的访问模式)
unsafe impl Send for MyWrapper {}
unsafe impl Sync for MyWrapper {}

// === GlobalAlloc ===
// 全局分配器 trait,也是 unsafe 的
// 实现者必须保证分配和释放的正确性

fn main() {
    // 验证某些类型的 Send/Sync 实现
    fn assert_send<T: Send>() {}
    fn assert_sync<T: Sync>() {}

    assert_send::<i32>();
    assert_send::<String>();
    assert_send::<Vec<i32>>();
    assert_sync::<i32>();
    assert_sync::<String>();

    // Rc 不是 Send
    // assert_send::<std::rc::Rc<i32>>();  // 编译错误

    // Arc 是 Send + Sync
    assert_send::<std::sync::Arc<i32>>();
    assert_sync::<std::sync::Arc<i32>>();

    println!("类型安全检查通过");
}
unsafe trait安全契约不实现的类型
Send值可以安全跨线程转移Rc<T>, *const T, *mut T
Sync引用可以安全跨线程共享RefCell<T>, Cell<T>, Rc<T>
GlobalAlloc分配/释放内存正确配对自定义分配器需手动实现

自定义 unsafe trait ​

rust
/// 一个 unsafe trait:保证类型可以安全地通过零初始化创建
///
/// # Safety
///
/// 实现者必须保证:将该类型的所有字节设为 0 后,得到的值是该类型的有效实例。
/// 例如,整数类型的全零是有效的(值为 0),但引用类型的全零是无效的(空引用)。
unsafe trait ZeroInit: Sized {
    fn zero() -> Self {
        // SAFETY: 实现者保证全零是有效值
        unsafe { std::mem::zeroed() }
    }
}

// SAFETY: i32 的全零表示值 0,是有效的 i32
unsafe impl ZeroInit for i32 {}

// SAFETY: f64 的全零表示 0.0,是有效的 f64
unsafe impl ZeroInit for f64 {}

// SAFETY: bool 的全零表示 false,是有效的 bool
unsafe impl ZeroInit for bool {}

// SAFETY: u8 数组的全零是有效的
unsafe impl ZeroInit for [u8; 16] {}

// 不能为 String 实现:全零的 String 有无效的内部指针
// 不能为 &T 实现:全零的引用是空引用,Rust 不允许
// 不能为 Vec<T> 实现:全零的 Vec 内部指针无效

fn create_default<T: ZeroInit>() -> T {
    T::zero()
}

fn main() {
    let n: i32 = create_default();
    println!("i32 零值: {}", n);

    let f: f64 = create_default();
    println!("f64 零值: {}", f);

    let b: bool = create_default();
    println!("bool 零值: {}", b);

    let arr: [u8; 16] = create_default();
    println!("数组零值: {:?}", arr);
}

unsafe trait 与普通 trait 的选择 ​

rust
// 普通 trait:编译器能验证实现的正确性
trait Printable {
    fn print(&self);
}

// 如果错误实现也不会导致内存不安全
struct Num(i32);
impl Printable for Num {
    fn print(&self) {
        println!("{}", self.0);
        // 即使这里写了错误的逻辑,也不会导致未定义行为
    }
}

// unsafe trait:错误实现可能导致未定义行为
/// # Safety
/// 实现者必须保证 as_bytes 返回的切片确实是 self 的有效内存表示,
/// 且 from_bytes 能正确地从这些字节重建出相同的值。
unsafe trait ByteRepr: Sized {
    fn as_bytes(&self) -> &[u8] {
        // SAFETY: 任何 Sized 类型都可以被视为字节切片
        // 但只有实现者保证这些字节的解释是正确的
        unsafe {
            std::slice::from_raw_parts(
                self as *const Self as *const u8,
                std::mem::size_of::<Self>(),
            )
        }
    }

    /// # Safety
    /// bytes 的长度必须等于 size_of::<Self>()
    unsafe fn from_bytes(bytes: &[u8]) -> Self {
        assert_eq!(bytes.len(), std::mem::size_of::<Self>());
        std::ptr::read(bytes.as_ptr() as *const Self)
    }
}

// SAFETY: i32 的内存表示是确定的,可以安全地序列化/反序列化
unsafe impl ByteRepr for i32 {}

// SAFETY: f32 的内存表示是确定的
unsafe impl ByteRepr for f32 {}

// 不能为 String 实现:String 包含指针,字节表示不能安全地跨进程使用

fn main() {
    let value: i32 = 42;
    let bytes = value.as_bytes();
    println!("i32 字节: {:?}", bytes);

    // SAFETY: bytes 来自有效的 i32,长度正确
    let restored: i32 = unsafe { i32::from_bytes(bytes) };
    println!("恢复: {}", restored);

    let pi: f32 = 3.14;
    let bytes = pi.as_bytes();
    println!("f32 字节: {:?}", bytes);

    let restored: f32 = unsafe { f32::from_bytes(bytes) };
    println!("恢复: {}", restored);
}

基本示例 ​

用 unsafe trait 实现一个类型安全的内存布局保证系统:

rust
/// 标记一个类型具有 C 兼容的内存布局
///
/// # Safety
///
/// 实现者必须保证:
/// 1. 类型使用 #[repr(C)] 或 #[repr(transparent)]
/// 2. 所有字段也满足 C 兼容布局
/// 3. 类型没有填充字节中的未定义值问题
unsafe trait CLayout: Sized {
    fn size() -> usize {
        std::mem::size_of::<Self>()
    }

    fn align() -> usize {
        std::mem::align_of::<Self>()
    }
}

// 基本类型天然满足 C 布局
// SAFETY: 基本整数类型的布局在 Rust 和 C 中相同
unsafe impl CLayout for i8 {}
unsafe impl CLayout for i16 {}
unsafe impl CLayout for i32 {}
unsafe impl CLayout for i64 {}
unsafe impl CLayout for u8 {}
unsafe impl CLayout for u16 {}
unsafe impl CLayout for u32 {}
unsafe impl CLayout for u64 {}
unsafe impl CLayout for f32 {}
unsafe impl CLayout for f64 {}

// 自定义 C 兼容结构体
#[repr(C)]
struct Point {
    x: f64,
    y: f64,
}

// SAFETY: Point 使用 #[repr(C)],所有字段(f64)满足 C 布局
unsafe impl CLayout for Point {}

#[repr(C)]
struct Color {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// SAFETY: Color 使用 #[repr(C)],所有字段(u8)满足 C 布局
unsafe impl CLayout for Color {}

// 只接受 C 兼容类型的序列化函数
fn serialize<T: CLayout>(value: &T) -> Vec<u8> {
    let size = T::size();
    let ptr = value as *const T as *const u8;
    // SAFETY: T 实现了 CLayout,保证有 C 兼容布局。
    // ptr 来自有效引用,size 是类型大小。
    let bytes = unsafe { std::slice::from_raw_parts(ptr, size) };
    bytes.to_vec()
}

fn deserialize<T: CLayout>(bytes: &[u8]) -> Option<T> {
    if bytes.len() != T::size() {
        return None;
    }

    // SAFETY: T 实现了 CLayout,bytes 长度正确。
    // 从有效的字节切片读取一个 T 值。
    let value = unsafe { std::ptr::read(bytes.as_ptr() as *const T) };
    Some(value)
}

fn main() {
    // 序列化 Point
    let point = Point { x: 1.5, y: 2.5 };
    let bytes = serialize(&point);
    println!("Point 大小: {} 字节, 对齐: {} 字节",
        Point::size(), Point::align());
    println!("Point 序列化: {} 字节", bytes.len());

    // 反序列化 Point
    let restored: Point = deserialize(&bytes).unwrap();
    println!("恢复: ({}, {})", restored.x, restored.y);

    // 序列化 Color
    let color = Color { r: 255, g: 128, b: 0, a: 255 };
    let bytes = serialize(&color);
    println!("\nColor 大小: {} 字节", Color::size());
    println!("Color 字节: {:?}", bytes);

    let restored: Color = deserialize(&bytes).unwrap();
    println!("恢复: rgba({}, {}, {}, {})",
        restored.r, restored.g, restored.b, restored.a);

    // 长度不匹配时返回 None
    let bad_bytes = vec![0u8; 3];
    let result: Option<i32> = deserialize(&bad_bytes);
    println!("\n错误长度: {:?}", result);  // None
}

常见问题 ​

问题一:什么时候应该用 unsafe trait 而不是普通 trait?

当错误的 trait 实现可能导致内存不安全(未定义行为)时使用 unsafe trait。如果错误实现只会导致逻辑错误(程序行为不符合预期但不会崩溃或内存损坏),用普通 trait 就够了。

问题二:Send 和 Sync 需要手动实现吗?

大多数情况下不需要——编译器会自动推导。只在使用了裸指针或 UnsafeCell 等类型,且你确信你的类型确实是线程安全的时候,才需要手动 unsafe impl Send 或 unsafe impl Sync。

问题三:unsafe trait 的方法是 unsafe 的吗?

不一定。unsafe trait 的方法可以是安全的。unsafe 标记在 trait 上表示实现者必须满足额外的安全契约,不影响方法本身的调用方式。当然,unsafe trait 也可以包含 unsafe 方法。

问题四:如何否定自动实现的 Send/Sync?

用 impl !Send for MyType {} 或在类型中包含 PhantomData<*const ()>(*const () 不是 Send 也不是 Sync)。

适用场景 ​

  • 线程安全标记:自定义类型的 Send/Sync 实现
  • 内存布局保证:标记类型有特定的内存布局
  • FFI 安全:标记类型可以安全地传递给 C 代码
  • 零初始化保证:标记类型可以安全地全零初始化

注意事项 ​

  • unsafe trait 的 # Safety 文档必须清楚说明实现者的责任
  • 错误实现 unsafe trait 可能导致未定义行为
  • 编译器自动推导的 Send/Sync 通常是正确的,谨慎覆盖
  • unsafe trait 的方法不一定是 unsafe 的
  • 实现 unsafe trait 需要 unsafe impl
  • 优先用普通 trait,只在必要时用 unsafe trait

总结 ​

unsafe trait 声明实现者必须满足编译器无法验证的安全契约。标准库中的 Send 和 Sync 是最典型的 unsafe trait——编译器自动推导大多数类型的实现,手动实现时需要 unsafe impl 并自行保证线程安全。声明 unsafe trait 时必须用 # Safety 文档说明实现者需要满足的条件。unsafe trait 适用于内存布局保证、FFI 安全、零初始化等场景。错误实现 unsafe trait 可能导致未定义行为,因此应谨慎使用,优先考虑普通 trait。