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