1//! Memory allocation APIs
2
3#![stable(feature = "alloc_module", since = "1.28.0")]
4
5mod global;
6mod layout;
7
8#[stable(feature = "global_alloc", since = "1.28.0")]
9pub use self::global::GlobalAlloc;
10#[stable(feature = "alloc_layout", since = "1.28.0")]
11pub use self::layout::Layout;
12#[stable(feature = "alloc_layout", since = "1.28.0")]
13#[deprecated(
14 since = "1.52.0",
15 note = "Name does not follow std convention, use LayoutError",
16 suggestion = "LayoutError"
17)]
18#[allow(deprecated, deprecated_in_future)]
19pub use self::layout::LayoutErr;
20
21#[stable(feature = "alloc_layout_error", since = "1.50.0")]
22pub use self::layout::LayoutError;
23
24use crate::error::Error;
25use crate::fmt;
26use crate::ptr::{self, NonNull};
27
28/// The `AllocError` error indicates an allocation failure
29/// that may be due to resource exhaustion or to
30/// something wrong when combining the given input arguments with this
31/// allocator.
32#[unstable(feature = "allocator_api", issue = "32838")]
33#[derive(Copy, Clone, PartialEq, Eq, Debug)]
34pub struct AllocError;
35
36#[unstable(
37 feature = "allocator_api",
38 reason = "the precise API and guarantees it provides may be tweaked.",
39 issue = "32838"
40)]
41impl Error for AllocError {}
42
43// (we need this for downstream impl of trait Error)
44#[unstable(feature = "allocator_api", issue = "32838")]
45impl fmt::Display for AllocError {
46 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47 f.write_str(data:"memory allocation failed")
48 }
49}
50
51/// An implementation of `Allocator` can allocate, grow, shrink, and deallocate arbitrary blocks of
52/// data described via [`Layout`][].
53///
54/// `Allocator` is designed to be implemented on ZSTs, references, or smart pointers because having
55/// an allocator like `MyAlloc([u8; N])` cannot be moved, without updating the pointers to the
56/// allocated memory.
57///
58/// Unlike [`GlobalAlloc`][], zero-sized allocations are allowed in `Allocator`. If an underlying
59/// allocator does not support this (like jemalloc) or return a null pointer (such as
60/// `libc::malloc`), this must be caught by the implementation.
61///
62/// ### Currently allocated memory
63///
64/// Some of the methods require that a memory block be *currently allocated* via an allocator. This
65/// means that:
66///
67/// * the starting address for that memory block was previously returned by [`allocate`], [`grow`], or
68/// [`shrink`], and
69///
70/// * the memory block has not been subsequently deallocated, where blocks are either deallocated
71/// directly by being passed to [`deallocate`] or were changed by being passed to [`grow`] or
72/// [`shrink`] that returns `Ok`. If `grow` or `shrink` have returned `Err`, the passed pointer
73/// remains valid.
74///
75/// [`allocate`]: Allocator::allocate
76/// [`grow`]: Allocator::grow
77/// [`shrink`]: Allocator::shrink
78/// [`deallocate`]: Allocator::deallocate
79///
80/// ### Memory fitting
81///
82/// Some of the methods require that a layout *fit* a memory block. What it means for a layout to
83/// "fit" a memory block means (or equivalently, for a memory block to "fit" a layout) is that the
84/// following conditions must hold:
85///
86/// * The block must be allocated with the same alignment as [`layout.align()`], and
87///
88/// * The provided [`layout.size()`] must fall in the range `min ..= max`, where:
89/// - `min` is the size of the layout most recently used to allocate the block, and
90/// - `max` is the latest actual size returned from [`allocate`], [`grow`], or [`shrink`].
91///
92/// [`layout.align()`]: Layout::align
93/// [`layout.size()`]: Layout::size
94///
95/// # Safety
96///
97/// * Memory blocks returned from an allocator that are [*currently allocated*] must point to
98/// valid memory and retain their validity while they are [*currently allocated*] and the shorter
99/// of:
100/// - the borrow-checker lifetime of the allocator type itself.
101/// - as long as at least one of the instance and all of its clones has not been dropped.
102///
103/// * copying, cloning, or moving the allocator must not invalidate memory blocks returned from this
104/// allocator. A copied or cloned allocator must behave like the same allocator, and
105///
106/// * any pointer to a memory block which is [*currently allocated*] may be passed to any other
107/// method of the allocator.
108///
109/// [*currently allocated*]: #currently-allocated-memory
110#[unstable(feature = "allocator_api", issue = "32838")]
111pub unsafe trait Allocator {
112 /// Attempts to allocate a block of memory.
113 ///
114 /// On success, returns a [`NonNull<[u8]>`][NonNull] meeting the size and alignment guarantees of `layout`.
115 ///
116 /// The returned block may have a larger size than specified by `layout.size()`, and may or may
117 /// not have its contents initialized.
118 ///
119 /// The returned block of memory remains valid as long as it is [*currently allocated*] and the shorter of:
120 /// - the borrow-checker lifetime of the allocator type itself.
121 /// - as long as at the allocator and all its clones has not been dropped.
122 ///
123 /// # Errors
124 ///
125 /// Returning `Err` indicates that either memory is exhausted or `layout` does not meet
126 /// allocator's size or alignment constraints.
127 ///
128 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
129 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
130 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
131 ///
132 /// Clients wishing to abort computation in response to an allocation error are encouraged to
133 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
134 ///
135 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
136 fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>;
137
138 /// Behaves like `allocate`, but also ensures that the returned memory is zero-initialized.
139 ///
140 /// # Errors
141 ///
142 /// Returning `Err` indicates that either memory is exhausted or `layout` does not meet
143 /// allocator's size or alignment constraints.
144 ///
145 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
146 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
147 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
148 ///
149 /// Clients wishing to abort computation in response to an allocation error are encouraged to
150 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
151 ///
152 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
153 fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
154 let ptr = self.allocate(layout)?;
155 // SAFETY: `alloc` returns a valid memory block
156 unsafe { ptr.as_non_null_ptr().as_ptr().write_bytes(0, ptr.len()) }
157 Ok(ptr)
158 }
159
160 /// Deallocates the memory referenced by `ptr`.
161 ///
162 /// # Safety
163 ///
164 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator, and
165 /// * `layout` must [*fit*] that block of memory.
166 ///
167 /// [*currently allocated*]: #currently-allocated-memory
168 /// [*fit*]: #memory-fitting
169 unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout);
170
171 /// Attempts to extend the memory block.
172 ///
173 /// Returns a new [`NonNull<[u8]>`][NonNull] containing a pointer and the actual size of the allocated
174 /// memory. The pointer is suitable for holding data described by `new_layout`. To accomplish
175 /// this, the allocator may extend the allocation referenced by `ptr` to fit the new layout.
176 ///
177 /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been
178 /// transferred to this allocator. Any access to the old `ptr` is Undefined Behavior, even if the
179 /// allocation was grown in-place. The newly returned pointer is the only valid pointer
180 /// for accessing this memory now.
181 ///
182 /// If this method returns `Err`, then ownership of the memory block has not been transferred to
183 /// this allocator, and the contents of the memory block are unaltered.
184 ///
185 /// # Safety
186 ///
187 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator.
188 /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.).
189 /// * `new_layout.size()` must be greater than or equal to `old_layout.size()`.
190 ///
191 /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
192 ///
193 /// [*currently allocated*]: #currently-allocated-memory
194 /// [*fit*]: #memory-fitting
195 ///
196 /// # Errors
197 ///
198 /// Returns `Err` if the new layout does not meet the allocator's size and alignment
199 /// constraints of the allocator, or if growing otherwise fails.
200 ///
201 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
202 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
203 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
204 ///
205 /// Clients wishing to abort computation in response to an allocation error are encouraged to
206 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
207 ///
208 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
209 unsafe fn grow(
210 &self,
211 ptr: NonNull<u8>,
212 old_layout: Layout,
213 new_layout: Layout,
214 ) -> Result<NonNull<[u8]>, AllocError> {
215 debug_assert!(
216 new_layout.size() >= old_layout.size(),
217 "`new_layout.size()` must be greater than or equal to `old_layout.size()`"
218 );
219
220 let new_ptr = self.allocate(new_layout)?;
221
222 // SAFETY: because `new_layout.size()` must be greater than or equal to
223 // `old_layout.size()`, both the old and new memory allocation are valid for reads and
224 // writes for `old_layout.size()` bytes. Also, because the old allocation wasn't yet
225 // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is
226 // safe. The safety contract for `dealloc` must be upheld by the caller.
227 unsafe {
228 ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), old_layout.size());
229 self.deallocate(ptr, old_layout);
230 }
231
232 Ok(new_ptr)
233 }
234
235 /// Behaves like `grow`, but also ensures that the new contents are set to zero before being
236 /// returned.
237 ///
238 /// The memory block will contain the following contents after a successful call to
239 /// `grow_zeroed`:
240 /// * Bytes `0..old_layout.size()` are preserved from the original allocation.
241 /// * Bytes `old_layout.size()..old_size` will either be preserved or zeroed, depending on
242 /// the allocator implementation. `old_size` refers to the size of the memory block prior
243 /// to the `grow_zeroed` call, which may be larger than the size that was originally
244 /// requested when it was allocated.
245 /// * Bytes `old_size..new_size` are zeroed. `new_size` refers to the size of the memory
246 /// block returned by the `grow_zeroed` call.
247 ///
248 /// # Safety
249 ///
250 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator.
251 /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.).
252 /// * `new_layout.size()` must be greater than or equal to `old_layout.size()`.
253 ///
254 /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
255 ///
256 /// [*currently allocated*]: #currently-allocated-memory
257 /// [*fit*]: #memory-fitting
258 ///
259 /// # Errors
260 ///
261 /// Returns `Err` if the new layout does not meet the allocator's size and alignment
262 /// constraints of the allocator, or if growing otherwise fails.
263 ///
264 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
265 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
266 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
267 ///
268 /// Clients wishing to abort computation in response to an allocation error are encouraged to
269 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
270 ///
271 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
272 unsafe fn grow_zeroed(
273 &self,
274 ptr: NonNull<u8>,
275 old_layout: Layout,
276 new_layout: Layout,
277 ) -> Result<NonNull<[u8]>, AllocError> {
278 debug_assert!(
279 new_layout.size() >= old_layout.size(),
280 "`new_layout.size()` must be greater than or equal to `old_layout.size()`"
281 );
282
283 let new_ptr = self.allocate_zeroed(new_layout)?;
284
285 // SAFETY: because `new_layout.size()` must be greater than or equal to
286 // `old_layout.size()`, both the old and new memory allocation are valid for reads and
287 // writes for `old_layout.size()` bytes. Also, because the old allocation wasn't yet
288 // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is
289 // safe. The safety contract for `dealloc` must be upheld by the caller.
290 unsafe {
291 ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), old_layout.size());
292 self.deallocate(ptr, old_layout);
293 }
294
295 Ok(new_ptr)
296 }
297
298 /// Attempts to shrink the memory block.
299 ///
300 /// Returns a new [`NonNull<[u8]>`][NonNull] containing a pointer and the actual size of the allocated
301 /// memory. The pointer is suitable for holding data described by `new_layout`. To accomplish
302 /// this, the allocator may shrink the allocation referenced by `ptr` to fit the new layout.
303 ///
304 /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been
305 /// transferred to this allocator. Any access to the old `ptr` is Undefined Behavior, even if the
306 /// allocation was shrunk in-place. The newly returned pointer is the only valid pointer
307 /// for accessing this memory now.
308 ///
309 /// If this method returns `Err`, then ownership of the memory block has not been transferred to
310 /// this allocator, and the contents of the memory block are unaltered.
311 ///
312 /// # Safety
313 ///
314 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator.
315 /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.).
316 /// * `new_layout.size()` must be smaller than or equal to `old_layout.size()`.
317 ///
318 /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
319 ///
320 /// [*currently allocated*]: #currently-allocated-memory
321 /// [*fit*]: #memory-fitting
322 ///
323 /// # Errors
324 ///
325 /// Returns `Err` if the new layout does not meet the allocator's size and alignment
326 /// constraints of the allocator, or if shrinking otherwise fails.
327 ///
328 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
329 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
330 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
331 ///
332 /// Clients wishing to abort computation in response to an allocation error are encouraged to
333 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
334 ///
335 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
336 unsafe fn shrink(
337 &self,
338 ptr: NonNull<u8>,
339 old_layout: Layout,
340 new_layout: Layout,
341 ) -> Result<NonNull<[u8]>, AllocError> {
342 debug_assert!(
343 new_layout.size() <= old_layout.size(),
344 "`new_layout.size()` must be smaller than or equal to `old_layout.size()`"
345 );
346
347 let new_ptr = self.allocate(new_layout)?;
348
349 // SAFETY: because `new_layout.size()` must be lower than or equal to
350 // `old_layout.size()`, both the old and new memory allocation are valid for reads and
351 // writes for `new_layout.size()` bytes. Also, because the old allocation wasn't yet
352 // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is
353 // safe. The safety contract for `dealloc` must be upheld by the caller.
354 unsafe {
355 ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), new_layout.size());
356 self.deallocate(ptr, old_layout);
357 }
358
359 Ok(new_ptr)
360 }
361
362 /// Creates a "by reference" adapter for this instance of `Allocator`.
363 ///
364 /// The returned adapter also implements `Allocator` and will simply borrow this.
365 #[inline(always)]
366 fn by_ref(&self) -> &Self
367 where
368 Self: Sized,
369 {
370 self
371 }
372}
373
374#[unstable(feature = "allocator_api", issue = "32838")]
375unsafe impl<A> Allocator for &A
376where
377 A: Allocator + ?Sized,
378{
379 #[inline]
380 fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
381 (**self).allocate(layout)
382 }
383
384 #[inline]
385 fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
386 (**self).allocate_zeroed(layout)
387 }
388
389 #[inline]
390 unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout) {
391 // SAFETY: the safety contract must be upheld by the caller
392 unsafe { (**self).deallocate(ptr, layout) }
393 }
394
395 #[inline]
396 unsafe fn grow(
397 &self,
398 ptr: NonNull<u8>,
399 old_layout: Layout,
400 new_layout: Layout,
401 ) -> Result<NonNull<[u8]>, AllocError> {
402 // SAFETY: the safety contract must be upheld by the caller
403 unsafe { (**self).grow(ptr, old_layout, new_layout) }
404 }
405
406 #[inline]
407 unsafe fn grow_zeroed(
408 &self,
409 ptr: NonNull<u8>,
410 old_layout: Layout,
411 new_layout: Layout,
412 ) -> Result<NonNull<[u8]>, AllocError> {
413 // SAFETY: the safety contract must be upheld by the caller
414 unsafe { (**self).grow_zeroed(ptr, old_layout, new_layout) }
415 }
416
417 #[inline]
418 unsafe fn shrink(
419 &self,
420 ptr: NonNull<u8>,
421 old_layout: Layout,
422 new_layout: Layout,
423 ) -> Result<NonNull<[u8]>, AllocError> {
424 // SAFETY: the safety contract must be upheld by the caller
425 unsafe { (**self).shrink(ptr, old_layout, new_layout) }
426 }
427}
428