From 54abe4ce915d00ffc07d9077aebeedd052be29fa Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 14 Apr 2015 15:01:05 -0400 Subject: [PATCH 01/19] link to ownership for now --- src/doc/trpl/lifetimes.md | 2 +- src/doc/trpl/references-and-borrowing.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/trpl/lifetimes.md b/src/doc/trpl/lifetimes.md index c6eee97dc6a61..cfcd8c4ee155a 100644 --- a/src/doc/trpl/lifetimes.md +++ b/src/doc/trpl/lifetimes.md @@ -1,3 +1,3 @@ % Lifetimes -Coming soon! +Coming Soon! Until then, check out the [ownership](ownership.html) chapter. diff --git a/src/doc/trpl/references-and-borrowing.md b/src/doc/trpl/references-and-borrowing.md index 6acb326958d31..0e13ea612645c 100644 --- a/src/doc/trpl/references-and-borrowing.md +++ b/src/doc/trpl/references-and-borrowing.md @@ -1,3 +1,3 @@ % References and Borrowing -Coming Soon! +Coming Soon! Until then, check out the [ownership](ownership.html) chapter. From e5631f94b4963b08a726007fc775311bd95957f8 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 15 Apr 2015 11:34:39 -0400 Subject: [PATCH 02/19] TRPL: move semantics --- src/doc/trpl/move-semantics.md | 104 ++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/src/doc/trpl/move-semantics.md b/src/doc/trpl/move-semantics.md index 6917d7f8b8e0f..0e7a1130561eb 100644 --- a/src/doc/trpl/move-semantics.md +++ b/src/doc/trpl/move-semantics.md @@ -1,3 +1,105 @@ % Move Semantics -Coming Soon +An important aspect of [ownership][ownership] is ‘move semantics’. Move +semantics control how and when ownership is transferred between bindings. + +[ownership]: ownership.html + +For example, consider a type like `Vec`, which owns its contents: + +```rust +let v = vec![1, 2, 3]; +``` + +I can assign this vector to another binding: + +```rust +let v = vec![1, 2, 3]; + +let v2 = v; +``` + +But, if we try to use `v` afterwards, we get an error: + +```rust,ignore +let v = vec![1, 2, 3]; + +let v2 = v; + +println!("v[0] is: {}", v[0]); +``` + +It looks like this: + +```text +error: use of moved value: `v` +println!("v[0] is: {}", v[0]); + ^ +``` + +A similar thing happens if we define a function which takes ownership, and +try to use something after we’ve passed it as an argument: + +```rust +fn take(v: Vec) { + // what happens here isn’t important. +} + +let v = vec![1, 2, 3]; + +take(v); + +println!("v[0] is: {}", v[0]); +``` + +Same error: “use of moved value.” When we transfer ownership to something else, +we say that we’ve ‘moved’ the thing we refer to. You don’t need some sort of +special annotation here, it’s the default thing that Rust does. + +# The details + +The reason that we cannot use a binding after we’ve moved it is subtle, but +important. When we write code like this: + +```rust +let v = vec![1, 2, 3]; + +let v2 = v; +``` + +The first line creates some data for the vector on the stack, `v`. The vector’s +data, however, is stored on the heap, and so it contains a pointer to that +data. When we move `v` to `v2`, it creates a copy of that data, for `v2`. Which +would mean two pointers to the contents of the vector on the heap. That would +be a problem: it would violate Rust’s safety guarantees by introducing a data +race. Therefore, Rust forbids using `v` after we’ve done the move. + +It’s also important to note that optimizations may remove the actual copy of +the bytes, depending on circumstances. So it may not be as inefficient as it +initially seems. + +# `Copy` types + +We’ve established that when ownership is transferred to another binding, you +cannot use the original binding. However, there’s a [trait][traits] that changes this +behavior, and it’s called `Copy`. We haven’t discussed traits yet, but for now, +you can think of them as an annotation to a particular type that adds extra +behavior. For example: + +```rust +let v = 1; + +let v2 = v; + +println!("v is: {}", v); +``` + +In this case, `v` is an `i32`, which implements the `Copy` trait. This means +that, just like a move, when we assign `v` to `v2`, a copy of the data is made. +But, unlike a move, we can still use `v` afterward. This is because an `i32` +has no pointers to data somewhere else, copying it is a full copy. + +We will discuss how to make your own types `Copy` in the [traits][traits] +section. + +[traits]: traits.html From dd5eed4b8136849537d1b2c8655bd29dc976d89a Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Sat, 11 Apr 2015 08:14:38 +1000 Subject: [PATCH 03/19] Validate format of extended error descriptions. --- src/libsyntax/diagnostics/plugin.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/libsyntax/diagnostics/plugin.rs b/src/libsyntax/diagnostics/plugin.rs index 59fe3658437bd..de7964c92303b 100644 --- a/src/libsyntax/diagnostics/plugin.rs +++ b/src/libsyntax/diagnostics/plugin.rs @@ -92,6 +92,18 @@ pub fn expand_register_diagnostic<'cx>(ecx: &'cx mut ExtCtxt, } _ => unreachable!() }; + // Check that the description starts and ends with a newline. + description.map(|raw_msg| { + let msg = raw_msg.as_str(); + let last = msg.len() - 1; + if &msg[0..1] != "\n" || &msg[last..] != "\n" { + ecx.span_err(span, &format!( + "description for error code {} doesn't start and end with a newline", + token::get_ident(*code) + )); + } + raw_msg + }); with_registered_diagnostics(|diagnostics| { if diagnostics.insert(code.name, description).is_some() { ecx.span_err(span, &format!( From c54f43a5d18c89f65f22a179e8e6d05ce9c1d36c Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Wed, 15 Apr 2015 18:12:28 +1000 Subject: [PATCH 04/19] Update/add messages for E0{267,268,296,303}. --- src/librustc/diagnostics.rs | 39 +++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index e1eb8d7418695..fedcd582cd990 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -217,6 +217,26 @@ use Method::*; enum Method { GET, POST } "##, +E0267: r##" +This error indicates the use of loop keyword (break or continue) inside a +closure but outside of any loop. Break and continue can be used as normal +inside closures as long as they are also contained within a loop. To halt the +execution of a closure you should instead use a return statement. +"##, + +E0268: r##" +This error indicates the use of loop keyword (break or continue) outside of a +loop. Without a loop to break out of or continue in, no sensible action can be +taken. +"##, + +E0296: r##" +This error indicates that the given recursion limit could not be parsed. Ensure +that the value provided is a positive integer between quotes, like so: + +#![recursion_limit="1000"] +"##, + E0297: r##" Patterns used to bind names must be irrefutable. That is, they must guarantee that a name will be extracted in all cases. Instead of pattern matching the @@ -277,21 +297,23 @@ In certain cases it is possible for sub-bindings to violate memory safety. Updates to the borrow checker in a future version of Rust may remove this restriction, but for now patterns must be rewritten without sub-bindings. -// Code like this... -match Some(5) { - ref op_num @ Some(num) => ... +// Before. +match Some("hi".to_string()) { + ref op_string_ref @ Some(ref s) => ... None => ... } -// ... should be updated to code like this. -match Some(5) { - Some(num) => { - let op_num = &Some(num); +// After. +match Some("hi".to_string()) { + Some(ref s) => { + let op_string_ref = &Some(&s); ... } None => ... } +The `op_string_ref` binding has type &Option<&String> in both cases. + See also https://github.com/rust-lang/rust/issues/14587 "##, @@ -338,8 +360,6 @@ register_diagnostics! { E0264, // unknown external lang item E0265, // recursive constant E0266, // expected item - E0267, // thing inside of a closure - E0268, // thing outside of a loop E0269, // not all control paths return a value E0270, // computation may converge in a function marked as diverging E0271, // type mismatch resolving @@ -357,7 +377,6 @@ register_diagnostics! { E0283, // cannot resolve type E0284, // cannot resolve type E0285, // overflow evaluation builtin bounds - E0296, // malformed recursion limit attribute E0298, // mismatched types between arms E0299, // mismatched types between arms E0300, // unexpanded macro From 6d2b6d5a19224eee279c44e8ff2bb37ba331d1df Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Wed, 15 Apr 2015 21:54:01 +1000 Subject: [PATCH 05/19] Enforce 80 char lines in extended errors. --- src/librustc/diagnostics.rs | 14 ++++++++------ src/libsyntax/diagnostics/plugin.rs | 15 ++++++++++++--- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index fedcd582cd990..092d0cc442402 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -55,15 +55,17 @@ underscore `_` wildcard pattern can be added after all other patterns to match // FIXME: Remove duplication here? E0005: r##" -Patterns used to bind names must be irrefutable, that is, they must guarantee that a -name will be extracted in all cases. If you encounter this error you probably need -to use a `match` or `if let` to deal with the possibility of failure. +Patterns used to bind names must be irrefutable, that is, they must guarantee +that a name will be extracted in all cases. If you encounter this error you +probably need to use a `match` or `if let` to deal with the possibility of +failure. "##, E0006: r##" -Patterns used to bind names must be irrefutable, that is, they must guarantee that a -name will be extracted in all cases. If you encounter this error you probably need -to use a `match` or `if let` to deal with the possibility of failure. +Patterns used to bind names must be irrefutable, that is, they must guarantee +that a name will be extracted in all cases. If you encounter this error you +probably need to use a `match` or `if let` to deal with the possibility of +failure. "##, E0007: r##" diff --git a/src/libsyntax/diagnostics/plugin.rs b/src/libsyntax/diagnostics/plugin.rs index de7964c92303b..6fcf39f0b174b 100644 --- a/src/libsyntax/diagnostics/plugin.rs +++ b/src/libsyntax/diagnostics/plugin.rs @@ -20,6 +20,9 @@ use parse::token; use ptr::P; use util::small_vector::SmallVector; +// Maximum width of any line in an extended error description (inclusive). +const MAX_DESCRIPTION_WIDTH: usize = 80; + thread_local! { static REGISTERED_DIAGNOSTICS: RefCell>> = { RefCell::new(BTreeMap::new()) @@ -92,16 +95,22 @@ pub fn expand_register_diagnostic<'cx>(ecx: &'cx mut ExtCtxt, } _ => unreachable!() }; - // Check that the description starts and ends with a newline. + // Check that the description starts and ends with a newline and doesn't + // overflow the maximum line width. description.map(|raw_msg| { let msg = raw_msg.as_str(); - let last = msg.len() - 1; - if &msg[0..1] != "\n" || &msg[last..] != "\n" { + if !msg.starts_with("\n") || !msg.ends_with("\n") { ecx.span_err(span, &format!( "description for error code {} doesn't start and end with a newline", token::get_ident(*code) )); } + if msg.lines().any(|line| line.len() > MAX_DESCRIPTION_WIDTH) { + ecx.span_err(span, &format!( + "description for error code {} contains a line longer than {} characters", + token::get_ident(*code), MAX_DESCRIPTION_WIDTH + )); + } raw_msg }); with_registered_diagnostics(|diagnostics| { From cc267cefcb4ffc4650d7307c7e31f0ce2cddbba4 Mon Sep 17 00:00:00 2001 From: Tamir Duberstein Date: Fri, 17 Apr 2015 07:35:35 -0700 Subject: [PATCH 06/19] Clarify comment --- Makefile.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile.in b/Makefile.in index ec5c099372bfb..8fc66a764da61 100644 --- a/Makefile.in +++ b/Makefile.in @@ -76,7 +76,7 @@ # # * `CFG_ENABLE_VALGRIND=1` - Run tests under valgrind # * `VALGRIND_COMPILE=1` - Run the compiler itself under valgrind -# (may require `CFG_ENABLE_VALGRIND`) +# (requires `CFG_ENABLE_VALGRIND`) # # * `NO_REBUILD=1` - Don't rebootstrap when testing std # (and possibly other crates) From 1dee7b0160fd708c8d5ccc6be5099f40e9d3bbba Mon Sep 17 00:00:00 2001 From: Tamir Duberstein Date: Fri, 17 Apr 2015 07:45:16 -0700 Subject: [PATCH 07/19] Run valgrind with fair scheduling when available Closes #3914. --- mk/platform.mk | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mk/platform.mk b/mk/platform.mk index cd86b273c6de2..9545a1fb52d9e 100644 --- a/mk/platform.mk +++ b/mk/platform.mk @@ -46,8 +46,9 @@ endif # see https://blog.mozilla.org/jseward/2012/06/05/valgrind-now-supports-jemalloc-builds-directly/ ifdef CFG_VALGRIND CFG_VALGRIND += --error-exitcode=100 \ - --soname-synonyms=somalloc=NONE \ + --fair-sched=try \ --quiet \ + --soname-synonyms=somalloc=NONE \ --suppressions=$(CFG_SRC_DIR)src/etc/x86.supp \ $(OS_SUPP) ifdef CFG_ENABLE_HELGRIND From a5e53472c77b8113c2d9909531433088138b20d5 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Fri, 17 Apr 2015 10:00:37 -0700 Subject: [PATCH 08/19] Bump prerelease to .3 --- mk/main.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mk/main.mk b/mk/main.mk index ec5deab5e24b7..c5b2fc8b9531e 100644 --- a/mk/main.mk +++ b/mk/main.mk @@ -18,7 +18,7 @@ CFG_RELEASE_NUM=1.0.0 # An optional number to put after the label, e.g. '.2' -> '-beta.2' # NB Make sure it starts with a dot to conform to semver pre-release # versions (section 9) -CFG_PRERELEASE_VERSION=.2 +CFG_PRERELEASE_VERSION=.3 CFG_FILENAME_EXTRA=4e7c5e5c From 22ce069c7e4e008d4835a669b85bee3d93a84172 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Thu, 16 Apr 2015 00:46:41 -0500 Subject: [PATCH 09/19] Add long diagnostics for E0020 --- src/librustc/diagnostics.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index 092d0cc442402..4f1fc4150fd47 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -114,6 +114,11 @@ reference when using guards or refactor the entire expression, perhaps by putting the condition inside the body of the arm. "##, +E0020: r##" +This error indicates that an attempt was made to divide by zero (or take the +remainder of a zero divisor) in a static or constant expression. +"##, + E0152: r##" Lang items are already implemented in the standard library. Unless you are writing a free-standing application (e.g. a kernel), you do not need to provide @@ -343,7 +348,6 @@ register_diagnostics! { E0017, E0018, E0019, - E0020, E0022, E0079, // enum variant: expected signed integer constant E0080, // enum variant: constant evaluation error From 017bc44712b94d22165672fd546b7e084fc3b404 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Thu, 16 Apr 2015 00:47:31 -0500 Subject: [PATCH 10/19] Add long diagnostics for E0015 --- src/librustc/diagnostics.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index 4f1fc4150fd47..24d920077d628 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -114,6 +114,12 @@ reference when using guards or refactor the entire expression, perhaps by putting the condition inside the body of the arm. "##, +E0015: r##" +The only function calls allowed in static or constant expressions are enum +variant constructors or struct constructors (for unit or tuple structs). This +is because Rust currently does not support compile-time function execution. +"##, + E0020: r##" This error indicates that an attempt was made to divide by zero (or take the remainder of a zero divisor) in a static or constant expression. @@ -343,7 +349,6 @@ register_diagnostics! { E0012, E0013, E0014, - E0015, E0016, E0017, E0018, From 50f75f3e2a4b8cb5451acb15f8d469a222dafbf4 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 15 Apr 2015 12:31:56 +0200 Subject: [PATCH 11/19] Add long diagnostics for "bind by-ref and by-move" --- src/librustc/diagnostics.rs | 49 ++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index 24d920077d628..306d2cd102fdb 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -114,6 +114,54 @@ reference when using guards or refactor the entire expression, perhaps by putting the condition inside the body of the arm. "##, +E0009: r##" +In a pattern, all values that don't implement the `Copy` trait have to be bound +the same way. The goal here is to avoid binding simultaneously by-move and +by-ref. + +This limitation may be removed in a future version of Rust. + +Wrong example: + +``` +struct X { x: (), } + +let x = Some((X { x: () }, X { x: () })); +match x { + Some((y, ref z)) => {}, + None => panic!() +} +``` + +You have two solutions: +1. Bind the pattern's values the same way: + +``` +struct X { x: (), } + +let x = Some((X { x: () }, X { x: () })); +match x { + Some((ref y, ref z)) => {}, + // or Some((y, z)) => {} + None => panic!() +} +``` + +2. Implement the `Copy` trait for the X structure (however, please +keep in mind that the first solution should be preferred!): + +``` +#[derive(Clone, Copy)] +struct X { x: (), } + +let x = Some((X { x: () }, X { x: () })); +match x { + Some((y, ref z)) => {}, + None => panic!() +} +``` +"##, + E0015: r##" The only function calls allowed in static or constant expressions are enum variant constructors or struct constructors (for unit or tuple structs). This @@ -343,7 +391,6 @@ a compile-time constant. } register_diagnostics! { - E0009, E0010, E0011, E0012, From ca14b8121c94c68fdc44f12e58472a574846ac46 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Fri, 17 Apr 2015 19:22:19 -0700 Subject: [PATCH 12/19] Trim malformed sentence. --- src/doc/grammar.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/doc/grammar.md b/src/doc/grammar.md index 1ea3c7d7bd9d8..1dec68211d4a1 100644 --- a/src/doc/grammar.md +++ b/src/doc/grammar.md @@ -5,8 +5,7 @@ This document is the primary reference for the Rust programming language grammar. It provides only one kind of material: - - Chapters that formally define the language grammar and, for each - construct. + - Chapters that formally define the language grammar. This document does not serve as an introduction to the language. Background familiarity with the language is assumed. A separate [guide] is available to From 806d0247831d3b5a89ce8962cbf3546a18470a99 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Fri, 17 Apr 2015 19:24:28 -0700 Subject: [PATCH 13/19] Trim florid language. --- src/doc/reference.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index 57110df0f9e03..fb03ba1600a49 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -735,13 +735,11 @@ Rust syntax is restricted in two ways: # Crates and source files -Rust is a *compiled* language. Its semantics obey a *phase distinction* -between compile-time and run-time. Those semantic rules that have a *static -interpretation* govern the success or failure of compilation. We refer to -these rules as "static semantics". Semantic rules called "dynamic semantics" -govern the behavior of programs at run-time. A program that fails to compile -due to violation of a compile-time rule has no defined dynamic semantics; the -compiler should halt with an error report, and produce no executable artifact. +Rust is a *compiled* language. Its semantics obey a *phase distinction* between +compile-time and run-time. Those semantic rules that have a *static +interpretation* govern the success or failure of compilation. Those semantics +that have a *dynamic interpretation* govern the behavior of the program at +run-time. The compilation model centers on artifacts called _crates_. Each compilation processes a single crate in source form, and if successful, produces a single From 21e2e6eec86e84eee765c91803f3488a21923a67 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Fri, 17 Apr 2015 19:29:20 -0700 Subject: [PATCH 14/19] Clean up section on Type aliases. --- src/doc/reference.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index fb03ba1600a49..41330555b3f96 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -1300,18 +1300,11 @@ contiguous stack segments like C. A _type alias_ defines a new name for an existing [type](#types). Type aliases are declared with the keyword `type`. Every value has a single, -specific type; the type-specified aspects of a value include: - -* Whether the value is composed of sub-values or is indivisible. -* Whether the value represents textual or numerical information. -* Whether the value represents integral or floating-point information. -* The sequence of memory operations required to access the value. -* The [kind](#type-kinds) of the type. - -For example, the type `(u8, u8)` defines the set of immutable values that are -composite pairs, each containing two unsigned 8-bit integers accessed by -pattern-matching and laid out in memory with the `x` component preceding the -`y` component: +specific type, but may implement several different traits, or be compatible with +several different type constraints. + +For example, the following defines the type `Point` as a synonym for the type +`(u8, u8)`, the type of pairs of unsigned 8 bit integers.: ``` type Point = (u8, u8); From 7f2f09f1b49777cdc8683efe2ce4bdc6ded3603f Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Fri, 17 Apr 2015 19:52:29 -0700 Subject: [PATCH 15/19] Eliminate the obsolete term 'slot'. --- src/doc/complement-lang-faq.md | 2 +- src/doc/grammar.md | 6 ++--- src/doc/reference.md | 48 +++++++++++++++++----------------- 3 files changed, 28 insertions(+), 28 deletions(-) diff --git a/src/doc/complement-lang-faq.md b/src/doc/complement-lang-faq.md index 8238dd3a5ba42..f731a78ef1254 100644 --- a/src/doc/complement-lang-faq.md +++ b/src/doc/complement-lang-faq.md @@ -124,7 +124,7 @@ Yes. Calling C code from Rust is simple and exactly as efficient as calling C co Yes. The Rust code has to be exposed via an `extern` declaration, which makes it C-ABI compatible. Such a function can be passed to C code as a function pointer or, if given the `#[no_mangle]` attribute to disable symbol mangling, can be called directly from C code. -## Why aren't function signatures inferred? Why only local slots? +## Why aren't function signatures inferred? Why only local variables? * Mechanically, it simplifies the inference algorithm; inference only requires looking at one function at a time. * The same simplification goes double for human readers. A reader does not need an IDE running an inference algorithm across an entire crate to be able to guess at a function's argument types; it's always explicit and nearby. diff --git a/src/doc/grammar.md b/src/doc/grammar.md index 1dec68211d4a1..3d9a5bafbd71e 100644 --- a/src/doc/grammar.md +++ b/src/doc/grammar.md @@ -426,7 +426,7 @@ meta_seq : meta_item [ ',' meta_seq ] ? ; **FIXME:** grammar? A _declaration statement_ is one that introduces one or more *names* into the -enclosing statement block. The declared names may denote new slots or new +enclosing statement block. The declared names may denote new variables or new items. #### Item declarations @@ -440,7 +440,7 @@ function, enumeration, structure, type, static, trait, implementation or module scope to a narrow region containing all of its uses; it is otherwise identical in meaning to declaring the item outside the statement block. -#### Slot declarations +#### Variable declarations ```antlr let_decl : "let" pat [':' type ] ? [ init ] ? ';' ; @@ -762,7 +762,7 @@ bound := path | lifetime ### Memory ownership -### Memory slots +### Variables ### Boxes diff --git a/src/doc/reference.md b/src/doc/reference.md index 41330555b3f96..2f0d8b1756a86 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -564,7 +564,7 @@ type_path_tail : '<' type_expr [ ',' type_expr ] + '>' A _path_ is a sequence of one or more path components _logically_ separated by a namespace qualifier (`::`). If a path consists of only one component, it may -refer to either an [item](#items) or a [slot](#memory-slots) in a local control +refer to either an [item](#items) or a [variable](#variables) in a local control scope. If a path has multiple components, it refers to an item. Every item has a _canonical path_ within its crate, but the path naming an item @@ -1062,9 +1062,9 @@ fn main() {} A _function item_ defines a sequence of [statements](#statements) and an optional final [expression](#expressions), along with a name and a set of parameters. Functions are declared with the keyword `fn`. Functions declare a -set of *input* [*slots*](#memory-slots) as parameters, through which the caller -passes arguments into the function, and an *output* [*slot*](#memory-slots) -through which the function passes results back to the caller. +set of *input* [*variables*](#variables) as parameters, through which the caller +passes arguments into the function, and the *output* [*type*](#types) +of the value the function will return to its caller on completion. A function may also be copied into a first-class *value*, in which case the value has the corresponding [*function type*](#function-types), and can be used @@ -1227,7 +1227,7 @@ be undesired. #### Diverging functions A special kind of function can be declared with a `!` character where the -output slot type would normally be. For example: +output type would normally be. For example: ``` fn my_err(s: &str) -> ! { @@ -2542,7 +2542,7 @@ statements](#expression-statements). ### Declaration statements A _declaration statement_ is one that introduces one or more *names* into the -enclosing statement block. The declared names may denote new slots or new +enclosing statement block. The declared names may denote new variables or new items. #### Item declarations @@ -2557,18 +2557,18 @@ in meaning to declaring the item outside the statement block. > **Note**: there is no implicit capture of the function's dynamic environment when > declaring a function-local item. -#### Slot declarations +#### Variable declarations ```{.ebnf .gram} let_decl : "let" pat [':' type ] ? [ init ] ? ';' ; init : [ '=' ] expr ; ``` -A _slot declaration_ introduces a new set of slots, given by a pattern. The +A _variable declaration_ introduces a new set of variable, given by a pattern. The pattern may be followed by a type annotation, and/or an initializer expression. When no type annotation is given, the compiler will infer the type, or signal an error if insufficient type information is available for definite inference. -Any slots introduced by a slot declaration are visible from the point of +Any variables introduced by a variable declaration are visible from the point of declaration until the end of the enclosing block scope. ### Expression statements @@ -2623,7 +2623,7 @@ of any reference that points to it. #### Moved and copied types -When a [local variable](#memory-slots) is used as an +When a [local variable](#variables) is used as an [rvalue](#lvalues,-rvalues-and-temporaries) the variable will either be moved or copied, depending on its type. All values whose type implements `Copy` are copied, all others are moved. @@ -3033,10 +3033,9 @@ paren_expr_list : '(' expr_list ')' ; call_expr : expr paren_expr_list ; ``` -A _call expression_ invokes a function, providing zero or more input slots and -an optional reference slot to serve as the function's output, bound to the -`lval` on the right hand side of the call. If the function eventually returns, -then the expression completes. +A _call expression_ invokes a function, providing zero or more input variables +and an optional location to move the function's output into. If the function +eventually returns, then the expression completes. Some examples of call expressions: @@ -3447,9 +3446,9 @@ return_expr : "return" expr ? ; ``` Return expressions are denoted with the keyword `return`. Evaluating a `return` -expression moves its argument into the output slot of the current function, -destroys the current function activation frame, and transfers control to the -caller frame. +expression moves its argument into the designated output location for the +current function call, destroys the current function activation frame, and +transfers control to the caller frame. An example of a `return` expression: @@ -3466,7 +3465,7 @@ fn max(a: i32, b: i32) -> i32 { ## Types -Every slot, item and value in a Rust program has a type. The _type_ of a +Every variable, item and value in a Rust program has a type. The _type_ of a *value* defines the interpretation of the memory holding it. Built-in types and type-constructors are tightly integrated into the language, @@ -3484,7 +3483,7 @@ The primitive types are the following: * The machine-dependent integer and floating-point types. [^unittype]: The "unit" value `()` is *not* a sentinel "null pointer" value for - reference slots; the "unit" type is the implicit return type from functions + reference variables; the "unit" type is the implicit return type from functions otherwise lacking a return type, and can be used in other contexts (such as message-sending or type-parametric code) as a zero-size type.] @@ -3844,7 +3843,7 @@ A Rust program's memory consists of a static set of *items* and a *heap*. Immutable portions of the heap may be shared between threads, mutable portions may not. -Allocations in the stack consist of *slots*, and allocations in the heap +Allocations in the stack consist of *variables*, and allocations in the heap consist of *boxes*. ### Memory allocation and lifetime @@ -3863,10 +3862,11 @@ in the heap, heap allocations may outlive the frame they are allocated within. When a stack frame is exited, its local allocations are all released, and its references to boxes are dropped. -### Memory slots +### Variables -A _slot_ is a component of a stack frame, either a function parameter, a -[temporary](#lvalues,-rvalues-and-temporaries), or a local variable. +A _variable_ is a component of a stack frame, either a named function parameter, +an anonymous [temporary](#lvalues,-rvalues-and-temporaries), or a named local +variable. A _local variable_ (or *stack-local* allocation) holds a value directly, allocated within the stack's memory. The value is a part of the stack frame. @@ -3879,7 +3879,7 @@ Box, y: Box)` declare one mutable variable `x` and one immutable variable `y`). Methods that take either `self` or `Box` can optionally place them in a -mutable slot by prefixing them with `mut` (similar to regular arguments): +mutable variable by prefixing them with `mut` (similar to regular arguments): ``` trait Changer { From f5b296310320a49897e05112f8fb739d55cdf695 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Fri, 17 Apr 2015 20:00:47 -0700 Subject: [PATCH 16/19] Improve special-traits section very slightly. --- src/doc/reference.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index 2f0d8b1756a86..477929af3b6f0 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -3821,18 +3821,20 @@ impl Printable for String { `self` refers to the value of type `String` that is the receiver for a call to the method `make_string`. -# The `Copy` trait +# Special traits -Rust has a special trait, `Copy`, which when implemented changes the semantics -of a value. Values whose type implements `Copy` are copied rather than moved -upon assignment. +Several traits define special evaluation behavior. -# The `Sized` trait +## The `Copy` trait -`Sized` is a special trait which indicates that the size of this type is known -at compile-time. +The `Copy` trait changes the semantics of a type implementing it. Values whose +type implements `Copy` are copied rather than moved upon assignment. -# The `Drop` trait +## The `Sized` trait + +The `Sized` trait indicates that the size of this type is known at compile-time. + +## The `Drop` trait The `Drop` trait provides a destructor, to be run whenever a value of this type is to be destroyed. From 744085ed1dad34a865a78b57ecdbb2849a7b1b87 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Fri, 17 Apr 2015 20:01:03 -0700 Subject: [PATCH 17/19] Improve memory-model section very slightly. --- src/doc/reference.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index 477929af3b6f0..9b1d23494adba 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -3842,8 +3842,10 @@ is to be destroyed. # Memory model A Rust program's memory consists of a static set of *items* and a *heap*. -Immutable portions of the heap may be shared between threads, mutable portions -may not. +Immutable portions of the heap may be safely shared between threads, mutable +portions may not be safely shared, but several mechanisms for effectively-safe +sharing of mutable values, built on unsafe code but enforcing a safe locking +discipline, exist in the standard library. Allocations in the stack consist of *variables*, and allocations in the heap consist of *boxes*. From a99a8b0a927822bfbbfad1ec0c24378a6a914688 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Fri, 17 Apr 2015 20:02:55 -0700 Subject: [PATCH 18/19] Remove obsolete discusison of runtime, promote `Linkage` to chapter. --- src/doc/reference.md | 39 +-------------------------------------- 1 file changed, 1 insertion(+), 38 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index 9b1d23494adba..c159f6164c205 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -3898,44 +3898,7 @@ state. Subsequent statements within a function may or may not initialize the local variables. Local variables can be used only after they have been initialized; this is enforced by the compiler. -# Runtime services, linkage and debugging - -The Rust _runtime_ is a relatively compact collection of Rust code that -provides fundamental services and datatypes to all Rust threads at run-time. It -is smaller and simpler than many modern language runtimes. It is tightly -integrated into the language's execution model of memory, threads, communication -and logging. - -### Memory allocation - -The runtime memory-management system is based on a _service-provider -interface_, through which the runtime requests blocks of memory from its -environment and releases them back to its environment when they are no longer -needed. The default implementation of the service-provider interface consists -of the C runtime functions `malloc` and `free`. - -The runtime memory-management system, in turn, supplies Rust threads with -facilities for allocating releasing stacks, as well as allocating and freeing -heap data. - -### Built in types - -The runtime provides C and Rust code to assist with various built-in types, -such as arrays, strings, and the low level communication system (ports, -channels, threads). - -Support for other built-in types such as simple types, tuples and enums is -open-coded by the Rust compiler. - -### Thread scheduling and communication - -The runtime provides code to manage inter-thread communication. This includes -the system of thread-lifecycle state transitions depending on the contents of -queues, as well as code to copy values between queues and their recipients and -to serialize values for transmission over operating-system inter-process -communication facilities. - -### Linkage +# Linkage The Rust compiler supports various methods to link crates together both statically and dynamically. This section will explore the various methods to From 88601f8d7d0784a2fe502193b9d98edd3e7d88ea Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Sun, 19 Apr 2015 00:54:42 +0530 Subject: [PATCH 19/19] fix doctest (fixup #24466) --- src/doc/trpl/move-semantics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/move-semantics.md b/src/doc/trpl/move-semantics.md index 0e7a1130561eb..b5bd53e1d75a1 100644 --- a/src/doc/trpl/move-semantics.md +++ b/src/doc/trpl/move-semantics.md @@ -40,7 +40,7 @@ println!("v[0] is: {}", v[0]); A similar thing happens if we define a function which takes ownership, and try to use something after we’ve passed it as an argument: -```rust +```rust,ignore fn take(v: Vec) { // what happens here isn’t important. }