bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #24548 - graydon:reference-tidying, r=steveklabnik

Browse source 
This just deletes some egregious lies and obsolete terminology -- all of which I originally wrote -- from the reference. I expect the reference itself will be deleted soon enough, but I found myself gritting teeth over these bits too much to let them into a 1.0 release.
This commit is contained in:
Manish Goregaokar 2015-04-18 23:29:58 +05:30
commit 695efb53d6
3 changed files with 53 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

2
src/doc/complement-lang-faq.md
View file

@ -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. 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. * 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. * 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.

9
src/doc/grammar.md
View file

@ -5,8 +5,7 @@
This document is the primary reference for the Rust programming language grammar. It This document is the primary reference for the Rust programming language grammar. It
provides only one kind of material: provides only one kind of material:
- Chapters that formally define the language grammar and, for each - Chapters that formally define the language grammar.
construct.
This document does not serve as an introduction to the language. Background This document does not serve as an introduction to the language. Background
familiarity with the language is assumed. A separate [guide] is available to familiarity with the language is assumed. A separate [guide] is available to
@ -427,7 +426,7 @@ meta_seq : meta_item [ ',' meta_seq ] ? ;
**FIXME:** grammar? **FIXME:** grammar?
A _declaration statement_ is one that introduces one or more *names* into the 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. items.
#### Item declarations #### Item declarations
@ -441,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 scope to a narrow region containing all of its uses; it is otherwise identical
in meaning to declaring the item outside the statement block. in meaning to declaring the item outside the statement block.
#### Slot declarations #### Variable declarations
```antlr ```antlr
let_decl : "let" pat [':' type ] ? [ init ] ? ';' ; let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
@ -763,7 +762,7 @@ bound := path | lifetime
### Memory ownership ### Memory ownership
### Memory slots ### Variables
### Boxes ### Boxes

138
src/doc/reference.md
View file

