Merge pull request #14 from BoxyUwU/master

Copy over stories from vision doc hackmd

Author: oli-obk

SUMMARY.md

@@ -5,7 +5,12 @@
 - [🔮 The vision](./vision.md)
    - [🙋‍♀️ Cast of characters](./vision/characters.md)
    - [😱 Status quo](./vision/status_quo.md)
+      - [Array defaults](./vision/status_quo/array_default.md)
+      - [Array split first method](./vision/status_quo/split_first.md)
    - [✨ Shiny future](./vision/shiny_future.md)
+      - [Array defaults](./vision/shiny_future/array_default.md)
+      - [Array split first method](./vision/shiny_future/split_first.md)
+      - [Image type in rust-gpu](./vision/shiny_future/image_type.md)
    - [📅 Roadmap for 2021](./vision/roadmap.md)
    - [❓How to vision doc](./vision/how_to_vision_doc.md)- [Meetings](./meetings/README.md)
 - [✏️ Draft RFCs](./draft-rfcs/README.md)

vision.md

@@ -10,6 +10,6 @@ This section lays out a general vision and set of goals for Const Generics in Ru
 
 ## This is a group effort
 
-As the leads of the Async Foundation group, Niko and Tyler are driving and organizing this document. But writing it and shaping it is a group effort. If you think there is a part of the async experience that is not reflected here, we want to hear from you! Check out the [How to vision doc] for more details on how to contribute.
+As the leads of the Const Generics group, Niko and Lcnr are driving and organizing this document. But writing it and shaping it is a group effort. If you think there is a part of the const generics experience that is not reflected here, we want to hear from you! Check out the [How to vision doc] for more details on how to contribute.
 
 [How to vision doc]: ./vision/how_to_vision_doc.md

vision/characters.md

@@ -1 +1,39 @@
 # 🙋‍♀️ Cast of characters
