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

# #![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(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 alignment requirements it will still be sized at least 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>()).

Note: Using Smox with generic type parameters in structs requires adding a where bound [(); optimal_size::<T, SIZE>()]: to propagate the constraint. This is an inherent limitation of generic_const_exprs.

# #![cfg_attr(feature = "nightly", feature(generic_const_exprs))]
# #![cfg_attr(not(feature = "nightly"), allow(unused))]
# #[cfg(feature = "nightly")]
# fn main() {
use smox::*;

// On nightly, the in_place storage is optimized to 0 bytes when T > SIZE
// This test verifies the optimization:

// i32 (4 bytes) fits in SIZE=32, stored in_place
// Size = pointer_size (due to union alignment)
let small: SmoxRc<i32, 32> = SmoxRc::new(42);
assert_eq!(std::mem::size_of_val(&small), 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!
let big: SmoxRc<[i32; 100], 32> = SmoxRc::new([0; 100]);
assert_eq!(std::mem::size_of_val(&big), std::mem::size_of::<usize>());

// Verify values work correctly
let mut s: SmoxRc<i32, 32> = SmoxRc::new(42);
*s += 1;
assert_eq!(*s, 43);

let b: SmoxRc<[i32; 100], 32> = SmoxRc::new([0; 100]);
// Cheap cloning the underlying Rc
let mut b_clone = b.clone();
// Modifying b_clone will trigger a copy-on-write
b_clone[0] = 1;

assert_eq!(b[0], 0);
assert_eq!(b_clone[0], 1);
# }
# #[cfg(not(feature = "nightly"))]
# fn main() {}