@ -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 _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 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. 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 Every item has a _canonical path_ within its crate, but the path naming an item
@ -735,13 +735,11 @@ Rust syntax is restricted in two ways:
# Crates and source files # Crates and source files
Rust is a *compiled* language. Its semantics obey a *phase distinction* Rust is a *compiled* language. Its semantics obey a *phase distinction* between
between compile-time and run-time. Those semantic rules that have a *static compile-time and run-time. Those semantic rules that have a *static
interpretation* govern the success or failure of compilation. We refer to interpretation* govern the success or failure of compilation. Those semantics
these rules as "static semantics". Semantic rules called "dynamic semantics" that have a *dynamic interpretation* govern the behavior of the program at
govern the behavior of programs at run-time. A program that fails to compile run-time.
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.
The compilation model centers on artifacts called _crates_. Each compilation The compilation model centers on artifacts called _crates_. Each compilation
processes a single crate in source form, and if successful, produces a single processes a single crate in source form, and if successful, produces a single
@ -1064,9 +1062,9 @@ fn main() {}
A _function item_ defines a sequence of [statements](#statements) and an A _function item_ defines a sequence of [statements](#statements) and an
optional final [expression](#expressions), along with a name and a set of optional final [expression](#expressions), along with a name and a set of
parameters. Functions are declared with the keyword `fn`. Functions declare a parameters. Functions are declared with the keyword `fn`. Functions declare a
set of *input* [*slots*](#memory-slots) as parameters, through which the caller set of *input* [*variables*](#variables) as parameters, through which the caller
passes arguments into the function, and an *output* [*slot*](#memory-slots) passes arguments into the function, and the *output* [*type*](#types)
through which the function passes results back to the caller. 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 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 value has the corresponding [*function type*](#function-types), and can be used
@ -1229,7 +1227,7 @@ be undesired.
#### Diverging functions #### Diverging functions
A special kind of function can be declared with a `!` character where the 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) -> ! { fn my_err(s: &str) -> ! {
@ -1302,18 +1300,11 @@ contiguous stack segments like C.
A _type alias_ defines a new name for an existing [type](#types). Type 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, aliases are declared with the keyword `type`. Every value has a single,
specific type; the type-specified aspects of a value include: specific type, but may implement several different traits, or be compatible with
several different type constraints.
* Whether the value is composed of sub-values or is indivisible. For example, the following defines the type `Point` as a synonym for the type
* Whether the value represents textual or numerical information. `(u8, u8)`, the type of pairs of unsigned 8 bit integers.:
* 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:
``` ```
type Point = (u8, u8); type Point = (u8, u8);
@ -2551,7 +2542,7 @@ statements](#expression-statements).
### Declaration statements ### Declaration statements
A _declaration statement_ is one that introduces one or more *names* into the 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. items.
#### Item declarations #### Item declarations
@ -2566,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 > **Note**: there is no implicit capture of the function's dynamic environment when
> declaring a function-local item. > declaring a function-local item.
#### Slot declarations #### Variable declarations
```{.ebnf .gram} ```{.ebnf .gram}
let_decl : "let" pat [':' type ] ? [ init ] ? ';' ; let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
init : [ '=' ] expr ; 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. 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 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. 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. declaration until the end of the enclosing block scope.
### Expression statements ### Expression statements
@ -2632,7 +2623,7 @@ of any reference that points to it.
#### Moved and copied types #### 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 [rvalue](#lvalues,-rvalues-and-temporaries) the variable will either be moved
or copied, depending on its type. All values whose type implements `Copy` are or copied, depending on its type. All values whose type implements `Copy` are
copied, all others are moved. copied, all others are moved.
@ -3042,10 +3033,9 @@ paren_expr_list : '(' expr_list ')' ;
call_expr : expr paren_expr_list ; call_expr : expr paren_expr_list ;
``` ```
A _call expression_ invokes a function, providing zero or more input slots and A _call expression_ invokes a function, providing zero or more input variables
an optional reference slot to serve as the function's output, bound to the and an optional location to move the function's output into. If the function
`lval` on the right hand side of the call. If the function eventually returns, eventually returns, then the expression completes.
then the expression completes.
Some examples of call expressions: Some examples of call expressions:
@ -3456,9 +3446,9 @@ return_expr : "return" expr ? ;
``` ```
Return expressions are denoted with the keyword `return`. Evaluating a `return` Return expressions are denoted with the keyword `return`. Evaluating a `return`
expression moves its argument into the output slot of the current function, expression moves its argument into the designated output location for the
destroys the current function activation frame, and transfers control to the current function call, destroys the current function activation frame, and
caller frame. transfers control to the caller frame.
An example of a `return` expression: An example of a `return` expression:
@ -3475,7 +3465,7 @@ fn max(a: i32, b: i32) -> i32 {
## Types ## 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. *value* defines the interpretation of the memory holding it.
Built-in types and type-constructors are tightly integrated into the language, Built-in types and type-constructors are tightly integrated into the language,
@ -3493,7 +3483,7 @@ The primitive types are the following:
* The machine-dependent integer and floating-point types. * The machine-dependent integer and floating-point types.
[^unittype]: The "unit" value `()` is *not* a sentinel "null pointer" value for [^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 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.] message-sending or type-parametric code) as a zero-size type.]
@ -3831,18 +3821,20 @@ impl Printable for String {
`self` refers to the value of type `String` that is the receiver for a call to `self` refers to the value of type `String` that is the receiver for a call to
the method `make_string`. the method `make_string`.
# The `Copy` trait # Special traits
Rust has a special trait, `Copy`, which when implemented changes the semantics Several traits define special evaluation behavior.
of a value. Values whose type implements `Copy` are copied rather than moved
upon assignment.
# The `Sized` trait ## The `Copy` trait
`Sized` is a special trait which indicates that the size of this type is known The `Copy` trait changes the semantics of a type implementing it. Values whose
at compile-time. 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 The `Drop` trait provides a destructor, to be run whenever a value of this type
is to be destroyed. is to be destroyed.
@ -3850,10 +3842,12 @@ is to be destroyed.
# Memory model # Memory model
A Rust program's memory consists of a static set of *items* and a *heap*. 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 Immutable portions of the heap may be safely shared between threads, mutable
may not. 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 *slots*, and allocations in the heap Allocations in the stack consist of *variables*, and allocations in the heap
consist of *boxes*. consist of *boxes*.
### Memory allocation and lifetime ### Memory allocation and lifetime
@ -3872,10 +3866,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 When a stack frame is exited, its local allocations are all released, and its
references to boxes are dropped. references to boxes are dropped.
### Memory slots ### Variables
A _slot_ is a component of a stack frame, either a function parameter, a A _variable_ is a component of a stack frame, either a named function parameter,
[temporary](#lvalues,-rvalues-and-temporaries), or a local variable. an anonymous [temporary](#lvalues,-rvalues-and-temporaries), or a named local
variable.
A _local variable_ (or *stack-local* allocation) holds a value directly, 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. allocated within the stack's memory. The value is a part of the stack frame.
@ -3888,7 +3883,7 @@ Box<i32>, y: Box<i32>)` declare one mutable variable `x` and one immutable
variable `y`). variable `y`).
Methods that take either `self` or `Box<Self>` can optionally place them in a Methods that take either `self` or `Box<Self>` 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 { trait Changer {
@ -3903,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 local variables. Local variables can be used only after they have been
initialized; this is enforced by the compiler. initialized; this is enforced by the compiler.
# Runtime services, linkage and debugging # Linkage
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
The Rust compiler supports various methods to link crates together both The Rust compiler supports various methods to link crates together both
statically and dynamically. This section will explore the various methods to statically and dynamically. This section will explore the various methods to