+
+## What is this?
+
+We've created four characters that we use to guide our thinking. These characters are the protagonists of our [status quo] and [shiny future] stories, and they help us to think about the different kinds of priorities and expectations that people bring when using Const Generics in rust. Having names and personalities also makes the stories more fun and approachable.
+
+[status quo]: ./status_quo.md
+[shiny future]: ./shiny_future.md
+
+## The characters
+
+* Alan: the experienced "GC'd language" developer, new to Rust
+    * *Top priority*: performance -- that's what he is not getting from current GC'd language
+    * *Expectations*: absence of memory safety bugs (he gets that now from his GC), strong ecosystem, great tooling
+* Grace: the systems programming expert, new to Rust
+    * *Top priority*: memory safety -- that's what she is not getting from C/C++
+    * *Expectations*: able to do all the things she's used to from C/C++
+* Niklaus: new programmer from an unconventional background
+    * *Top priority*: accessibility -- he's learning a lot of new things at once
+    * *Expectations*: community -- the community enabled him to have early success, and he is excited to have it support him and him grow more
+* Barbara: the experienced Rust developer
+    * *Top priority*: overall productivity and long-term maintenance -- she loves Rust, and wants to see it extended to new areas; she has an existing code base to maintain
+    * *Expectations*: elegance and craftsmanship, fits well with Rust
+
+## 🤔 Frequently Asked Questions
+
+### Where do the names come from?
+Famous programming language designers and theorists. [Alan Turing], [Grace Hopper], [Niklaus Wirth], and [Barbara Liskov].
+
+### I don't see myself in these characters. What should I do?
+Come to Zulip (#project-const-generics) and talk to us about it! Maybe they need to be adjusted!
+
+### I see myself in more than one of these characters!
+Yeah, me too.
+
+[Alan Turing]: https://en.wikipedia.org/wiki/Alan_Turing
+[Grace Hopper]: https://en.wikipedia.org/wiki/Grace_Hopper
+[Niklaus Wirth]: https://en.wikipedia.org/wiki/Niklaus_Wirth
+[Barbara Liskov]: https://en.wikipedia.org/wiki/Barbara_Liskov

vision/how_to_vision_doc.md

@@ -9,7 +9,7 @@ This page describes the process for contributing to the vision doc.
 
 ## Who owns this document?
 
-This document is owned and maintained by the leads of the Const Generics Working Group.
+This document is owned and maintained by the leads of the project-const-generics group.
 They decide what content to accept or reject. 
 This decision is made in consultation with the Rust teams that will be making the ultimate decisions. 
 For example, if a design doc or part of the shiny future is describing a new language feature, the leads ought to  discuss that with the language design team, since that team will ultimately have to approve the RFCs for its design.

vision/roadmap.md

@@ -17,6 +17,3 @@ It is updated on a monthly basis.
 
 | Plan | Owner | Status | Last updated
 | --- | --- | --- | --- |
-| [Async functions in traits] | nikomatsakis | 🥬 | 2021-02 |
-
-[Async functions in traits]: ../design_docs/async_fns_in_traits.md

vision/shiny_future/array_default.md

@@ -0,0 +1,56 @@
+# ✨ Shiny future story: Barbara implements `Default` for all array lengths
+
+Shiny future of [status quo story](../status_quo/array_default.md)
+
+Barbara is working on `std`. She saw that the newest version of rustc has had some improvements to const generics
+and decides to try implementing `Default` for all array lengths. She goes to write:
+
+```rust
+impl<T, const N: usize> Default for [T; N]
+where
+    T: Default,
+{
+    fn default() -> Self {
+        /* snip */
+    }
+}
+```
+
+The code builds just fine but then she sees a test failing:
+```rust
+fn generic<T>() -> [T; 0] {
+    Default::default()
+}
+```
+
+"Ah," she says, "I see that Default is implemented for any type [T; 0], regardless of whether T: Default. That makes sense. Argh!"
+
+Next she tries to write:
+```rust
+impl<T, const N: usize> Default for [T; N]
+where
+    T: Default,
+    { N > 0 },
+{
+    fn default() -> Self {
+        /* snip */
+    }
+}
+
+impl<T> Default for [T; 0] {
+    fn default() -> Self {
+        []
+    }
+}
+```
+
+This compiles just fine and the test is passing. She decides to submit a PR where her reviewer asks her to 
+add a test to make sure that `[T; N]: Default` holds when `T: Default` as this didn't used to work
+
+```rust
+fn exhaustive_default_impl<T: Default, const N: usize>() -> [T; N] {
+    <[T; N] as Default>::default()
+}
+```
+
+This test passes just fine, "yay const generics ✨" she says

vision/shiny_future/image_type.md

@@ -0,0 +1,44 @@
+# ✨ Shiny future story: Image type in rust-gpu
+Barbara is working on rust-gpu. In that project, she has a struct `Image` that represents GPU images. There are a number of constant parameters allowing this type to be heavily customized in a number of ways. In some cases, helper methods are only available for images with particular formats. She writes the struct declaration:
+
+```rust
+struct Image<
+    SampledType: SampleType<FORMAT>,
+    const DIM: Dimensionality,
+    const DEPTH: ImageDepth,
+    const ARRAYED: Arrayed,
+    const MULTISAMPLED: Multisampled,
+    const SAMPLED: Sampled,
+    const FORMAT: ImageFormat,
+    const ACCESS_QUALIFIER: Option<AccessQualifier>,
+>(PhantomData<SampledType>);
+```
+
+Barbara gets a few compile errors about her types used as a const param not implementing `StructuralEq` so she derives that and moves on.
+She then wants to write some methods that only work for images in some specific formats:
+
+```rust
+impl<
+    SampledType: SampleType<FORMAT>,
+    const DIM: Dimensionality,
+    const DEPTH: ImageDepth,
+    const ARRAYED: Arrayed,
+    const MULTISAMPLED: Multisampled,
+    const SAMPLED: Sampled,
+    const FORMAT: ImageFormat,
+    const ACCESS_QUALIFIER: Option<AccessQualifier>,
+> Image<SampledType, DIM, DEPTH, ARRAYED, MULTISAMPLED, SAMPLED, FORMAT, ACCESS_QUALIFIER> {
+    pub fn example_method(/* snip */)
+    where
+        { some_condition(DEPTH, MULTISAMPLED) }
+    { /* snip */ }
+}
+
+const fn some_condition(a: ImageDepth, m: Multisampled) -> bool {
+    match (a, m) {
+        /* snip */
+    }
+}
+```
+
+This compiles just fine and Barbara moves on to more complicated things 

vision/shiny_future/split_first.md

@@ -0,0 +1,58 @@
+# ✨ Shiny future story: Array split first method
+
+Shiny future of [status quo story](../status_quo/split_first.md)
+
+Barbara is working on her project. She has the idea to write a `split_first` function that will allow her to split out the first item from a fixed-length array; naturally, the array must be non-empty. It looks something like this:
+
+```rust
+// Note: this method has an implied where clause that `N - 1` evaluates without 
+// erroring because `N - 1` is in the function signature
+fn split_first<T, const N: usize>(arr: [T; N]) -> (T; [T; N - 1]) {
+    // ...
+    let tail: [T; N - 1] = // ...
+    (head, tail)
+}
+```
+
+Next she wants to write a function that uses `split_first`:
+
+```rust
+fn some_method<const N: usize>(arr: [u8; N]) {
+    let (first, rest) = split_first(arr);
+    for i in rest {
+        // ...
+    }
+}
+```
+
+The compiler gives her a compile error:
+```
+error: the constant expression `N - 1` is not known to evaluate without underflowing
+2 |     let (first, rest) = split_first(arr);
+  |                         ^^^^^^^^^^^ `N - 1` not known to be evaluatable without underflowing
+note: required by this expression in `split_first`'s function signature
+5 |     fn split_first<T, const N: usize>(arr: [T; N]) -> (T; [T; N - 1]) {
+  |                                                               ^^^^^
+help: add a where clause to `some_method`
+  | fn some_method<const N: usize>(arr: [u8; N]) where { N > 0; }
+```
+
+Barbara hits the 'quick fix' button in her IDE and it inserts the where clause for her- she immediately
+gets a compile error at another spot because she was calling `some_method` with an empty array:
+
+```
+error: the constant `0` is not greater than `0`
+22 |     some_method([])
+info: `0` must be greater than `0` because of this where clause
+  | fn some_method<const N: usize>(arr: [u8; N]) where { N > 0; }
+  |                                                    ----------
+```
+
+Barbara has no more compile errors, even the following code is compiling:
+```rust
+fn some_other_method<const N: usize>(arr: [u8; N]) where { N > 1; } {
+    // ...
+    let (first, rest) = split_first(arr);
+    // ...
+}
+```

vision/status_quo.md

@@ -2,7 +2,7 @@
 
 ## What is this
 
-The "status quo" stores are here to state our "theory of the case". That is, they present (and prove) our hypotheses as to what the various challenges are for users of Async I/O in Rust. These hypotheses are presented in narrative form, by telling the story of a specific [character] as they try (and typically fail in dramatic fashion) to achieve their goals.
+The "status quo" stores are here to state our "theory of the case". That is, they present (and prove) our hypotheses as to what the various challenges are for users of Const Generics in Rust. These hypotheses are presented in narrative form, by telling the story of a specific [character] as they try (and typically fail in dramatic fashion) to achieve their goals.
 
 [character]: ./characters.md
 

vision/status_quo/array_default.md

@@ -0,0 +1,105 @@
+# 😱 Status quo story: Barbara wants to implement `Default` for all array lengths 
+
+Barbara is working on `std`. She wants to implement `Default` for all array types. Currently, it is implemented for `N <= 32` using a macro ([link](https://doc.rust-lang.org/nightly/src/core/array/mod.rs.html#391))
+
+She thinks "Ah, I can use min-const-generics for this!" and goes to write
+
+```rust
+impl<T, const N: usize> Default for [T; N]
+where
+    T: Default,
+{
+    fn default() -> Self {
+        
+    }
+
+}
+```
+
+So far so good, but then she realizes she can't figure out what to write in the body. At first she tries:
+
+```rust
+impl<T, const N: usize> Default for [T; N]
+where
+    T: Default,
+{
+    fn default() -> Self {
+        [T::default(); N]
+    }
+
+}
+```
+
+but this won't compile:
+
+```
+error[E0277]: the trait bound `T: Copy` is not satisfied
+  --> src/lib.rs:10:9
+   |
+10 |         [T::default(); N]
+   |         ^^^^^^^^^^^^^^^^^ the trait `Copy` is not implemented for `T`
+   |
+   = note: the `Copy` trait is required because the repeated element will be copied
+help: consider further restricting this bound
+   |
+7  |     T: MyDefault + Copy,
+   |                  ^^^^^^
+```
+
+"Ah," she realizes, "this would be cloning a single value of `T`, but I want to make `N` distinct values. How can I do that?"
+
+She asks on Zulip and lcnr tells her that there is this [`map` function  defined on arrays](https://doc.rust-lang.org/std/primitive.array.html#method.map). She could write:
+
+
+```rust
+impl<T, const N: usize> Default for [T; N]
+where
+    T: Default,
+{
+    fn default() -> Self {
+        [(); N].map(|()| T::default())
+    }
+}
+```
+
+"That code will build," lcnr warns her, "but we're not going to be able to ship it. Test it and see." Barbara runs the tests and finds she is getting a failure. The following test no longer builds:
+
+```rust
+fn generic<T>() -> [T; 0] {
+    Default::default()
+}
+```
+
+"Ah," she says, "I see that `Default` is implemented for any type `[T; 0]`, regardless of whether `T: Default`. That makes sense. Argh!"
+
+Next she tries (this already relies on a nightly feature)
+```rust
+impl<T: Trait, const N: usize> Default for [T; N]
+where
+    T: Default,
+    N != 0, // nightly feature!
+{
+    fn default() -> Self {
+        [(); N].map(|()| T::default())
+    }
+}
+
+impl<T> Trait for [T; 0] {
+    // ...
+}
+```
+
+While this does seem to compile, when trying to use it, it causes an unexpected error.
+
+```rust
+fn foo<T: Trait, const N: usize>() -> [u8; N] {
+    <[T; N] as Trait>::ASSOC //~ ERROR `[T; N]` does not implement `Trait`
+}
+```
+
+The compiler can't tell that `N == 0 || N != 0` is true for all possible `N`, so it can't infer `[T; N]: Trait` from `T: Trait`.
+
+Frustrated, Barbara gives up and goes looking for another issue to fix.
+
+Even worse, Barbara notices the same problem for `serde::Deserialize` and decides to
+abandon backwards compatibility in favor of a brighter future.