实现 unsafe Trait ​

核心概念 ​

unsafe impl 是实现 unsafe trait 的语法。当你写 unsafe impl SomeTrait for MyType 时,你在向编译器和其他开发者承诺:你已经手动验证了 MyType 满足 SomeTrait 要求的所有安全契约。编译器不会检查这些契约是否真的被满足——这完全是程序员的责任。如果承诺是错误的,使用这个 trait 实现的代码可能会产生未定义行为。最常见的 unsafe impl 是为自定义类型手动实现 Send 和 Sync。

rust
use std::cell::UnsafeCell;

// 一个使用 UnsafeCell 的自定义类型
// UnsafeCell 不自动实现 Sync
struct SharedCounter {
    value: UnsafeCell<u64>,
}

// 手动实现 Sync
// SAFETY: SharedCounter 在多线程环境中的访问由外部锁保护,
// 保证同一时刻只有一个线程能修改 value。
// (实际项目中应使用 Mutex 或 AtomicU64,这里仅用于演示)
unsafe impl Sync for SharedCounter {}

// Send 也需要手动实现(UnsafeCell 的存在阻止了自动推导)
// SAFETY: SharedCounter 不包含线程局部数据,可以安全转移到其他线程。
unsafe impl Send for SharedCounter {}

impl SharedCounter {
    fn new(value: u64) -> Self {
        SharedCounter {
            value: UnsafeCell::new(value),
        }
    }

    // 注意:这个方法本身不是线程安全的
    // 调用者必须确保不会有数据竞争
    fn get(&self) -> u64 {
        // SAFETY: 调用者保证没有并发写入
        unsafe { *self.value.get() }
    }

    fn set(&self, val: u64) {
        // SAFETY: 调用者保证没有并发读写
        unsafe { *self.value.get() = val; }
    }
}

fn main() {
    let counter = SharedCounter::new(0);
    counter.set(42);
    println!("计数器: {}", counter.get());
}

实现 Send 和 Sync ​

rust
use std::sync::Arc;
use std::thread;

// 包含裸指针的类型,编译器不会自动实现 Send/Sync
struct RawBuffer {
    ptr: *mut u8,
    len: usize,
}

// SAFETY: RawBuffer 拥有 ptr 指向的内存的独占所有权,
// 内存不与其他线程共享,转移 RawBuffer 就是转移整块内存的所有权。
unsafe impl Send for RawBuffer {}

// 不实现 Sync:通过 &RawBuffer 可以获取 *mut u8,
// 多线程同时持有 *mut u8 可能导致数据竞争。
// 如果需要共享,应该加锁。

impl RawBuffer {
    fn new(len: usize) -> Self {
        let layout = std::alloc::Layout::from_size_align(len, 1).unwrap();
        // SAFETY: layout 的 size > 0
        let ptr = unsafe { std::alloc::alloc(layout) };
        if ptr.is_null() {
            panic!("分配失败");
        }
        RawBuffer { ptr, len }
    }

    fn write(&mut self, offset: usize, data: &[u8]) {
        assert!(offset + data.len() <= self.len);
        // SAFETY: 已检查边界,ptr 有效
        unsafe {
            std::ptr::copy_nonoverlapping(data.as_ptr(), self.ptr.add(offset), data.len());
        }
    }

    fn read(&self, offset: usize, len: usize) -> Vec<u8> {
        assert!(offset + len <= self.len);
        let mut result = vec![0u8; len];
        // SAFETY: 已检查边界,ptr 有效
        unsafe {
            std::ptr::copy_nonoverlapping(self.ptr.add(offset), result.as_mut_ptr(), len);
        }
        result
    }
}

impl Drop for RawBuffer {
    fn drop(&mut self) {
        let layout = std::alloc::Layout::from_size_align(self.len, 1).unwrap();
        // SAFETY: ptr 和 layout 在 new 中通过 alloc 获得
        unsafe {
            std::alloc::dealloc(self.ptr, layout);
        }
    }
}

fn main() {
    // RawBuffer 可以跨线程转移(因为实现了 Send)
    let mut buf = RawBuffer::new(64);
    buf.write(0, b"Hello from main thread");

    let handle = thread::spawn(move || {
        // buf 的所有权转移到新线程
        let data = buf.read(0, 22);
        println!("子线程读取: {}", String::from_utf8_lossy(&data));

        // buf 在这个线程中被 drop
    });

    handle.join().unwrap();
}

实现自定义 unsafe trait ​

rust
/// 标记类型可以安全地被复制为原始字节
///
/// # Safety
///
/// 实现者必须保证:
/// 1. 类型不包含指针、引用或其他间接引用
/// 2. 类型不包含 padding 字节中的敏感信息
/// 3. 任何位模式都是该类型的有效值
unsafe trait Pod: Copy + Sized {
    fn as_bytes(&self) -> &[u8] {
        // SAFETY: Pod 类型的任何位模式都有效
        unsafe {
            std::slice::from_raw_parts(
                self as *const Self as *const u8,
                std::mem::size_of::<Self>(),
            )
        }
    }

