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.
## 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.

9
src/doc/grammar.md
View file

@ -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
@ -427,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
@ -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
in meaning to declaring the item outside the statement block.
#### Slot declarations
#### Variable declarations
```antlr
let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
@ -763,7 +762,7 @@ bound := path | lifetime
### Memory ownership
### Memory slots
### Variables
### 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 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
@ -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
@ -1064,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
@ -1229,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) -> ! {
@ -1302,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:
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.
* 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:
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);
@ -2551,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
@ -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
> 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
@ -2632,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.
@ -3042,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:
@ -3456,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:
@ -3475,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,
@ -3493,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.]
@ -3831,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.
@ -3850,10 +3842,12 @@ 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 *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
@ -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
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.
@ -3888,7 +3883,7 @@ Box<i32>, y: Box<i32>)` declare one mutable variable `x` and one immutable
variable `y`).
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 {
@ -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
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