A new stack-based vector

Author: c410-f3r

text/2978-stack_vec.md

@@ -0,0 +1,185 @@
+- Feature Name: `stack_vec`
+- Start Date: 2020-09-27
+- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000)
+- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
+
+# Summary
+[summary]: #summary
+
+This RFC proposes the creation of a new "growable" vector named `StackVec` that manages stack memory and can be seen as an alternative for the built-in structure that handles heap-allocated memory, aka `alloc::vec::Vec<T>`.
+
+# Motivation
+[motivation]: #motivation
+
+`core::collections::StackVec<T>` has several use-cases and should be conveniently added into the standard library due to its importance.
+
+### Unification
+
+There are a lot of different crates about the subject that tries to do roughly the same thing, a centralized implementation would stop the current fragmentation.
+
+### Optimization
+
+Stack-based allocation is generally faster than heap-based allocation and can be used as an optimization in places that otherwise would have to call an allocator. Some resource-constrained embedded devices can also benefit from it.
+
+### Building block
+
+Just like `Vec`, `StackVec` is a primitive vector where high-level structures can use it as a building block. For example, a stack-based matrix or binary heap.
+
+### Useful in the real world
+
+`arrayvec` is one of the most downloaded project of `crates.io` and is used by thousand of projects, including Rustc itself.
+
+### Compiler internals
+
+Unstable features can be used internally to make operations more efficient, e.g., `specialization`.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+Instead of relying on a heap-allocator, stack-based memory area is added and removed on-demand in a last-in-first-out (LIFO) order according to the calling workflow of a program. Let's illustrate an imaginary function `super()` that allocates 32 bits before calling another function named `sub()` that also allocates 32 bits of auxiliary memory:
+
+```txt
+0 bits           32 bits          64 bits   
+
+
+|       |   ->   |       |   ->   |       |
+---------        ---------        ---------
+                 | super |        |  sub  |
+                 ---------        ---------
+                                  | super |
+                                  ---------
+```
+
+* Now `super()` returns and the exactly same thing happens in reverse order, dropping everything when out of scope.
+
+```txt
+64 bits          32 bits          0 bits   
+
+
+|       |   ->   |       |   ->   |       |
+---------        ---------        ---------
+|  sub  |        | super |
+---------        ---------
+| super |
+---------
+```
+
+`StackVec` takes advantage of this predictable behavior to reserve an exactly amount of uninitialized bytes up-front and these bytes form a buffer where elements can be included dynamically.
+
+```rust
+fn main() {
+    // `stack_vec` has a pre-allocated memory of 2048 bits that can store up to 64 decimals.
+    let mut stack_vec: StackVec<i32, 64> = StackVec::new();
+
+    // Although reserved, there isn't anything explicitly stored yet
+    assert_eq!(stack_vec.len(), 0);
+
+    // Initializes the first 32 bits with a simple '1' decimal or
+    // 00000000 00000000 00000000 00000001 bits
+    stack_vec.push(1);
+
+    // Our vector memory is now split into a 32/2016 pair of initialized and
+    // uninitialized memory respectively
+    assert_eq!(stack_vec.len(), 1);
+}
+```
+
+Of course, fixed buffers lead to some inflexibility because unlike `Vec`, the underlying capacity can not expand at run-time and there will never be more than 64 elements in the above example.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+The most natural module for `StackVec` is `core::collections` with an API that basically mimics most of the current `Vec<T>` surface.
+
+```rust
+// core::collections
+
+pub struct StackVec<T, const N: usize> {
+    data: MaybeUninit<[T, N]>,
+    len: usize
+}
+
+impl<T, const N: usize> StackVec<T, N> {
+    // Much of the `Vec` API goes here
+}
+```
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+### Additional complexity
+
+New and existing users are likely to find it difficult to differentiate the purpose of each vector type, especially people that don't have a theoretical background in memory management.
+
+### The current ecosystem is fine
+
+Even with all the fragmentation, different types of memory usage is an overkill in certain situations. If someone wants to use stack memory in an embedded application, then it is just a matter of grabbing an appropriated crate.
+
+# Prior art
+[prior-art]: #prior-art
+
+These are the most known structures:
+
+ * `arrayvec::ArrayVec`: Uses declarative macros and an `Array` trait for implementations but lacks support for arbitrary sizes.
+ * `heapless::Vec`: With the usage of `typenum`, can support arbitrary sizes without a nightly compiler.
+ * `staticvec::StaticVec`: Uses unstable constant generics for arrays of arbitrary sizes.
+ * `tinyvec::ArrayVec`: Supports fixed and arbitrary (unstable feature) sizes but requires `T: Default` for security reasons.
+
+As seen, there isn't an implementation that stands out among the others because all of them roughly share the same purpose and functionality. Noteworthy is the usage of constant generics that makes it possible to create an efficient and unified approach for arbitrary array sizes.
+
+# Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+### Nomenclature
+
+`StackVec` will probably avoid conflicts with existing crates but another name might be a better option.
+
+### Prelude
+
+Should it be included in the prelude?
+
+### Macros
+
+```rust
+    // Instance with 1i32, 2i32 and 3i32
+    let _: StackVec<i32, 33> = stack_vec![1, 2, 3];
+
+    // Instance with 1i32 and 1i32
+    let _: StackVec<i32, 64> = stack_vec![1; 2];
+```
+
+# Future possibilities
+[future-possibilities]: #future-possibilities
+
+### Dynamic array
+
+An hydric approach between heap and stack memory could also be provided natively in the future.
+
+```rust
+pub struct DynVec<T, const N: usize> {
+    // Hides internal implementation
+    data: DynVecData,
+}
+
+impl<T, const N: usize> DynVec<T, N> {
+    // Much of the `Vec` API goes here
+}
+
+// This is just an example. `Vec<T>` could be `Box` and `enum` an `union`.
+enum DynVecData<T, const N: usize> {
+    Heap(Vec<T>),
+    Inline(StackVec<T, N>),
+}
+```
+
+The above description is very similar to what `smallvec` already does.
+
+### Generic collections and generic strings
+
+Many structures that use `alloc::vec::Vec` as the underlying storage can also use stack or hybrid memory, for example, an hypothetical `GenericString<S>`, where `S` is the storage, could be split into:
+
+```rust
+type DynString = GenericString<DynVec<u8>>;
+type HeapString = GenericString<Vec<u8>>;
+type StackString = GenericString<StackVec<u8>>;
+```