Skip to content

Commit 9469575

Browse files
committed
restate GlobalAlloc method safety preconditions in terms of what the caller has to do for greater clarity
1 parent 2699de6 commit 9469575

File tree

1 file changed

+17
-15
lines changed

1 file changed

+17
-15
lines changed

core/src/alloc/global.rs

+17-15
Original file line numberDiff line numberDiff line change
@@ -124,8 +124,8 @@ pub unsafe trait GlobalAlloc {
124124
///
125125
/// # Safety
126126
///
127-
/// This function is unsafe because undefined behavior can result
128-
/// if the caller does not ensure that `layout` has non-zero size.
127+
/// `layout` must have non-zero size. Attempting to allocate for a zero-sized `layout` may
128+
/// result in undefined behavior.
129129
///
130130
/// (Extension subtraits might provide more specific bounds on
131131
/// behavior, e.g., guarantee a sentinel address or a null pointer
@@ -156,14 +156,14 @@ pub unsafe trait GlobalAlloc {
156156
///
157157
/// # Safety
158158
///
159-
/// This function is unsafe because undefined behavior can result
160-
/// if the caller does not ensure all of the following:
159+
/// The caller must ensure:
161160
///
162-
/// * `ptr` must denote a block of memory currently allocated via
163-
/// this allocator,
161+
/// * `ptr` is a block of memory currently allocated via this allocator and,
164162
///
165-
/// * `layout` must be the same layout that was used
166-
/// to allocate that block of memory.
163+
/// * `layout` is the same layout that was used to allocate that block of
164+
/// memory.
165+
///
166+
/// Otherwise undefined behavior can result.
167167
#[stable(feature = "global_alloc", since = "1.28.0")]
168168
unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout);
169169

@@ -172,7 +172,8 @@ pub unsafe trait GlobalAlloc {
172172
///
173173
/// # Safety
174174
///
175-
/// This function is unsafe for the same reasons that `alloc` is.
175+
/// The caller has to ensure that `layout` has non-zero size. Like `alloc`
176+
/// zero sized `layout` can result in undefined behaviour.
176177
/// However the allocated block of memory is guaranteed to be initialized.
177178
///
178179
/// # Errors
@@ -220,20 +221,21 @@ pub unsafe trait GlobalAlloc {
220221
///
221222
/// # Safety
222223
///
223-
/// This function is unsafe because undefined behavior can result
224-
/// if the caller does not ensure all of the following:
224+
/// The caller must ensure that:
225225
///
226-
/// * `ptr` must be currently allocated via this allocator,
226+
/// * `ptr` is allocated via this allocator,
227227
///
228-
/// * `layout` must be the same layout that was used
228+
/// * `layout` is the same layout that was used
229229
/// to allocate that block of memory,
230230
///
231-
/// * `new_size` must be greater than zero.
231+
/// * `new_size` is greater than zero.
232232
///
233233
/// * `new_size`, when rounded up to the nearest multiple of `layout.align()`,
234-
/// must not overflow `isize` (i.e., the rounded value must be less than or
234+
/// does not overflow `isize` (i.e., the rounded value must be less than or
235235
/// equal to `isize::MAX`).
236236
///
237+
/// If these are not followed, undefined behaviour can result.
238+
///
237239
/// (Extension subtraits might provide more specific bounds on
238240
/// behavior, e.g., guarantee a sentinel address or a null pointer
239241
/// in response to a zero-size allocation request.)

0 commit comments

Comments
 (0)