[ptr] Document maximum allocation size · rust-lang/rust@293b5cb (original) (raw)
`@@ -59,11 +59,39 @@
`
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 requiresa < 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
`//!
`