Skip to main content

UnsafePointerHandler

Struct UnsafePointerHandler 

Source
pub struct UnsafePointerHandler<T: ?Sized>(pub *mut T);
Expand description

一个持有类型化可变裸指针(*mut T)的包装结构,用于快捷地跨线程传递原始指针。

§设计意图

该类型允许将任意类型的可变裸指针包装起来,并在类型层面保留指针所指向的数据类型 T。 它本身不管理内存、不保证有效性、不提供生命周期关联——所有安全性均由调用者负责。 适合在需要绕过 Rust 所有权/借用检查,但又希望保持一定类型一致性的场景(如 FFI 或底层跨线程传递)。

§安全性总览

该类型的所有方法均为 unsafe,因为任何对裸指针的解引用、转换或地址操作都可能导致未定义行为。 使用前,调用者必须确保:

  • 指针所指向的内存区域在解引用时是有效的(已分配、未释放、且对齐正确)。
  • 若进行可变操作(as_mut_ptr、deref_mut),则必须保证不存在其它并发访问(包括读写), 除非使用了外部同步机制(如 Mutex、RwLock、原子操作等)。
  • 若跨线程传递,调用者需自行保证数据在线程间的同步,避免数据竞争和悬垂指针。
  • 指针不可为空(null),除非调用者明确将其用作标记且从不解引用。
  • 生命周期必须由调用者手动维护:确保在解引用时原始数据依然存活,且未发生 move 或 drop。
  • 泛型参数 T 必须与指针实际指向的类型完全匹配,否则转换或解引用将导致立即未定义行为。

§Send 与 Sync

该类型本身仅含有一个指针(机器字长),因此类型层面可自动满足 Send 和 Sync。 但这绝不意味着所指向的数据也是 Send/Sync。调用者必须确保跨线程使用时, 指针指向的数据符合相应的线程安全要求(例如使用 Arc<Mutex<T>> 或确保 T: Send + Sync)。

§示例

use std::thread;
use array_viewer::unsafe_pointer::UnsafePointerHandler;

let mut value = 42;
// 从可变指针创建处理器
let handler = unsafe { UnsafePointerHandler::from_mut_ptr(&mut value) };

let handle = thread::spawn(move || {
    unsafe {
        // 在新线程中获取可变引用并修改
        let mut_ref = handler.deref_mut();
        *mut_ref += 1;
    }
});
handle.join().unwrap();

// 主线程等待子线程结束,确保 value 在访问期间存活
assert_eq!(value, 43);

// 注意:若子线程在 value 生命周期外访问,将导致悬垂指针,调用者需自行避免。

Tuple Fields§

§0: *mut T

Implementations§

Source§

impl<T: ?Sized> UnsafePointerHandler<T>

Source

pub unsafe fn from_ptr(ptr: *const T) -> Self

从不可变裸指针创建处理器(内部转换为可变指针存储)。

§Safety

调用者必须保证 ptr 非空、有效且符合所有后续使用的安全性条件。 即使最初为 *const T,存储为 *mut T 并不会自动允许写操作,写操作仍需满足别名规则。

Source

pub unsafe fn from_mut_ptr(ptr: *mut T) -> Self

从可变裸指针创建处理器。

§Safety

同 from_ptr,且额外要求该指针允许可变访问且无其他别名。

Source

pub unsafe fn as_ptr(&self) -> *const T

获取存储的不可变指针(*const T)。

§Safety

返回的指针本身未经验证,调用者必须确保其有效,且不可用于可变访问(除非额外确保独占性)。

Source

pub unsafe fn as_mut_ptr(&self) -> *mut T

获取存储的可变指针(*mut T)。

§Safety

返回的指针未经验证,调用者必须确保该指针有效且满足独占可变访问的条件(无并发读写)。

Source

pub unsafe fn deref<'a>(&self) -> &'a T

不可变地解引用存储的指针,得到 &'a T。

§Safety
  • 指针必须非空且指向一个初始化的 T 实例。
  • 该实例在返回引用的生命周期 'a 内必须保持有效且不被修改(除非使用内部可变性)。
  • 不存在任何并发可变引用。
Source

pub unsafe fn deref_mut<'a>(&self) -> &'a mut T

可变地解引用存储的指针,得到 &'a mut T。

§Safety
  • 指针必须非空且指向一个初始化的 T 实例。
  • 在返回引用的生命周期 'a 内,该实例必须独占访问,不存在任何其它引用(包括不可变引用)。
  • 确保没有其它线程同时访问该数据(除非外部同步机制保证)。
Source

pub unsafe fn into_mut_ptr(self) -> *mut T

消费处理器,返回存储的可变裸指针。

§Safety

返回的指针不再受此包装约束,调用者需自行承担后续所有使用责任,确保有效性。

Source

pub unsafe fn into_ptr(self) -> *const T

消费处理器,返回存储的不可变裸指针。

§Safety

同上,返回的指针不再受包装约束,调用者需保证后续使用安全。

Source§

impl<T> UnsafePointerHandler<T>

Source

pub unsafe fn from_usize(addr: usize) -> Self

从 usize 地址值创建处理器,强制转换为 *mut T。

§Safety

调用者必须确保该地址确实是一个指向 T 的有效指针地址,且满足所有对齐、有效性条件。 此方法绕过了类型检查,风险极高,推荐仅在确知地址来源时使用。

Source

pub unsafe fn into_usize(self) -> usize

取出内部存储的 usize 地址值。

§Safety

此方法本身仅读取地址,但该地址后续可能被误用。调用者应意识到返回的地址可能已失效, 任何后续将其转回指针并解引用的操作都必须重新满足所有安全条件。

Source

pub unsafe fn null() -> Self

创建一个指向空(null)的处理器。

§Safety

创建空指针本身是安全的,但任何对该指针的解引用操作都将导致未定义行为。 此方法仅适用于需要显式表示“空”标记的场景,且调用者必须确保从不解引用它。

Trait Implementations§

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.