Rollup merge of #116675 - joshlf:patch-10, r=scottmcm · rust-lang/rust@74a78af (original) (raw)
`@@ -63,11 +63,39 @@
`
63
63
`//!
`
64
64
`//! ## Allocated object
`
65
65
`//!
`
66
``
`` -
//! For several operations, such as [offset] or field projections (expr.field), the notion of an
``
67
``
`-
//! "allocated object" becomes relevant. An allocated object is a contiguous region of memory.
`
68
``
`-
//! Common examples of allocated objects include stack-allocated variables (each variable is a
`
69
``
`-
//! separate allocated object), heap allocations (each allocation created by the global allocator is
`
70
``
`` -
//! a separate allocated object), and static variables.
``
``
66
`+
//! An allocated object is a subset of program memory which is addressable
`
``
67
`+
//! from Rust, and within which pointer arithmetic is possible. Examples of
`
``
68
`+
//! allocated objects include heap allocations, stack-allocated variables,
`
``
69
`+
//! statics, and consts. The safety preconditions of some Rust operations -
`
``
70
`` +
//! such as offset and field projections (expr.field) - are defined in
``
``
71
`+
//! terms of the allocated objects on which they operate.
`
``
72
`+
//!
`
``
73
`+
//! An allocated object has a base address, a size, and a set of memory
`
``
74
`+
//! addresses. It is possible for an allocated object to have zero size, but
`
``
75
`+
//! such an allocated object will still have a base address. The base address
`
``
76
`+
//! of an allocated object is not necessarily unique. While it is currently the
`
``
77
`+
//! case that an allocated object always has a set of memory addresses which is
`
``
78
`+
//! fully contiguous (i.e., has no "holes"), there is no guarantee that this
`
``
79
`+
//! will not change in the future.
`
``
80
`+
//!
`
``
81
`` +
//! For any allocated object with base address, size, and a set of
``
``
82
`` +
//! addresses, the following are guaranteed:
``
``
83
`` +
//! - For all addresses a in addresses, a is in the range `base .. (base +
``
``
84
`` +
//! size)(note that this requiresa < base + size, not a <= base + size`)
``
``
85
`` +
//! - base is not equal to [null()] (i.e., the address with the numerical
``
``
86
`+
//! value 0)
`
``
87
`` +
//! - base + size <= usize::MAX
``
``
88
`` +
//! - size <= isize::MAX
``
``
89
`+
//!
`
``
90
`` +
//! As a consequence of these guarantees, given any address a within the set
``
``
91
`+
//! of addresses of an allocated object:
`
``
92
`` +
//! - It is guaranteed that a - base does not overflow isize
``
``
93
`` +
//! - It is guaranteed that a - base is non-negative
``
``
94
`` +
//! - It is guaranteed that, given o = a - base (i.e., the offset of a within
``
``
95
`` +
//! the allocated object), base + o will not wrap around the address space (in
``
``
96
`` +
//! other words, will not overflow usize)
``
``
97
`+
//!
`
``
98
`` +
//! [null()]: null
``
71
99
`//!
`
72
100
`//! # Strict Provenance
`
73
101
`//!
`