smallbox

Small Box optimization: store small item on the stack and fallback to heap for large item.

Documentation

# Usage

First, add the following to your Cargo.toml:

toml [dependencies] smallbox = "0.5"

Next, add this to your crate root:

rust extern crate smallbox;

If you want this crate to work with dynamic-sized type, you can request it via:

toml [dependencies] smallbox = { version = "0.5", features = ["unsize"] }

Currently smallbox by default links to the standard library, but if you would instead like to use this crate in a #![no_std] situation or crate, and want to opt out heap dependency and SmallBox<T> type, you can request this via:

toml [dependencies.smallbox] version = "0.5" features = ["unsize"] default-features = false

Enable heap feature for #![no_std] build to link to alloc crate and bring SmallBox<T> back.

toml [dependencies.smallbox] version = "0.5" features = ["unsize", "heap"] default-features = false

# Feature Flags

This crate has the following cargo feature flags:

• std

  • Optional, enabled by default
  • Use libstd

• heap

  • Optional, enabled by default
  • Support heap fallback by including SmallBox<T>
  • If std feature flag is opted out, this will link alloc crate, and it need nightly rust for that.

• unsize

  • Optional
  • Require nightly rust
  • Enable support for DST (dynamic-sized type).

  Stable Rust

  The only possible way to use this crate on stable rust is to use the default feature flag, which means you can't use it in no_std environment or use it with DST (dynamic-sized type).

  Unsized Type

  Once the feature unsize is enabled, the item type T of SmallBox and StackBox can and must be an unsized type, such as trait object or owned array slice.

  Overview

  This crate delivers two core type:

• SmallBox<T, Space>: Stores T on heap or stack depending on the size of T. It takes StackBox<T, Space> as an varience to store small item, and then fallback to heap allocated Box<T> when type T is larger then the capacity of Space.

• StackBox<T, Space>: Represents as a fixed-capacity allocation, and stores item on stack.

  Example

  Eliminate heap alloction for small items by SmallBox:

  ```rust use smallbox::SmallBox; use smallbox::space::S4;

  let small: SmallBox<_, S4> = SmallBox::new([0; 2]); let large: SmallBox<_, S4> = SmallBox::new([0; 32]);

  asserteq!(small.len(), 2); asserteq!(large.len(), 32);

  match small { SmallBox::Stack(val) => assert_eq!(*val, [0; 2]), _ => unreachable!() }

  match large { SmallBox::Box(val) => assert_eq!(*val, [0; 32]), _ => unreachable!() } ```

  DST

  The following examples requires unsize feature flag enabled.

  Trait object dynamic-dispatch:

  ```rust use smallbox::StackBox; use smallbox::space::S1;

  let val: StackBox, S1> = StackBox::new(5usize).unwrap();

  assert!(*val == 5)

  }

  ```

  Any downcasting:

  ```rust use std::any::Any; use smallbox::SmallBox; use smallbox::space::S2;

  let num: SmallBox = SmallBox::new(1234u32);

  if let Some(num) = num.downcastref::() { asserteq!(*num, 1234); } else { unreachable!(); } ```

Benchmark

The test platform is Windows 10 on Intel E3 v1230 v3.

``` running 6 tests test boxlargeitem ... bench: 102 ns/iter (+/- 15) test boxsmallitem ... bench: 48 ns/iter (+/- 16) test smallboxlargeitemlargespace ... bench: 64 ns/iter (+/- 1) test smallboxlargeitemsmallspace ... bench: 113 ns/iter (+/- 14) test smallboxsmallitemlargespace ... bench: 17 ns/iter (+/- 0) test smallboxsmallitemsmallspace ... bench: 6 ns/iter (+/- 0)

test result: ok. 0 passed; 0 failed; 0 ignored; 6 measured; 0 filtered out ```

Roadmap

• check size statically.
• provide to_box() for SmallBox<T> of unsize version.

Contribution

All kinds of contribution are welcome.

• Issue Feel free to open an issue when you find typos, bugs, or have any question.
• Pull requests. Better implementation, more tests, more documents and typo fixes are all welcome.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.