Module std::ptr

通过裸指针手动管理内存。

See also the pointer primitive types.

Safety

该模块中的许多函数都将裸指针作为参数，并对其进行读取或写入。为了安全起见，这些指针必须是 valid。 指针是否有效取决于指针用于 (读或写) 的操作以及所访问的内存范围 (即 read/written 多少个字节)。 大多数函数使用 *mut T 和 * const T 来访问单个值，在这种情况下，文档将忽略该大小，并隐式地假定其为 size_of::<T>() 字节。

有效性的确切规则尚未确定。此时提供的保证非常小:

• null 指针从来都是无效的，甚至对于 大小为零 的访问也是无效的。
• 为了使指针有效，有必要 (但并不总是足够) 使指针 可引用: 从指针开始的给定大小的内存范围必须全部在单个已分配对象的范围内。 请注意，在 Rust 中，每个 (stack-allocated) 变量都被视为一个单独的分配对象。
• 即使对于 大小为零 的操作，指针也不得指向已释放的内存，即，即使对于大小为零的操作，释放也会使指针无效。 但是，将任何非零整数 字面量 强制转换为指针对于零大小的访问都是有效的，即使该地址恰好存在一些内存并被释放了。 这相当于编写自己的分配器: 分配零大小的对象不是很困难。 获得对零大小访问有效的指针的规范方法是 NonNull::dangling。
• 在用于在线程之间同步的 atomic operations 的意义上，此模块中的函数执行的所有访问都是非原子的。 这意味着从两个不同的线程对同一位置执行两次并发访问是一种未定义的行为，除非两个访问均仅从内存中读取。 请注意，这明确包含 read_volatile 和 write_volatile: 易失性访问不能用于线程间同步。
• 只要基础对象处于活动状态，并且不使用引用 (仅裸指针) 来访问同一内存，则对指针进行强制引用的结果是有效的。

这些公理，以及仔细地使用 offset 进行指针算术，足以在不安全的代码中正确实现许多有用的东西。随着 aliasing 规则的确定，最终将提供更强有力的保证。 有关更多信息，请参见 书籍 以及专门针对 未定义的行为 的引用中的部分。

Alignment

上面定义的有效裸指针不一定正确对齐 (其中 “proper” 对齐由 pointee 类型定义，即 *const T 必须与 mem::align_of::<T>() 对齐)。 但是，大多数函数要求其参数正确对齐，并将在其文档中明确说明此要求。 read_unaligned 和 write_unaligned 除外。

当一个函数需要适当的对齐时，即使访问的大小为 0，即实际上没有触摸到内存，它也需要进行适当的对齐。在这种情况下，请考虑使用 NonNull::dangling。

分配对象

对于一些操作，例如 offset 或 projection (expr.field)，“allocated object” 的概念变得相关。分配的对象是一个连续的内存区域。 分配对象的常见示例包括栈分配变量 (每个变量都是一个单独的分配对象)、堆分配 (每个分配器创建的分配都是一个单独的分配对象) 和 static 变量。

Macros

addr_of	创建一个 const 裸指针到一个位置，而无需创建中间引用。
addr_of_mut	创建一个 mut 裸指针到一个位置，而无需创建中间引用。

Structs

DynMetadata	Experimental Dyn = dyn SomeTrait trait 对象类型的元数据。
NonNull	*mut T 但非零且协变。

Traits

Pointee

Experimental 提供任何指向类型的指针元数据类型。

Functions

from_raw_parts	Experimental 根据数据地址和元数据形成 (possibly-wide) 裸指针。
from_raw_parts_mut	Experimental 执行与 from_raw_parts 相同的功能，除了返回原始 *mut 指针 (与原始 * const 指针相反) 之外。
metadata	Experimental 提取指针的元数据组件。
copy⚠	将 count * size_of::<T>() 字节从 src 复制到 dst。源和目标可能会重叠。
copy_nonoverlapping⚠	将 count * size_of::<T>() 字节从 src 复制到 dst。源和目标必须不重叠。
drop_in_place⚠	执行指向值的析构函数 (如果有)。
eq	比较裸指针是否相等。
hash	散列一个裸指针。
null	创建一个空的裸指针。
null_mut	创建一个空的可变裸露指针。
read⚠	从 src 读取值而不移动它。这将使 src 中的内存保持不变。
read_unaligned⚠	从 src 读取值而不移动它。这将使 src 中的内存保持不变。
read_volatile⚠	对 src 的值进行易失性读取，而无需移动它。这将使 src 中的内存保持不变。
replace⚠	将 src 移至指定的 dst，返回先前的 dst 值。
slice_from_raw_parts	根据指针和长度形成原始切片。
slice_from_raw_parts_mut	执行与 slice_from_raw_parts 相同的功能，但返回的是原始可变切片，而不是原始的不可变切片。
swap⚠	在相同类型的两个可变位置交换值，而无需取消初始化任何一个。
swap_nonoverlapping⚠	从 x 和 y 开始在两个内存区域之间交换 count * size_of::<T>() 字节。 这两个区域必须 不能 重叠。
write⚠	用给定值覆盖存储位置，而无需读取或丢弃旧值。
write_bytes⚠	将从 dst 开始的 count * size_of::<T>() 内存字节设置为 val。
write_unaligned⚠	用给定值覆盖存储位置，而无需读取或丢弃旧值。
write_volatile⚠	使用给定值对存储单元执行易失性写操作，而无需读取或丢弃旧值。