    fn from_bytes(bytes: &[u8]) -> Option<Self> {
        if bytes.len() != std::mem::size_of::<Self>() {
            return None;
        }
        // SAFETY: Pod 类型的任何位模式都有效,长度已检查
        Some(unsafe { std::ptr::read(bytes.as_ptr() as *const Self) })
    }
}

// SAFETY: i32 不包含指针,任何 4 字节的位模式都是有效的 i32
unsafe impl Pod for i32 {}

// SAFETY: u8 不包含指针,任何 1 字节的位模式都是有效的 u8
unsafe impl Pod for u8 {}

// SAFETY: f32 不包含指针(NaN 等特殊值也是有效的 f32)
unsafe impl Pod for f32 {}

// SAFETY: [u8; N] 不包含指针,任何位模式都有效
unsafe impl Pod for [u8; 4] {}

#[derive(Copy, Clone)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// SAFETY: Pixel 是 #[repr(C)],所有字段是 u8(Pod),
// 没有 padding,任何位模式都有效
unsafe impl Pod for Pixel {}

// 不能为 String 实现:包含指针
// 不能为 bool 实现:只有 0 和 1 是有效值
// 不能为 &T 实现:是引用

fn round_trip<T: Pod + std::fmt::Debug>(val: T) {
    let bytes = val.as_bytes();
    let restored = T::from_bytes(bytes).unwrap();
    println!("原始: {:?} → 字节: {:?} → 恢复: {:?}", val, bytes, restored);
}

