1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
//! Allocator extension traits.
use core::{alloc, mem};
use alloc_traits::{NonZeroLayout, LocalAlloc};
use super::{
boxed::Box,
fixed_vec::FixedVec,
rc::Rc,
uninit::Uninit,
};
/// Values of for some allocation including the [`Uninit`].
///
/// See [`Uninit`] for a better picture of the potential usage of this result.
///
/// [`Uninit`]: ../uninit/struct.Uninit.html
#[derive(Debug)]
pub struct LeakedAllocation<'a, T: ?Sized=()> {
/// Uninit pointer to the region with specified layout.
pub uninit: Uninit<'a, T>,
}
/// Leak allocations into uninit regions.
pub trait LocalAllocLeakExt<'alloc>: LocalAlloc<'alloc> {
/// Leak an allocation with detailed layout.
///
/// Provides an [`Uninit`] wrapping several aspects of initialization in a safe interface,
/// bound by the lifetime of the reference to the allocator.
///
/// [`Uninit`]: ../uninit/struct.Uninit.html
fn alloc_layout(&'alloc self, layout: NonZeroLayout)
-> Option<LeakedAllocation<'alloc>>
{
let alloc = self.alloc(layout)?;
let uninit = unsafe {
Uninit::from_memory(alloc.ptr, alloc.layout.size().into())
};
Some(LeakedAllocation {
uninit,
})
}
/// Leak an allocation for a specific type.
///
/// It is not yet initialized but provides a safe interface for that initialization. Note that
/// the type **can** be a ZST in which case a dangling pointer is substituted for the true
/// allocation.
///
/// ## Usage
///
/// ```
/// # use static_alloc::Bump;
/// # use without_alloc::alloc::LocalAllocLeakExt;
/// use core::cell::{Ref, RefCell};
///
/// let slab: Bump<[Ref<'static, usize>; 1]> = Bump::uninit();
/// let data = RefCell::new(0xff);
///
/// // We can place a `Ref` here but we did not yet.
/// let alloc = slab.alloc_t::<Ref<usize>>().unwrap();
/// let cell_ref = alloc.uninit.init(data.borrow());
///
/// assert_eq!(**cell_ref, 0xff);
/// ```
fn alloc_t<V>(&'alloc self) -> Option<LeakedAllocation<'alloc, V>> {
match NonZeroLayout::new::<V>() {
None => Some(LeakedAllocation::zst_fake_alloc()),
Some(alloc) => {
let allocation = self.alloc_layout(alloc)?;
let right_type = allocation.cast().unwrap();
Some(right_type)
},
}
}
/// Allocate a [`Box`].
///
/// This will allocate some memory with the correct layout for a [`Box`], then place the
/// provided value into the allocation by constructing an [`Box`].
///
/// [`Box`]: ../boxed/struct.Box.html
fn boxed<V>(&'alloc self, val: V) -> Option<Box<'alloc, V>> {
let alloc = self.alloc_t::<V>()?;
Some(Box::new(val, alloc.uninit))
}
/// Allocate a [`FixedVec`].
///
/// This will allocate some memory with the correct layout for a [`FixedVec`] of the given
/// capacity (in elements) and wrap it. Returns `None` if it is not possible to allocate the
/// layout.
///
/// [`FixedVec`]: ../fixed_vec/struct.FixedVec.html
fn fixed_vec<V>(&'alloc self, capacity: usize) -> Option<FixedVec<'alloc, V>> {
let size = mem::size_of::<V>().checked_mul(capacity)?;
let layout = alloc::Layout::from_size_align(size, mem::align_of::<V>()).ok()?;
let uninit = match NonZeroLayout::from_layout(layout.into()) {
None => Uninit::empty(),
Some(layout) => {
let allocation = self.alloc_layout(layout)?;
let right_type = allocation.cast_slice().unwrap();
right_type.uninit
}
};
Some(FixedVec::new(uninit))
}
/// Allocate an [`Rc`].
///
/// This will allocate some memory with the correct layout for an [`Rc`], then place the
/// provided value into the allocation by constructing an [`Rc`].
///
/// [`Rc`]: ../rc/struct.Rc.html
fn rc<V>(&'alloc self, val: V) -> Option<Rc<'alloc, V>> {
let layout = Rc::<V>::layout();
// Unwrap since this is surely never an empty layout, always have counter.
let layout = NonZeroLayout::from_layout(layout.into()).unwrap();
let alloc = self.alloc_layout(layout)?;
Some(Rc::new(val, alloc.uninit))
}
/// Allocate a slice of a copyable type.
///
/// This will allocate some memory with the same layout as required by the slice, then copy all
/// values into the new allocation via a byte copy.
///
/// ```
/// # use static_alloc::Bump;
/// # use without_alloc::alloc::LocalAllocLeakExt;
/// let slab: Bump<[usize; 16]> = Bump::uninit();
/// let data: &[u8] = b"Hello, World!";
///
/// let slice = slab.copy_slice(data).unwrap();
/// assert_eq!(data, slice);
/// ```
fn copy_slice<T: Copy>(&'alloc self, slice: &[T]) -> Option<&'alloc mut [T]> {
let layout = alloc::Layout::for_value(slice);
let uninit = match NonZeroLayout::from_layout(layout.into()) {
None => Uninit::empty(),
Some(layout) => {
let allocation = self.alloc_layout(layout)?;
let right_type = allocation.cast_slice().unwrap();
right_type.uninit
}
};
unsafe {
// SAFETY:
// * the source is trivially valid for reads as it is a slice
// * the memory is valid for the same layout as slice, so aligned and large enough
// * both are aligned, uninit due to allocator requirements
core::ptr::copy(slice.as_ptr(), uninit.as_begin_ptr(), slice.len());
}
Some(unsafe {
// SAFETY: this is a copy of `slice` which is initialized.
uninit.into_mut()
})
}
/// Allocate a dynamically sized string.
///
/// This will allocate some memory with the same layout as required by the string, then copy
/// all characters into the new allocation via a byte copy.
///
/// ```
/// # use static_alloc::Bump;
/// # use without_alloc::alloc::LocalAllocLeakExt;
/// let slab: Bump<[u8; 16]> = Bump::uninit();
/// let data: &str = "Hello, World!";
///
/// let slice = slab.copy_str(data).unwrap();
/// assert_eq!(data, slice);
/// ```
fn copy_str(&'alloc self, st: &str) -> Option<&'alloc str> {
let bytes = self.copy_slice(st.as_bytes())?;
Some(unsafe {
// SAFETY: this is a copy of `st` which is valid utf-8
core::str::from_utf8_unchecked(bytes)
})
}
/// Allocate a copy of a generic dynamically sized type.
///
/// This method takes a `ManuallyDrop<T>` wrapper instead of a `T` directly. These types are of
/// course layout compatible and you may soundly cast one reference type to the other. However
/// this choice forces acknowledgment that the value _must not_ be dropped by the caller
/// afterwards and makes this reasonably more safe in case of panics.
///
/// Note further that mutable access is however explicitly _not_ required in contrast to
/// `ManuallyDrop::take`. Otherwise, the caller would have to ensure that the value is not
/// aliased and actually mutable. Keeping these guarantees often involves moving the value into
/// a new stack slot which is obviously not possible for dynamically sized values. This
/// interfaces promises not to overwrite any byte which does not restrict its functionality.
///
/// # Safety
///
/// This is quite unsafe and relies on the nightly `set_ptr_value` feature. Furthermore this
/// method does not require that `T` is in fact `Copy` as doing so would not be possible for
/// dynamically sized values. You must either require this bound on the expose interface or
/// must ensure the source value behind the pointer is not used further, not dropped and
/// basically discarded. You should act as if `take` had been called on the supplied value.
///
/// # Example
///
/// ```
/// # use static_alloc::Bump;
/// # use without_alloc::alloc::LocalAllocLeakExt;
/// use core::fmt::Debug;
/// use core::mem::ManuallyDrop;
///
/// let slab: Bump<[u8; 16]> = Bump::uninit();
/// let debuggable = ManuallyDrop::new(1usize);
/// let debug = unsafe {
/// slab.copy_dst::<dyn Debug>(&debuggable).unwrap()
/// };
/// assert_eq!(format!("{:?}", debug), "1");
/// ```
#[cfg(feature = "nightly_set_ptr_value")]
#[allow(unused_unsafe)]
unsafe fn copy_dst<T: ?Sized>(&'alloc self, val: &core::mem::ManuallyDrop<T>) -> Option<&'alloc mut T> {
let layout = alloc::Layout::for_value(val);
let uninit = match NonZeroLayout::from_layout(layout.into()) {
None => Uninit::invent_for_zst(),
Some(layout) => self.alloc_layout(layout)?.uninit,
};
unsafe {
// SAFETY:
// * the source is valid for reads for its own layout
// * the memory is valid for the same layout as val, so aligned and large enough
// * both are aligned, uninit due to allocator requirements
core::ptr::copy(val as *const _ as *const u8, uninit.as_ptr() as *mut u8, layout.size());
}
let ptr = val as *const _ as *mut T;
let ptr = uninit.as_ptr().with_metadata_of(ptr);
Some(unsafe {
// SAFETY: The byte copy above put the value into a valid state. Caller promises that
// we can logically move the value.
&mut *ptr
})
}
}
impl<'alloc, T> LocalAllocLeakExt<'alloc> for T
where T: LocalAlloc<'alloc>,
{ }
impl<Zst> LeakedAllocation<'_, Zst> {
/// Invent a new allocation for a zero-sized type (ZST).
///
/// # Panics
/// This method panics when the type parameter is not a zero sized type.
pub fn zst_fake_alloc() -> Self {
LeakedAllocation {
uninit: Uninit::invent_for_zst(),
}
}
}
impl<'a, T> LeakedAllocation<'a, T> {
fn cast<U>(self) -> Option<LeakedAllocation<'a, U>> {
Some(LeakedAllocation {
uninit: self.uninit.cast().ok()?,
})
}
fn cast_slice<U>(self) -> Option<LeakedAllocation<'a, [U]>> {
Some(LeakedAllocation {
uninit: self.uninit.cast_slice().ok()?,
})
}
}