Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
smallbox
Box dynamically-sized types on stack. Requires nightly rust.
Store or return trait-object and closure without heap allocation, and fallback to heap when thing goes too large.
Documentation
Usage
First, add the following to your Cargo.toml
:
[]
= "0.4"
Next, add this to your crate root:
extern crate smallbox;
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:
[]
= { = "0.4", = false }
Enable heap
feature for #![no_std]
build to link to alloc
crate
and bring SmallBox<T>
back.
[]
= "0.4"
= false
= ["heap"]
Feature Flags
The stackbox crate has the following cargo feature flags:
-
std
- Optional, enabled by default
- Use libstd
-
heap
- Optional
- Use heap fallback and include
SmallBox<T>
type, and link toalloc
crate ifstd
feature flag is opted out.
Overview
This crate delivers two core type:
StackBox<T>
: Represents as a fixed-capacity allocation, and on stack stores dynamically-sized type.
The new
method creates returns Err(value)
if the instance larger then Space
.
Default capacity is two words (2 * sizeof(usize)
), more details on custom capacity are at the following sections.
SmallBox<T>
: Takes StackBox<T>
as an varience, and fallback to heap-alloc Box<T>
when type T
is larger then Space
.
Example
The simplest usage is trait object dynamic-dispatch
use StackBox;
let val: = new.unwrap;
assert!
Any
downcasting is also quite a good use.
use Any;
let num: = new.unwrap;
if let Some = num. else
Another use case is to allow returning capturing closures without having to box them.
use StackBox;
let closure = make_closure;
assert_eq!;
SmallBox<T>
is to eliminate heap alloction for small things, except that
the object is large enough to allocte.
In addition, the inner StackBox<T>
or Box<T>
can be moved out by explicit pattern match.
use SmallBox;
let tiny: = new;
let big: = new;
assert_eq!;
assert_eq!;
match tiny
match big
Capacity
The custom capacity of SmallBox<T, Space>
and StackBox<T,Space>
is expressed by the size of type Space
,
which default to space::S2
representing as 2 words space (2 * usize).
There are some default options in module smallbox::space
from S2
to S64
.
Anyway, you can defind your own space type, or just use some array.
The resize()
method on StackBox<T, Space>
and SmallBox<T, Space>
is used to transforms themselves to the one of larger capacity.
use SmallBox;
use *;
let s = new;
assert!;
Roadmap
- Static size check (since
mem::size_of()
has become const fn)
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.