smox 0.5.0

Box that stores small objects inline and bigger objects on the heap using Box, Rc or Arc, with CoW semantic
Documentation 
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

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
// starting with v0.5 the size is given in `size_of::<usize>` units.
#[derive(Clone)]
struct Generic<T: Clone> {
    value: SmoxRc<T, 2>,
}

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>>() <= std::mem::size_of::<[usize; 2]>());
assert!(std::mem::size_of::<Generic<[i32; 100]>>() <= std::mem::size_of::<[usize; 2]>());

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() {}
```

# Limitations

* `T` and the underlying `HeapStorage` box type must implement `Clone`
* `Smox` does not support dyn trait objects
* `Smox` does not support unsized types

# 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. See below for nightly support.
* 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.
  Although this may not have the best performance, esp when it can not benefit from CoW.

# Status

With v0.5.0 the the API stabilized for the current rust stable, eventually this will be
deprecated and superseeded once rust provides better support for const generics as shown in
the `nightly` features. The nightly support is still experimental and may change in future
versions.

# 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`, then no space fo in-place storage is
reserved, storing on heap requires only 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`.

```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, the in_place storage is optimized to 0 bytes when T > SIZE
// This test verifies the optimization:

// i32 (4 bytes) fits in SIZE=4, stored in_place
// Size = pointer_size (due to union alignment)
let small: SmoxRc<i32, 4> = SmoxRc::new(42);
assert_eq!(std::mem::size_of_val(&small), std::mem::size_of::<[usize; 1]>());

// [i32; 100] (400 bytes) > SIZE=4, stored on heap → ptr size
// Without nightly optimization, this would be 4*size_of::<usize> bytes!
let big: SmoxRc<[i32; 100], 4> = 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, 4> = SmoxRc::new(42);
*s += 1;
assert_eq!(*s, 43);

let b: SmoxRc<[i32; 100], 4> = 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() {}
```

# Open Issues

The `generic_const_exprs` feature is far from complete. Eventually the rust team may specify
this functionaly in a completely other way. This crate will stabilize when the rust language
supports the required features in stable. The old stable implementation will then be abadoned
in favor of the new features. The pre-stabilization implementation will stay available in old
versions though.