Cable
A cable
(pointer) with a hook
(header at address) at the end and a sized payload
(array)
Features
A pointer type for heap allocation, with some special features:
- Stores an optional user specified header at address
- Stashes the size of the data inline
- A resizable array with bounds checking that requires just a pointer to use
- Adds padding where necessary to maintain alignment for header, size, and elements.
Usage
Add this to your Cargo.toml
:
[]
= "0.1.1"
Examples
let mut data: = with_capacity_zeroed;
data = 1.0;
data = 6.0;
data = 9.0;
for i in data.iter
println!;
println!;
The Cable<T, H>
is useful in creating other heap objects.
Creating a simple dynamic storage with a length and capacity:
let mut data: = with_capacity; // allocate capacity for 24 elements
data = 19;
data = 22;
data = 35;
data = 53;
data = 68;
data = 13;
println!;
println!;
The Cable<T, H>
works well for nested structures when a small footprint is required:
let mut x: = Vec with_capacity;
x.push;
x = 67;
x = 45;
x.push;
x = 32;
x = 19;
In this case the vector acts like a 2D array but each element can have a variable size. This allows for compact data structures with proper bounds checking and a minimal footprint. A struct can be used as a header for convenience:
let mut x: = with_capacity;
A header may be omitted for brevity:
let mut x: = new;
Safety
This pointer is safe as it always allocates at least mem::size_of::<usize>()
bytes on the heap and will point to that allocation.
Allocation
A cable has some special allocation features and considerations:
- Will allocate at least
mem::size_of::<H>()
+ padding forusize
+mem::size_of::<usize>()
+ padding forT
. - H can be zero-sized, in this case, such as when using the unit type
H = ()
the header is not allocated. - Can optionally allocate memory zeroed.
- Cost is minimal, most memory layout is determined at compile time.
- Resembles a
Box<H>
when payload is unallocated (although with at least an extramem::size_of::<usize>()
bytes, seeinto_boxed_header
).
Crate features
To be determined, will likely support in the future:
- no-std
- serde
- custom allocator