devela/sys/mem/alloc/
namespace.rs

Help
1// devela::sys::mem::alloc::namespace
2//
3//! Defines the [`Alloc`] namespace.
4//
5
6#[allow(unused_imports, reason = "unsafe feature-gated")]
7#[cfg(feature = "alloc")]
8use crate::{
9    MemLayout,
10    _dep::_alloc::alloc::{alloc, alloc_zeroed, dealloc, handle_alloc_error, realloc},
11};
12
13#[doc = crate::TAG_NAMESPACE!()]
14/// Memory-allocation-related operations.
15///
16/// See also: [`Mem`][crate::Mem], [`ExtMem`][crate::ExtMem],
17/// [`Ptr`][crate::Ptr], [`Slice`][crate::Slice].
18pub struct Alloc;
19
20#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
21#[cfg(feature = "alloc")]
22impl Alloc {
23    /// Signals a memory allocation error.
24    ///
25    /// # Safety
26    /// See `std::alloc::`[`handle_alloc_error`].
27    pub fn handle_alloc_error(layout: MemLayout) -> ! {
28        handle_alloc_error(layout)
29    }
30}
31
32/// # Unsafe methods
33///
34/// ## Features
35/// They depend on enabling any `unsafe*` feature, and not enabling `safe_mem`.
36#[cfg_attr(feature = "nightly_doc", doc(cfg(unsafe··)))]
37#[cfg(all(not(feature = "safe_mem"), unsafe··))]
38#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
39#[cfg(feature = "alloc")]
40#[rustfmt::skip]
41impl Alloc {
42    /// Allocates memory with the global allocator.
43    ///
44    /// # Safety
45    /// See `std::alloc::`[`alloc`].
46    #[must_use]
47    pub unsafe fn alloc(layout: MemLayout) -> *mut u8 {
48        // SAFETY: Caller must uphold the safety contract.
49        unsafe { alloc(layout) }
50    }
51    /// Allocates zero-initialized memory with the global allocator.
52    ///
53    /// # Safety
54    /// See `std::alloc::`[`alloc_zeroed`].
55    #[must_use]
56    pub unsafe fn alloc_zeroed(layout: MemLayout) -> *mut u8 {
57        // SAFETY: Caller must uphold the safety contract.
58        unsafe { alloc_zeroed(layout) }
59    }
60    /// Deallocates memory with the global allocator.
61    ///
62    /// # Safety
63    /// See `std::alloc::`[`dealloc`].
64    pub unsafe fn dealloc(ptr: *mut u8, layout: MemLayout) {
65        // SAFETY: Caller must uphold the safety contract.
66        unsafe { dealloc(ptr, layout) }
67    }
68    /// Reallocates memory with the global allocator.
69    ///
70    /// # Safety
71    /// See `std::alloc::`[`realloc`].
72    pub unsafe fn realloc(ptr: *mut u8, layout: MemLayout, new_size: usize) -> *mut u8 {
73        // SAFETY: Caller must uphold the safety contract.
74        unsafe { realloc(ptr, layout, new_size) }
75    }
76}
devela/sys/mem/alloc/namespace.rs

devela/sys/mem/alloc/
namespace.rs
