From 11c0f771074111ed067a8a828c0ad01594043d98 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Thu, 22 May 2014 22:01:44 -0700 Subject: [PATCH] doc: add a new language design faq This indends to help quell frequently answered questions about the language design in a single, authoritative place. --- mk/docs.mk | 4 +- src/doc/complement-design-faq.md | 176 +++++++++++++++++++++++++++++++ src/doc/index.md | 15 +-- 3 files changed, 186 insertions(+), 9 deletions(-) create mode 100644 src/doc/complement-design-faq.md diff --git a/mk/docs.mk b/mk/docs.mk index b02cb548ad506..91ff72ed2b53e 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -29,8 +29,8 @@ DOCS := index intro tutorial guide-ffi guide-macros guide-lifetimes \ guide-tasks guide-container guide-pointers guide-testing \ guide-runtime complement-bugreport complement-cheatsheet \ - complement-lang-faq complement-project-faq rust rustdoc \ - guide-unsafe + complement-lang-faq complement-design-faq complement-project-faq rust \ + rustdoc guide-unsafe PDF_DOCS := tutorial rust diff --git a/src/doc/complement-design-faq.md b/src/doc/complement-design-faq.md new file mode 100644 index 0000000000000..8a8f6e02b6d22 --- /dev/null +++ b/src/doc/complement-design-faq.md @@ -0,0 +1,176 @@ +% Rust Design FAQ + +This document describes decisions were arrived at after lengthy discussion and +experimenting with alternatives. Please do not propose reversing them unless +you have a new, extremely compelling argument. Note that this document +specifically talks about the *language* and not any library or implementation. + +A few general guidelines define the philosophy: + +- [Memory safety][mem] must never be compromised +- [Abstraction][abs] should be zero-cost, while still maintaining safety +- Practicality is key + +[mem]: http://en.wikipedia.org/wiki/Memory_safety +[abs]: http://en.wikipedia.org/wiki/Abstraction_%28computer_science%29 + +# Semantics + +## Data layout is unspecified + +In the general case, `enum` and `struct` layout is undefined. This allows the +compiler to potentially do optimizations like re-using padding for the +discriminant, compacting variants of nested enums, reordering fields to remove +padding, etc. `enum`s which carry no data ("C-like") are eligible to have a +defined representation. Such `enum`s are easily distinguished in that they are +simply a list of names that carry no data: + +``` +enum CLike { + A, + B = 32, + C = 34, + D +} +``` + +The [repr attribute][repr] can be applied to such `enum`s to give them the same +representation as a primitive. This allows using Rust `enum`s in FFI where C +`enum`s are also used, for most use cases. The attribute can also be applied +to `struct`s to get the same layout as a C struct would. + +[repr]: http://doc.rust-lang.org/rust.html#miscellaneous-attributes + +## There is no GC + +A language that requires a GC is a language that opts into a larger, more +complex runtime than Rust cares for. Rust is usable on bare metal with no +extra runtime. Additionally, garbage collection is frequently a source of +non-deterministic behavior. Rust provides the tools to make using a GC +possible and even pleasant, but it should not be a requirement for +implementing the language. + +## Non-`Share` `static mut` is unsafe + +Types which are [`Share`][share] are thread-safe when multiple shared +references to them are used concurrently. Types which are not `Share` are not +thread-safe, and thus when used in a global require unsafe code to use. + +[share]: http://doc.rust-lang.org/core/kinds/trait.Share.html + +### If mutable static items that implement `Share` are safe, why is taking &mut SHARABLE unsafe? + +Having multiple aliasing `&mut T`s is never allowed. Due to the nature of +globals, the borrow checker cannot possibly ensure that a static obeys the +borrowing rules, so taking a mutable reference to a static is always unsafe. + +## There is no life before or after main (no static ctors/dtors) + +Globals can not have a non-constant-expression constructor and cannot have a +destructor at all. This is an opinion of the language. Static constructors are +undesirable because they can slow down program startup. Life before main is +often considered a misfeature, never to be used. Rust helps this along by just +not having the feature. + +See [the C++ FQA][fqa] about the "static initialization order fiasco", and +[Eric Lippert's blog][elp] for the challenges in C#, which also has this +feature. + +A nice replacement is the [lazy constructor macro][lcm] by [Marvin +Löbel][kim]. + +[fqa]: https://mail.mozilla.org/pipermail/rust-dev/2013-April/003815.html +[elp]: http://ericlippert.com/2013/02/06/static-constructors-part-one/ +[lcm]: https://gist.github.com/Kimundi/8782487 +[kim]: https://github.com/Kimundi + +## The language does not require a runtime + +See the above entry on GC. Requiring a runtime limits the utility of the +language, and makes it undeserving of the title "systems language". All Rust +code should need to run is a stack. + +## `match` must be exhaustive + +`match` being exhaustive has some useful properties. First, if every +possibility is covered by the `match`, adding further variants to the `enum` +in the future will prompt a compilation failure, rather than runtime failure. +Second, it makes cost explicit. In general, only safe way to have a +non-exhaustive match would be to fail the task if nothing is matched, though +it could fall through if the type of the `match` expression is `()`. This sort +of hidden cost and special casing is against the language's philosophy. It's +easy to ignore certain cases by using the `_` wildcard: + +```rust,ignore +match val.do_something() { + Cat(a) => { /* ... */ } + _ => { /* ... */ } +} +``` + +[#3101][iss] is the issue that proposed making this the only behavior, with +rationale and discussion. + +[iss]: https://github.com/mozilla/rust/issues/3101 + +## No guaranteed tail-call optimization + +In general, tail-call optimization is not guaranteed: see for a detailed +explanation with references. There is a [proposed extension][tce] that would +allow tail-call elimination in certain contexts. The compiler is still free to +optimize tail-calls [when it pleases][sco], however. + +[tml]: https://mail.mozilla.org/pipermail/rust-dev/2013-April/003557.html +[sco]: http://llvm.org/docs/CodeGenerator.html#sibling-call-optimization +[tce]: https://github.com/rust-lang/rfcs/pull/81 + +## No constructors + +Functions can serve the same purpose as constructors without adding any +language complexity. + +## No copy constructors + +Types which implement [`Copy`][copy], will do a standard C-like "shallow copy" +with no extra work (similar to "plain old data" in C++). It is impossible to +implement `Copy` types that require custom copy behavior. Instead, in Rust +"copy constructors" are created by implementing the [`Clone`][clone] trait, +and explicitly calling the `clone` method. Making user-defined copy operators +explicit surfaces the underlying complexity, forcing the developer to opt-in +to potentially expensive operations. + +[copy]: http://doc.rust-lang.org/core/kinds/trait.Copy.html +[clone]: http://doc.rust-lang.org/core/clone/trait.Clone.html + +## No move constructors + +Values of all types are moved via `memcpy`. This makes writing generic unsafe +code much simpler since assignment, passing and returning are known to never +have a side effect like unwinding. + +# Syntax + +## Macros require balanced delimiters + +This is to make the language easier to parse for machines. Since the body of a +macro can contain arbitrary tokens, some restriction is needed to allow simple +non-macro-expanding lexers and parsers. This comes in the form of requiring +that all delimiters be balanced. + +## `->` for function return type + +This is to make the language easier to parse for humans, especially in the face +of higher-order functions. `fn foo(f: fn(int): int, fn(T): U): U` is not +particularly easy to read. + +## `let` is used to introduce variables + +`let` not only defines variables, but can do pattern matching. One can also +redeclare immutable variables with `let`. This is useful to avoid unnecessary +`mut` annotations. An interesting historical note is that Rust comes, +syntactically, most closely from ML, which also uses `let` to introduce +bindings. + +See also [a long thread][alt] on renaming `let mut` to `var`. + +[alt]: https://mail.mozilla.org/pipermail/rust-dev/2014-January/008319.html diff --git a/src/doc/index.md b/src/doc/index.md index 0bfc9baaa1688..37d03d0867d13 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -23,6 +23,14 @@ li {list-style-type: none; } * [Testing](guide-testing.html) * [Rust's Runtime](guide-runtime.html) +# FAQs + +* [Language Design FAQ](complement-design-faq.html) +* [Language FAQ](complement-lang-faq.html) +* [Project FAQ](complement-project-faq.html) +* [Code cheatsheet](complement-cheatsheet.html) - "How do I do X?" +* [How to submit a bug report](complement-bugreport.html) + # Libraries * [The standard library, `std`](std/index.html) @@ -60,13 +68,6 @@ li {list-style-type: none; } * [The `rustdoc` manual](rustdoc.html) -# FAQs - -* [Language FAQ](complement-lang-faq.html) -* [Project FAQ](complement-project-faq.html) -* [Code cheatsheet](complement-cheatsheet.html) - "How do I do X?" -* [How to submit a bug report](complement-bugreport.html) - # External resources * The Rust IRC channels on [irc.mozilla.org](http://irc.mozilla.org/)