unsafe Trait
核心概念
unsafe trait 是一种特殊的 trait 声明方式,表示实现该 trait 的类型必须满足某些编译器无法自动验证的安全契约(invariant)。trait 被标记为 unsafe 不是因为它的方法有危险,而是因为实现者必须手动保证某些语义上的承诺。标准库中最典型的 unsafe trait 是 Send 和 Sync——编译器会自动推导大多数类型是否实现这两个 trait,但如果你用 unsafe impl 手动实现,就必须自己保证类型确实可以安全地跨线程发送或共享。
// 声明一个 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
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
/// 一个 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 的选择
// 普通 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 实现一个类型安全的内存布局保证系统:
/// 标记一个类型具有 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。