fn main() {
    round_trip(42_i32);
    round_trip(3.14_f32);
    round_trip([1u8, 2, 3, 4]);

    let pixel = Pixel { r: 255, g: 128, b: 0, a: 255 };
    let bytes = pixel.as_bytes();
    println!("\nPixel 字节: {:?}", bytes);

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

错误实现的后果 ​

rust
// 演示错误实现 unsafe trait 的危险性(这段代码是反面教材)

// 假设有一个 unsafe trait 要求类型是线程安全的
unsafe trait ThreadSafe {}

// 错误的实现:Rc 不是线程安全的
// 如果写了 unsafe impl ThreadSafe for Rc<T> {}
// 在多线程中使用 Rc 会导致数据竞争(引用计数不是原子的)

// 正确做法:只为真正线程安全的类型实现
use std::sync::Arc;
use std::sync::atomic::{AtomicU32, Ordering};

struct SafeCounter {
    count: AtomicU32,
}

// SAFETY: AtomicU32 使用原子操作,天然线程安全
unsafe impl ThreadSafe for SafeCounter {}

impl SafeCounter {
    fn new() -> Self {
        SafeCounter { count: AtomicU32::new(0) }
    }

    fn increment(&self) {
        self.count.fetch_add(1, Ordering::SeqCst);
    }

    fn get(&self) -> u32 {
        self.count.load(Ordering::SeqCst)
    }
}

fn main() {
    use std::thread;

    let counter = Arc::new(SafeCounter::new());
    let mut handles = Vec::new();

    for _ in 0..10 {
        let c = Arc::clone(&counter);
        handles.push(thread::spawn(move || {
            for _ in 0..1000 {
                c.increment();
            }
        }));
    }

    for h in handles {
        h.join().unwrap();
    }

    println!("最终计数: {} (预期: 10000)", counter.get());
}

基本示例 ​

完整展示 unsafe impl 在实际项目中的使用:

rust
use std::alloc::{alloc, dealloc, Layout};

/// 固定大小的类型安全内存块
///
/// # Safety
///
/// 实现 TypedBlock 的类型必须保证:
/// - size() 返回的大小足够存放该类型的值
/// - align() 返回正确的对齐要求
unsafe trait TypedBlock: Sized {
    fn size() -> usize { std::mem::size_of::<Self>() }
    fn align() -> usize { std::mem::align_of::<Self>() }
}

// SAFETY: 基本类型的大小和对齐由默认实现正确计算
unsafe impl TypedBlock for u8 {}
unsafe impl TypedBlock for u16 {}
unsafe impl TypedBlock for u32 {}
unsafe impl TypedBlock for u64 {}
unsafe impl TypedBlock for i32 {}
unsafe impl TypedBlock for f32 {}
unsafe impl TypedBlock for f64 {}

#[derive(Debug, Clone, Copy)]
#[repr(C)]
struct Vec3 {
    x: f32,
    y: f32,
    z: f32,
}

// SAFETY: Vec3 是 #[repr(C)] 的简单结构体,
// 默认的 size() 和 align() 实现正确
unsafe impl TypedBlock for Vec3 {}

/// 类型安全的堆分配块
struct HeapBlock<T: TypedBlock> {
    ptr: *mut T,
    layout: Layout,
}

impl<T: TypedBlock> HeapBlock<T> {
    fn new(value: T) -> Self {
        let layout = Layout::from_size_align(T::size(), T::align()).unwrap();

        // SAFETY: layout 来自有效的 TypedBlock 实现
        let ptr = unsafe { alloc(layout) as *mut T };
        if ptr.is_null() {
            panic!("分配失败");
        }

        // SAFETY: ptr 来自 alloc,大小和对齐正确
        unsafe { std::ptr::write(ptr, value); }

        HeapBlock { ptr, layout }
    }

    fn get(&self) -> &T {
        // SAFETY: ptr 在 new 中被正确初始化,且未被释放
        unsafe { &*self.ptr }
    }

    fn get_mut(&mut self) -> &mut T {
        // SAFETY: 我们有独占访问权(&mut self)
        unsafe { &mut *self.ptr }
    }

    fn into_inner(self) -> T {
        // SAFETY: ptr 指向有效的 T 值
        let value = unsafe { std::ptr::read(self.ptr) };
        // 释放内存但不 drop value(已经被 read 取出)
        // SAFETY: ptr 和 layout 来自 new 中的 alloc
        unsafe { dealloc(self.ptr as *mut u8, self.layout); }
        // 阻止 Drop 再次释放
        std::mem::forget(self);
        value
    }
}

impl<T: TypedBlock> Drop for HeapBlock<T> {
    fn drop(&mut self) {
        // SAFETY: ptr 指向有效的 T 值,drop 后释放内存
        unsafe {
            std::ptr::drop_in_place(self.ptr);
            dealloc(self.ptr as *mut u8, self.layout);
        }
    }
}

// SAFETY: 如果 T 是 Send,HeapBlock<T> 也可以跨线程转移
// 因为它拥有 T 的独占所有权
unsafe impl<T: TypedBlock + Send> Send for HeapBlock<T> {}

fn main() {
    // 基本类型
    let block = HeapBlock::new(42_i32);
    println!("i32 block: {}", block.get());
    println!("  大小: {} 字节, 对齐: {} 字节", i32::size(), i32::align());

    // 修改
    let mut block = HeapBlock::new(3.14_f64);
    *block.get_mut() = 2.718;
    println!("f64 block: {}", block.get());

    // 取出值
    let block = HeapBlock::new(Vec3 { x: 1.0, y: 2.0, z: 3.0 });
    println!("Vec3 block: {:?}", block.get());
    let vec3 = block.into_inner();
    println!("取出: {:?}", vec3);
    println!("  大小: {} 字节, 对齐: {} 字节", Vec3::size(), Vec3::align());

    // 跨线程
    let block = HeapBlock::new(100_u64);
    let handle = std::thread::spawn(move || {
        println!("子线程: {}", block.get());
    });
    handle.join().unwrap();
}

常见问题 ​

问题一:unsafe impl 和普通 impl 有什么区别?

unsafe impl 只用于 unsafe trait。它表示程序员手动保证类型满足 trait 的安全契约。普通 impl 用于普通 trait,编译器验证实现的正确性。

问题二:什么时候需要手动实现 Send/Sync?

当类型包含裸指针(*const T、*mut T)或 UnsafeCell 时,编译器不会自动推导 Send/Sync。如果你确信类型实际上是线程安全的,可以手动 unsafe impl。

问题三:错误的 unsafe impl 会被编译器发现吗?

不会。编译器不检查 unsafe trait 的安全契约是否被满足。错误的实现可能在运行时导致数据竞争、内存损坏等未定义行为。

问题四:可以为外部类型实现 unsafe trait 吗?

受孤儿规则限制——要么 trait 是你定义的,要么类型是你定义的。不能为标准库类型实现外部 crate 的 unsafe trait。

适用场景 ​

  • 线程安全标记:为含裸指针的类型实现 Send/Sync
  • FFI 类型:标记 C 兼容类型的安全属性
  • 自定义抽象:实现自定义的 unsafe trait
  • 底层库:编写底层数据结构和分配器

注意事项 ​

  • unsafe impl 必须附带 SAFETY 注释说明为什么实现是正确的
  • 编译器不验证 unsafe trait 的安全契约
  • 错误的 unsafe impl Send/Sync 可能导致数据竞争
  • 优先依赖编译器自动推导 Send/Sync
  • 手动实现前确认类型确实满足安全要求
  • 代码审查应重点关注 unsafe impl 的正确性

总结 ​

unsafe impl 用于实现 unsafe trait,表示程序员手动保证类型满足 trait 的安全契约。编译器不会验证这些契约——错误的实现可能导致未定义行为。最常见的场景是为包含裸指针或 UnsafeCell 的类型手动实现 Send 和 Sync。每个 unsafe impl 都应附带 SAFETY 注释,说明为什么实现是正确的。应优先依赖编译器的自动推导,只在自动推导无法满足需求且确信类型安全时才使用 unsafe impl。代码审查中 unsafe impl 是重点审查对象。