diff options
Diffstat (limited to 'src/doc/reference.md')
| -rw-r--r-- | src/doc/reference.md | 138 |
1 files changed, 48 insertions, 90 deletions
diff --git a/src/doc/reference.md b/src/doc/reference.md index 57110df0f9e..c159f6164c2 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 @@ -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 + +Several traits define special evaluation behavior. -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. +## The `Copy` trait -# The `Sized` trait +The `Copy` trait changes the semantics of a type implementing it. Values whose +type implements `Copy` are copied rather than moved upon assignment. -`Sized` is a special trait which indicates that the size of this type is known -at compile-time. +## The `Sized` trait -# The `Drop` 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 |