A Box like type that keeps small objects on the stack and can allocate bigger objects as
Box, Rc or Arc. DerefMut is copy-on-write when the Smox is backed by Rc or Arc
# Rationale
In generic contexts one often does not know how big the objects will be. If they are small
enough
they can be kept on the stack for better performance. If they are bigger they need to be
allocated on the heap. Smox allows to do this in a transparent way.
# Example
```rust
# #![cfg_attr(feature = "nightly", allow(unused))]
# #[cfg(not(feature = "nightly"))]
# fn main() {
use smox::*;
// For the copy-on-write behavior we need T: Clone
#[derive(Clone)]
struct Generic<T: Clone> {
value: SmoxRc<T, 16>,
}
impl<T: Clone> Generic<T> {
fn new(value: T) -> Self {
Self {
value: SmoxRc::new_rc(value),
}
}
}
// we have the guarantee that Generic<T> will always be at most 16 bytes large.
assert!(std::mem::size_of::<Generic<i32>>() <= 16);
assert!(std::mem::size_of::<Generic<[i32; 100]>>() <= 16);
let mut small = Generic::new(42i32);
*small.value += 1;
assert_eq!(*small.value, 43);
let big = Generic::new([0i32;100]);
// Cheap cloning the underlying Rc
let mut big_clone = big.clone();
// Modifying big_clone will trigger a copy-on-write
big_clone.value[0] = 1;
assert_eq!(big.value[0], 0);
assert_eq!(big_clone.value[0], 1);
# }
# #[cfg(feature = "nightly")]
# fn main() {}
```
# Details
* In the current implementation, the given `SIZE` is also the size of a `Smox` or
the size of a box types whatever is bigger.
Current stable rust lacks the `generic_const_exprs` support to constrain the size when
heap storage is used to a single pointer. This will change in the future, perhaps with a
`nightly` feature flag.
* The biggest spaces saving are when you can benefit from the copy-on-write behavior of `Rc` or
`Arc`. Use either of these when there is a chance that the objects will be cloned.
* When your `Smox` should stay as small as possible then try the `MINIMAL_SIZE` as size limit.
# Nightly Support
With the `nightly` feature enabled, Smox uses `generic_const_exprs` to optimize away unused
in-place storage. When `T` is larger than `SIZE`, the in-place storage becomes 0 bytes instead
of wasting `SIZE` bytes. Because of alignement requirements it will still be sized a multiple
of a pointer size. When stored on heap it is a single pointer, when stored in_place it is
`size_of::<T>().next_multiple_of(std::mem::size_of::<usize>()`.
However, this optimization requires adding where bounds when using `Smox` with generic type
parameters:
```rust
# #![cfg_attr(feature = "nightly", feature(generic_const_exprs))]
# #![cfg_attr(not(feature = "nightly"), allow(unused))]
# #[cfg(feature = "nightly")]
# fn main() {
use smox::*;
// On nightly, generic structs need the optimal_size where bound
#[derive(Clone)]
struct Generic<T: Clone>
where
[(); optimal_size::<T, 32>()]:,
{
value: SmoxRc<T, 32>,
}
impl<T: Clone> Generic<T>
where
[(); optimal_size::<T, 32>()]:,
{
fn new(value: T) -> Self {
Self {
value: SmoxRc::new_rc(value),
}
}
}
// Size behavior with nightly optimization:
// - When T > SIZE: stored on heap, Smox is pointer-sized (in_place optimized to 0)
// - When T <= SIZE: stored in_place, size is size_of::<T>() rounded up to pointer alignment
// (because the union contains pointer fields which require pointer alignment)
// i32 (4 bytes) fits in SIZE=32, stored in_place
// Size = 4.next_multiple_of(8) = 8 = pointer size
assert_eq!(std::mem::size_of::<Generic<i32>>(), std::mem::size_of::<usize>());
// [i32; 100] (400 bytes) > SIZE=32, stored on heap → ptr size (in_place is 0!)
// Without nightly optimization, this would be 32 bytes!
assert_eq!(std::mem::size_of::<Generic<[i32; 100]>>(), std::mem::size_of::<usize>());
// [u8; 12] (12 bytes) fits in SIZE=32, stored in_place
// Size = 12.next_multiple_of(8) = 16 (padding added for pointer alignment)
assert_eq!(
std::mem::size_of::<Generic<[u8; 12]>>(),
std::mem::size_of::<[u8; 12]>().next_multiple_of(std::mem::size_of::<usize>())
);
let mut small = Generic::new(42i32);
*small.value += 1;
assert_eq!(*small.value, 43);
let big = Generic::new([0i32;100]);
// Cheap cloning the underlying Rc
let mut big_clone = big.clone();
// Modifying big_clone will trigger a copy-on-write
big_clone.value[0] = 1;
assert_eq!(big.value[0], 0);
assert_eq!(big_clone.value[0], 1);
# }
# #[cfg(not(feature = "nightly"))]
# fn main() {}
```