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
|
use crate::guards::UninitializedSliceMemoryGuard;
use std::mem::MaybeUninit;
use crate::try_inplace_array;
/// `alloc_array` is used when `inplace_or_alloc_array` realize that the size of requested array of `T`
/// is too large and should be replaced in the heap.
///
/// It allocates a vector with `size` elements and fills it up with help of `init` closure
/// and then pass a reference to a slice of the vector into the `consumer` closure.
/// `consumer`'s result will be returned.
pub fn alloc_array<T, R, Consumer: FnOnce(UninitializedSliceMemoryGuard<T>) -> R>(size: usize, consumer: Consumer) -> R {
unsafe {
let mut memory_holder = Vec::<MaybeUninit<T>>::with_capacity(size);
memory_holder.set_len(size);
let result = consumer(UninitializedSliceMemoryGuard::new(&mut *memory_holder));
memory_holder.set_len(0);
result
}
}
/// `inplace_or_alloc_array` is a central function of this crate.
/// It's trying to place an array of `T` on the stack and pass the guard of memory into the
/// `consumer` closure. `consumer`'s result will be returned.
///
/// If the result of array of `T` is more than 4096 then the vector will be allocated
/// in the heap and will be used instead of stack-based fixed-size array.
///
/// Sometimes size of allocated array might be more than requested. For sizes larger than 32,
/// the following formula is used: `roundUp(size/32)*32`. This is a simplification that used
/// for keeping code short, simple and able to optimize.
/// For example, for requested 50 item `[T; 64]` will be allocated.
/// For 120 items - `[T; 128]` and so on.
///
/// Note that rounding size up is working for fixed-sized arrays only. If function decides to
/// allocate a vector then its size will be equal to requested.
///
/// # Examples
///
/// ```rust
/// use inplace_it::{
/// inplace_or_alloc_array,
/// UninitializedSliceMemoryGuard,
/// };
///
/// let sum: u16 = inplace_or_alloc_array(100, |uninit_guard: UninitializedSliceMemoryGuard<u16>| {
/// assert_eq!(uninit_guard.len(), 128);
/// // For now, our memory is placed/allocated but uninitialized.
/// // Let's initialize it!
/// let guard = uninit_guard.init(|index| index as u16 * 2);
/// // For now, memory contains content like [0, 2, 4, 6, ..., 252, 254]
/// guard.iter().sum()
/// });
/// // Sum of [0, 2, 4, 6, ..., 252, 254] = sum of [0, 1, 2, 3, ..., 126, 127] * 2 = ( 127 * (127+1) ) / 2 * 2
/// assert_eq!(sum, 127 * 128);
/// ```
pub fn inplace_or_alloc_array<T, R, Consumer>(size: usize, consumer: Consumer) -> R
where Consumer: FnOnce(UninitializedSliceMemoryGuard<T>) -> R
{
match try_inplace_array(size, consumer) {
Ok(result) => result,
Err(consumer) => alloc_array(size, consumer),
}
}
|
