languages/rust
languages/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust synced 2024-07-20 18:05:58 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add concept-index entries to docs, plus fix a few minor nits.

Browse source
This commit is contained in:
Graydon Hoare 2010-07-03 17:29:06 -07:00
parent df0fa603d0
commit 965e5287ba
1 changed files with 248 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

260
doc/rust.texi
View file

@ -207,6 +207,7 @@ receiver side.
@sp 1
@item Predictable native code, simple runtime
@cindex DWARF
The meaning and cost of every operation within a Rust program is intended to
be easy to model for the reader. The code should not ``surprise'' the
@ -299,9 +300,10 @@ Boxed immutable values are reference-counted and have a deterministic
destruction order: top-down, immediately upon release of the last live
reference.
State values can refer to immutable values, but not vice-versa. Rust therefore
encourages the programmer to write in a style that consists primarily of
immutable types, but also permits limited, local (per-task) mutability.
State values can refer to non-state values, but not vice-versa. Rust
therefore encourages the programmer to write in a style that consists
primarily of immutable types, but also permits limited, local
(per-task) mutability.
@sp 1
@item Stack-based iterators
@ -437,7 +439,7 @@ Every storage slot in a Rust frame participates in not only a conventional
structural static type system, describing the interpretation of memory in the
slot, but also a @emph{typestate} system. The static typestates of a program
describe the set of @emph{pure, dynamic predicates} that provably hold over
some set of slots, at each point in the program's control flow graph within
some set of slots, at each point in the program's control-flow graph within
each frame. The static calculation of the typestates of a program is a
function-local dataflow problem, and handles user-defined predicates in a
similar fashion to the way the type system permits user-defined types.
@ -573,6 +575,8 @@ Additional specific influences can be seen from the following languages:
@node Ref.Lex
@section Ref.Lex
@c * Ref.Lex:: Lexical structure.
@cindex Lexical structure
@cindex Token
The lexical structure of a Rust source file or crate file is defined in terms
of Unicode character codes and character properties.
@ -621,6 +625,7 @@ token or a syntactic extension token.
@node Ref.Lex.Ident
@subsection Ref.Lex.Ident
@c * Ref.Lex.Ident:: Identifier tokens.
@cindex Identifier token
Identifiers follow the pattern of C identifiers: they begin with a
@emph{letter} or @emph{underscore}, and continue with any combination of
@ -640,6 +645,7 @@ A @dfn{decimal digit} is a character in the range U+0030-U+0039
@c * Ref.Lex.Key:: Keyword tokens.
The keywords are:
@cindex Keywords
@sp 2
@ -719,6 +725,11 @@ The keywords are:
@node Ref.Lex.Num
@subsection Ref.Lex.Num
@c * Ref.Lex.Num:: Numeric tokens.
@cindex Number token
@cindex Hex token
@cindex Decimal token
@cindex Binary token
@cindex Floating-point token
A @dfn{number literal} is either an @emph{integer literal} or a
@emph{floating-point literal}.
@ -740,7 +751,7 @@ and @emph{underscores}.
@end enumerate
@sp 1
A @dfn{floating point literal} has one of two forms:
A @dfn{floating-point literal} has one of two forms:
@enumerate
@item Two @emph{decimal literals} separated by a period
character U+002E ('.'), with an optional @emph{exponent} trailing after the
@ -765,6 +776,10 @@ A @dfn{sign character} is either U+002B or U+002D (@code{'+'} or @code{'-'}).
@node Ref.Lex.Text
@subsection Ref.Lex.Text
@c * Ref.Lex.Key:: String and character tokens.
@cindex String token
@cindex Character token
@cindex Escape sequence
@cindex Unicode
A @dfn{character literal} is a single Unicode character enclosed within two
U+0027 (single-quote) characters, with the exception of U+0027 itself, which
@ -812,6 +827,9 @@ region). @xref{Ref.Comp.Syntax}.
@subsection Ref.Lex.Sym
@c * Ref.Lex.Sym:: Special symbol tokens.
@cindex Symbol
@cindex Operator
The special symbols are:
@sp 2
@ -877,6 +895,9 @@ The special symbols are:
@node Ref.Path
@section Ref.Path
@c * Ref.Path:: References to slots and items.
@cindex Names of items or slots
@cindex Path name
@cindex Type parameters
A @dfn{path} is a ubiquitous syntactic form in Rust that deserves special
attention. A path denotes a slot or an
@ -943,12 +964,14 @@ x.y.(1 + v).z;
@section Ref.Gram
@c * Ref.Gram:: Grammar.
@emph{TODO: LL(1), it reads like C, Alef and bits of Napier; formalize here}.
@emph{TODO: mostly LL(1), it reads like C, Alef and bits of Napier;
formalize here}.
@page
@node Ref.Comp
@section Ref.Comp
@c * Ref.Comp:: Compilation and component model.
@cindex Compilation model
Rust is a @emph{compiled} language. Its semantics are divided along a
@emph{phase distinction} between compile-time and run-time. Those semantic
@ -970,6 +993,7 @@ successful produces a single crate in executable form.
@node Ref.Comp.Crate
@subsection Ref.Comp.Crate
@c * Ref.Comp.Crate:: Units of compilation and linking.
@cindex Crate
A @dfn{crate} is a unit of compilation and linking, as well as versioning,
distribution and runtime loading. Crates are defined by @emph{crate source
@ -1059,6 +1083,7 @@ mod bar @{
@node Ref.Comp.Meta
@subsection Ref.Comp.Meta
@cindex Metadata, in crates
In a crate, a @code{meta} directive associates free form key-value metadata
with the crate. This metadata can, in turn, be used in providing partial
@ -1070,6 +1095,7 @@ Alternatively, metadata can serve as a simple form of documentation.
@node Ref.Comp.Syntax
@subsection Ref.Comp.Syntax
@c * Ref.Comp.Syntax:: Syntax extension.
@cindex Syntax extension
Rust provides a notation for @dfn{syntax extension}. The notation is a marked
syntactic form that can appear as an expression, statement or item in the body
@ -1118,6 +1144,9 @@ let bool matched = re.match(pattern, s);
@node Ref.Mem
@section Ref.Mem
@c * Ref.Mem:: Semantic model of memory.
@cindex Memory model
@cindex Box
@cindex Slot
A Rust task's memory consists of a static set of @emph{items}, a set of tasks
each with its own @emph{stack}, and a @emph{heap}. Immutable portions of the
@ -1137,6 +1166,11 @@ consist of @emph{boxes}.
@node Ref.Mem.Alloc
@subsection Ref.Mem.Alloc
@c * Ref.Mem.Alloc:: Memory allocation model.
@cindex Item
@cindex Stack
@cindex Heap
@cindex Shared box
@cindex Task-local box
The @dfn{items} of a program are those functions, iterators, objects, modules
and types that have their value calculated at compile-time and stored uniquely
@ -1169,6 +1203,7 @@ execution of other tasks.
@node Ref.Mem.Own
@subsection Ref.Mem.Own
@c * Ref.Mem.Own:: Memory ownership model.
@cindex Ownership
A task @emph{owns} all the @emph{stack-local} slot allocations in its stack
and @emph{task-local} boxes accessible from its stack. A task @emph{shares}
@ -1191,6 +1226,10 @@ references to any boxes.
@node Ref.Mem.Slot
@subsection Ref.Mem.Slot
@c * Ref.Mem.Slot:: Stack memory model.
@cindex Stack
@cindex Slot
@cindex Local slot
@cindex Alias slot
A task's stack contains slots.
@ -1238,6 +1277,8 @@ fn incr(& mutable int i) @{
@node Ref.Mem.Box
@subsection Ref.Mem.Box
@c * Ref.Mem.Box:: Heap memory model.
@cindex Box
@cindex Dereference operator
A @dfn{box} is a reference to a reference-counted heap allocation holding
another value.
@ -1293,6 +1334,9 @@ fn main() @{
@node Ref.Mem.Acct
@subsection Ref.Mem.Acct
@c * Ref.Mem.Acct:: Memory accounting model.
@cindex Domain
@cindex Accounting
@cindex Memory budget
Every task belongs to a domain, and that domain tracks the amount of memory
allocated and not yet released by tasks within it. @xref{Ref.Task.Dom}. Each
@ -1315,6 +1359,8 @@ cost is transferred to the receiving domain.
@node Ref.Task
@section Ref.Task
@c * Ref.Task:: Semantic model of tasks.
@cindex Task
@cindex Process
An executing Rust program consists of a tree of tasks. A Rust @dfn{task}
consists of an entry function, a stack, a set of outgoing communication
@ -1339,6 +1385,14 @@ operating-system processes.
@subsection Ref.Task.Comm
@c * Ref.Task.Comm:: Inter-task communication.
@cindex Communication
@cindex Port
@cindex Channel
@cindex Message passing
@cindex Send statement
@cindex Receive statement
@cindex Flush statement
With the exception of @emph{unsafe} constructs, Rust tasks are isolated from
interfering with one another's memory directly. Instead of manipulating shared
storage, Rust tasks communicate with one another using a typed, asynchronous,
@ -1393,6 +1447,15 @@ operator is @code{<-}. @xref{Ref.Stmt.Recv}.
@subsection Ref.Task.Life
@c * Ref.Task.Life:: Task lifecycle and state transitions.
@cindex Lifecycle of task
@cindex Scheduling
@cindex Running, task state
@cindex Blocked, task state
@cindex Failing, task state
@cindex Dead, task state
@cindex Soft failure
@cindex Hard failure
The @dfn{lifecycle} of a task consists of a finite set of states and events
that cause transitions between the states. The lifecycle states of a task are:
@ -1442,6 +1505,10 @@ reclamation when the last reference to it drops.
@subsection Ref.Task.Dom
@c * Ref.Task.Dom:: Task domains
@cindex Domain
@cindex Process
@cindex Thread
Every task belongs to a domain. A @dfn{domain} is a structure that owns tasks,
schedules tasks, tracks memory allocation within tasks and manages access to
runtime services on behalf of tasks.
@ -1463,6 +1530,10 @@ domain.
@subsection Ref.Task.Sched
@c * Ref.Task.Sched:: Task scheduling model.
@cindex Scheduling
@cindex Preemption
@cindex Yielding control
Every task is @emph{scheduled} within its domain. @xref{Ref.Task.Dom}. The
currently scheduled task is given a finite @emph{time slice} in which to
execute, after which it is @emph{descheduled} at a loop-edge or similar
@ -1478,6 +1549,10 @@ deschedules the task.
@section Ref.Item
@c * Ref.Item:: The components of a module.
@cindex Item
@cindex Type parameters
@cindex Module item
An @dfn{item} is a component of a module. Items are entirely determined at
compile-time, remain constant during execution, and may reside in read-only
memory.
@ -1516,6 +1591,11 @@ are no general parametric types.
@subsection Ref.Item.Mod
@c * Ref.Item.Mod:: Items defining sub-modules.
@cindex Module item
@cindex Importing names
@cindex Exporting names
@cindex Visibility control
A @dfn{module item} contains declarations of other @emph{items}. The items
within a module may be functions, modules, objects or types. These
declarations have both static and dynamic interpretation. The purpose of a
@ -1553,6 +1633,9 @@ and outside of it.
@subsubsection Ref.Item.Mod.Import
@c * Ref.Item.Mod.Import:: Declarations for module-local synonyms.
@cindex Importing names
@cindex Visibility control
An @dfn{import declaration} creates one or more local name bindings synonymous
with some other name. Usually an import declaration is used to shorten the
path required to refer to a module item.
@ -1575,6 +1658,9 @@ fn main() @{
@subsubsection Ref.Item.Mod.Export
@c * Ref.Item.Mod.Import:: Declarations for restricting visibility.
@cindex Exporting names
@cindex Visibility control
An @dfn{export declaration} restricts the set of local declarations within a
module that can be accessed from code outside the module. By default, all
local declarations in a module are exported. If a module contains an export
@ -1606,6 +1692,11 @@ fn main() @{
@node Ref.Item.Fn
@subsection Ref.Item.Fn
@c * Ref.Item.Fn:: Items defining functions.
@cindex Functions
@cindex Slots, function input and output
@cindex Effect of a function
@cindex Predicate
A @dfn{function item} defines a sequence of statements associated with a name
and a set of parameters. Functions are declared with the keyword
@ -1642,6 +1733,11 @@ fn add(int x, int y) -> int @{
@subsection Ref.Item.Iter
@c * Ref.Item.Iter:: Items defining iterators.
@cindex Iterators
@cindex Put statement
@cindex Put each statement
@cindex Foreach statement
Iterators are function-like items that can @code{put} multiple values during
their execution before returning or tail-calling.
@ -1679,6 +1775,8 @@ for each (int x = range(0,100)) @{
@node Ref.Item.Obj
@subsection Ref.Item.Obj
@c * Ref.Item.Obj:: Items defining objects.
@cindex Objects
@cindex Object constructors
An @dfn{object item} defines the @emph{state} and @emph{methods} of a set of
@emph{object values}. Object values have object types. @xref{Ref.Type.Obj}.
@ -1710,6 +1808,7 @@ check (c.get() == 3);
@node Ref.Item.Type
@subsection Ref.Item.Type
@c * Ref.Item.Type:: Items defining the types of values and slots.
@cindex Types
A @dfn{type} defines an @emph{interpretation} of a value in
memory. @xref{Ref.Type}. Types are declared with the keyword @code{type}. A
@ -1738,6 +1837,7 @@ restricted form of @code{tag} type. @xref{Ref.Type.Tag}.
@page
@node Ref.Type
@section Ref.Type
@cindex Types
Every slot and value in a Rust program has a type. The @dfn{type} of a
@emph{value} defines the interpretation of the memory holding it. The type of
@ -1773,6 +1873,10 @@ Rust; they cannot be used as user-defined identifiers in any context.
@node Ref.Type.Any
@subsection Ref.Type.Any
@cindex Any type
@cindex Dynamic type, see @i{Any type}
@cindex Reflection
@cindex Alt type statement
The type @code{any} is the union of all possible Rust types. A value of type
@code{any} is represented in memory as a pair consisting of a boxed value of
@ -1784,6 +1888,10 @@ type extraction. @xref{Ref.Stmt.Alt}.
@node Ref.Type.Mach
@subsection Ref.Type.Mach
@cindex Machine types
@cindex Floating-point types
@cindex Integer types
@cindex Word types
The machine types are the following:
@ -1825,12 +1933,15 @@ The signed two's complement word types @code{i8}, @code{i16}, @code{i32} and
@end ifhtml
respectively.
@item
The IEEE 754 single-precision and double-precision floating point types:
The IEEE 754 single-precision and double-precision floating-point types:
@code{f32} and @code{f64}, respectively.
@end itemize
@node Ref.Type.Int
@subsection Ref.Type.Int
@cindex Machine-dependent types
@cindex Integer types
@cindex Word types
The Rust type @code{uint}@footnote{A Rust @code{uint} is analogous to a C99
@ -1845,6 +1956,8 @@ rust type @code{uint} on the same target machine.
@node Ref.Type.Float
@subsection Ref.Type.Float
@cindex Machine-dependent types
@cindex Floating-point types
The Rust type @code{float} is a machine-specific type equal to one of the
supported Rust floating-point machine types (@code{f32} or @code{f64}). It is
@ -1853,13 +1966,18 @@ target machine, or if the target machine has no floating-point hardware
support, the largest floating-point type supported by the software
floating-point library used to support the other floating-point machine types.
Note that due to the preference for hardware-supported floating point, the
Note that due to the preference for hardware-supported floating-point, the
type @code{float} may not be equal to the largest @emph{supported}
floating-point type.
@node Ref.Type.Prim
@subsection Ref.Type.Prim
@cindex Primitive types
@cindex Integer types
@cindex Floating-point types
@cindex Character type
@cindex Boolean type
The primitive types are the following:
@ -1882,6 +2000,8 @@ The machine-dependent integer and floating-point types.
@node Ref.Type.Big
@subsection Ref.Type.Big
@cindex Integer types
@cindex Big integer type
The Rust type @code{big}@footnote{A Rust @code{big} is analogous to a Lisp
bignum or a Python long integer.} is an arbitrary precision integer type that
@ -1895,6 +2015,12 @@ should only exhaust its range due to memory exhaustion.
@node Ref.Type.Text
@subsection Ref.Type.Text
@cindex Text types
@cindex String type
@cindex Character type
@cindex Unicode
@cindex UCS-4
@cindex UTF-8
The types @code{char} and @code{str} hold textual data.
@ -1906,6 +2032,8 @@ A value of type @code{str} is a Unicode string, represented as a vector of
@node Ref.Type.Rec
@subsection Ref.Type.Rec
@cindex Record types
@cindex Structure types, see @i{Record types}
The record type-constructor @code{rec} forms a new heterogeneous product of
values.@footnote{The @code{rec} type-constructor is analogous to the
@ -1923,6 +2051,7 @@ let int px = p.x;
@node Ref.Type.Tup
@subsection Ref.Type.Tup
@cindex Tuple types
The tuple type-constructor @code{tup} forms a new heterogeneous product of
values exactly as the @code{rec} type-constructor does, with the difference
@ -1943,6 +2072,8 @@ check (p._1 == "world");
@node Ref.Type.Vec
@subsection Ref.Type.Vec
@cindex Vector types
@cindex Array types, see @i{Vector types}
The vector type-constructor @code{vec} represents a homogeneous array of
values of a given type. A vector has a fixed size. If the member-type of a
@ -1981,6 +2112,8 @@ vector is always bounds-checked.
@node Ref.Type.Tag
@subsection Ref.Type.Tag
@cindex Tag types
@cindex Union types, see @i{Tag types}
The @code{tag} type-constructor forms new heterogeneous disjoint union
types.@footnote{The @code{tag} type is analogous to a @code{data} constructor
@ -2019,6 +2152,7 @@ let list[int] a = cons(7, cons(13, nil));
@node Ref.Type.Fn
@subsection Ref.Type.Fn
@cindex Function types
The function type-constructor @code{fn} forms new function types. A function
type consists of a sequence of input slots, an optional set of input
@ -2040,6 +2174,7 @@ x = bo(5,7);
@node Ref.Type.Iter
@subsection Ref.Type.Iter
@cindex Iterator types
The iterator type-constructor @code{iter} forms new iterator types. An
iterator type consists a sequence of input slots, an optional set of input
@ -2062,6 +2197,8 @@ for each (int i = range(5,7)) @{
@node Ref.Type.Port
@subsection Ref.Type.Port
@cindex Port types
@cindex Communication
The port type-constructor @code{port} forms types that describe ports. A port
is the @emph{receiving end} of a typed, asynchronous, simplex inter-task
@ -2083,6 +2220,8 @@ v <- p;
@node Ref.Type.Chan
@subsection Ref.Type.Chan
@cindex Channel types
@cindex Communication
The channel type-constructor @code{chan} forms types that describe channels. A
channel is the @emph{sending end} of a typed, asynchronous, simplex inter-task
@ -2117,6 +2256,7 @@ c <| v;
@node Ref.Type.Task
@subsection Ref.Type.Task
@cindex Task type
The task type @code{task} describes values that are @emph{live
tasks}.
@ -2138,6 +2278,7 @@ holding those references), the released task immediately fails.
@node Ref.Type.Obj
@subsection Ref.Type.Obj
@c * Ref.Type.Obj:: Object types.
@cindex Object types
A @dfn{object type} describes values of abstract type, that carry some hidden
@emph{fields} and are accessed through a set of un-ordered
@ -2203,6 +2344,7 @@ give_ints(t2);
@node Ref.Type.Constr
@subsection Ref.Type.Constr
@c * Ref.Type.Constr:: Constrained types.
@cindex Constrained types
A @dfn{constrained type} is a type that carries a @emph{formal constraint}
(@pxref{Ref.Stmt.Stat.Constr}), which is similar to a normal constraint except
@ -2228,6 +2370,7 @@ let ordered_range rng2 = rec(low=15, high=17);
@node Ref.Type.Type
@subsection Ref.Type.Type
@c * Ref.Type.Type:: Types describing types.
@cindex Type type
@emph{TODO}.
@ -2235,6 +2378,7 @@ let ordered_range rng2 = rec(low=15, high=17);
@node Ref.Expr
@section Ref.Expr
@c * Ref.Expr:: Parsed and primitive expressions.
@cindex Expressions
Rust has two kinds of expressions: @emph{parsed expressions} and
@emph{primitive expressions}. The former are syntactic sugar and are
@ -2252,6 +2396,7 @@ right hand side of copy statements, @xref{Ref.Stmt.Copy}.
@node Ref.Stmt
@section Ref.Stmt
@c * Ref.Stmt:: Executable statements.
@cindex Statements
A @dfn{statement} is a component of a block, which is in turn a components of
an outer block, a function or an iterator. When a function is spawned into a
@ -2290,6 +2435,7 @@ actions.
@node Ref.Stmt.Stat
@subsection Ref.Stmt.Stat
@c * Ref.Stmt.Stat:: The static typestate system of statement analysis.
@cindex Typestate system
Statements have a detailed static semantics. The static semantics determine,
on a statement-by-statement basis, the @emph{effects} the statement has on its
@ -2303,7 +2449,7 @@ system.
@menu
* Ref.Stmt.Stat.Point:: Inter-statement positions of logical judgements.
* Ref.Stmt.Stat.CFG:: The control flow graph formed by statements.
* Ref.Stmt.Stat.CFG:: The control-flow graph formed by statements.
* Ref.Stmt.Stat.Constr:: Predicates applied to slots.
* Ref.Stmt.Stat.Cond:: Constraints required and implied by a statement.
* Ref.Stmt.Stat.Typestate:: Constraints that hold at points.
@ -2313,6 +2459,7 @@ system.
@node Ref.Stmt.Stat.Point
@subsubsection Ref.Stmt.Stat.Point
@c * Ref.Stmt.Stat.Point:: Inter-statement positions of logical judgements.
@cindex Points
A @dfn{point} exists before and after any statement in a Rust program.
For example, this code:
@ -2343,7 +2490,8 @@ memory.
@node Ref.Stmt.Stat.CFG
@subsubsection Ref.Stmt.Stat.CFG
@c * Ref.Stmt.Stat.CFG:: The control flow graph formed by statements.
@c * Ref.Stmt.Stat.CFG:: The control-flow graph formed by statements.
@cindex Control-flow graph
Each @emph{point} can be considered a vertex in a directed @emph{graph}. Each
kind of statement implies a single edge in this graph between the point before
@ -2352,11 +2500,13 @@ from the points of the statement to points before other statements. The edges
between points represent @emph{possible} indivisible control transfers that
might occur during execution.
This implicit graph is called the @dfn{control flow graph}, or @dfn{CFG}.
This implicit graph is called the @dfn{control-flow graph}, or @dfn{CFG}.
@node Ref.Stmt.Stat.Constr
@subsubsection Ref.Stmt.Stat.Constr
@c * Ref.Stmt.Stat.Constr:: Predicates applied to slots.
@cindex Predicate
@cindex Constraint
A @dfn{predicate} is any pure boolean function. @xref{Ref.Item.Fn}.
@ -2387,6 +2537,9 @@ in those slots must be immutable.
@node Ref.Stmt.Stat.Cond
@subsubsection Ref.Stmt.Stat.Cond
@c * Ref.Stmt.Stat.Cond:: Constraints required and implied by a statement.
@cindex Condition
@cindex Precondition
@cindex Postcondition
A @dfn{condition} is a set of zero or more constraints.
@ -2405,6 +2558,9 @@ postcondition is considered to be @emph{dropped} by the statement.
@node Ref.Stmt.Stat.Typestate
@subsubsection Ref.Stmt.Stat.Typestate
@c * Ref.Stmt.Stat.Typestate:: Constraints that hold at points.
@cindex Typestate
@cindex Prestate
@cindex Poststate
The typestate checking system @emph{calculates} an additional
condition for each point called its typestate. For a given statement,
@ -2453,6 +2609,8 @@ static (compile-time) error.
@node Ref.Stmt.Stat.Check
@subsubsection Ref.Stmt.Stat.Check
@c * Ref.Stmt.Stat.Check:: Relating dynamic state to static typestate.
@cindex Check statement
@cindex Assertions, see @i{Check statement}
The key mechanism that connects run-time semantics and compile-time analysis
of typestates is the use of @code{check} statements. @xref{Ref.Stmt.Check}. A
@ -2484,6 +2642,7 @@ to hold in order to execute properly.
@node Ref.Stmt.Decl
@subsection Ref.Stmt.Decl
@c * Ref.Stmt.Decl:: Statement declaring an item or slot.
@cindex Declaration statement
A @dfn{declaration statement} is one that introduces a @emph{name} into the
enclosing statement block. The declared name may denote a new slot or a new
@ -2512,6 +2671,10 @@ declaring a function-local item.
@node Ref.Stmt.Decl.Slot
@subsubsection Ref.Stmt.Decl.Slot
@c * Ref.Stmt.Decl.Slot:: Statement declaring an slot.
@cindex Local slot
@cindex Variable, see @i{Local slot}
@cindex Type inference
@cindex Automatic slot
A @code{slot declaration statement} has one one of two forms:
@ -2540,6 +2703,8 @@ object signatures must always declared types for all argument slots.
@node Ref.Stmt.Copy
@subsection Ref.Stmt.Copy
@c * Ref.Stmt.Copy:: Statement for copying a value.
@cindex Copy statement
@cindex Assignment operator, see @i{Copy statement}
A @dfn{copy statement} consists of an @emph{lval} followed by an equals-sign
(@code{=}) and a primitive expression. @xref{Ref.Expr}.
@ -2564,6 +2729,7 @@ x.y = z + 2;
@node Ref.Stmt.Spawn
@subsection Ref.Stmt.Spawn
@c * Ref.Stmt.Spawn:: Statements creating new tasks.
@cindex Spawn statement
A @code{spawn} statement consists of keyword @code{spawn}, followed by a
normal @emph{call} statement (@pxref{Ref.Stmt.Call}). A @code{spawn}
@ -2594,6 +2760,8 @@ auto result <- out;
@node Ref.Stmt.Send
@subsection Ref.Stmt.Send
@c * Ref.Stmt.Send:: Statements for sending a value into a channel.
@cindex Send statement
@cindex Communication
Sending a value through a channel can be done via two different statements.
Both statements take an @emph{lval}, denoting a channel, and a value to send
@ -2624,6 +2792,8 @@ c <| "hello, world";
@node Ref.Stmt.Flush
@subsection Ref.Stmt.Flush
@c * Ref.Stmt.Flush:: Statement for flushing a channel queue.
@cindex Flush statement
@cindex Communication
A @code{flush} statement takes a channel and blocks the flushing task until
the channel's queue has emptied. It can be used to implement a more precise
@ -2640,6 +2810,8 @@ flush c;
@node Ref.Stmt.Recv
@subsection Ref.Stmt.Recv
@c * Ref.Stmt.Recv:: Statement for receiving a value from a channel.
@cindex Receive statement
@cindex Communication
The @dfn{receive statement} takes an @var{lval} to receive into and an
expression denoting a port, and applies the @emph{receive operator}
@ -2659,6 +2831,8 @@ let str s <- p;
@node Ref.Stmt.Call
@subsection Ref.Stmt.Call
@c * Ref.Stmt.Call:: Statement for calling a function.
@cindex Call statement
@cindex Function calls
A @dfn{call statement} invokes a function, providing a tuple of input slots
and an alias slot to serve as the function's output, bound to the @var{lval}
@ -2677,6 +2851,9 @@ let int x = add(1, 2);
@node Ref.Stmt.Bind
@subsection Ref.Stmt.Bind
@c * Ref.Stmt.Bind:: Statement for binding arguments to functions.
@cindex Bind statement
@cindex Closures
@cindex Currying
A @dfn{bind statement} constructs a new function from an existing
function.@footnote{The @code{bind} statement is analogous to the @code{bind}
@ -2722,6 +2899,7 @@ of them can be achieved with @code{bind} statements.
@node Ref.Stmt.Ret
@subsection Ref.Stmt.Ret
@c * Ref.Stmt.Ret:: Statement for stopping and producing a value.
@cindex Return statement
Executing a @code{ret} statement@footnote{A @code{ret} statement is analogous
to a @code{return} statement in the C family.} copies a value into the output
@ -2741,6 +2919,8 @@ fn max(int a, int b) -> int @{
@node Ref.Stmt.Be
@subsection Ref.Stmt.Be
@c * Ref.Stmt.Be:: Statement for stopping and executing a tail call.
@cindex Be statement
@cindex Tail calls
Executing a @code{be} statement @footnote{A @code{be} statement in is
analogous to a @code{become} statement in Newsqueak or Alef.} destroys the
@ -2770,6 +2950,8 @@ copy of itself.
@node Ref.Stmt.Put
@subsection Ref.Stmt.Put
@c * Ref.Stmt.Put:: Statement for pausing and producing a value.
@cindex Put statement
@cindex Iterators
Executing a @code{put} statement copies a value into the output slot of the
current iterator, suspends execution of the current iterator, and transfers
@ -2789,6 +2971,9 @@ execution and destroying the iterator frame.
@node Ref.Stmt.Fail
@subsection Ref.Stmt.Fail
@c * Ref.Stmt.Fail:: Statement for causing task failure.
@cindex Fail statement
@cindex Failure
@cindex Unwinding
Executing a @code{fail} statement causes a task to enter the @emph{failing}
state. In the @emph{failing} state, a task unwinds its stack, destroying all
@ -2798,6 +2983,8 @@ point it halts execution in the @emph{dead} state.
@node Ref.Stmt.Log
@subsection Ref.Stmt.Log
@c * Ref.Stmt.Log:: Statement for logging values to diagnostic buffers.
@cindex Log statement
@cindex Logging
Executing a @code{log} statement may, depending on runtime configuration,
cause a value to be appended to an internal diagnostic logging buffer provided
@ -2815,6 +3002,10 @@ contains a log statement.
@node Ref.Stmt.Note
@subsection Ref.Stmt.Note
@c * Ref.Stmt.Note:: Statement for logging values during failure.
@cindex Note statement
@cindex Logging
@cindex Unwinding
@cindex Failure
A @code{note} statement has no effect during normal execution. The purpose of
a @code{note} statement is to provide additional diagnostic information to the
@ -2858,6 +3049,9 @@ logged during unwinding, @emph{not} the original value that was denoted by the
@node Ref.Stmt.While
@subsection Ref.Stmt.While
@c * Ref.Stmt.While:: Statement for simple conditional looping.
@cindex While statement
@cindex Loops
@cindex Control-flow
A @code{while} statement is a loop construct. A @code{while} loop may be
either a simple @code{while} or a @code{do}-@code{while} loop.
@ -2892,6 +3086,9 @@ do @{
@node Ref.Stmt.Break
@subsection Ref.Stmt.Break
@c * Ref.Stmt.Break:: Statement for terminating a loop.
@cindex Break statement
@cindex Loops
@cindex Control-flow
Executing a @code{break} statement immediately terminates the innermost loop
enclosing it. It is only permitted in the body of a loop.
@ -2899,6 +3096,9 @@ enclosing it. It is only permitted in the body of a loop.
@node Ref.Stmt.Cont
@subsection Ref.Stmt.Cont
@c * Ref.Stmt.Cont:: Statement for terminating a single loop iteration.
@cindex Continue statement
@cindex Loops
@cindex Control-flow
Executing a @code{cont} statement immediately terminates the current iteration
of the innermost loop enclosing it, returning control to the loop
@ -2913,6 +3113,9 @@ A @code{cont} statement is only permitted in the body of a loop.
@node Ref.Stmt.For
@subsection Ref.Stmt.For
@c * Ref.Stmt.For:: Statement for looping over strings and vectors.
@cindex For statement
@cindex Loops
@cindex Control-flow
A @dfn{for loop} is controlled by a vector or string. The for loop
bounds-checks the underlying sequence @emph{once} when initiating the loop,
@ -2945,6 +3148,9 @@ for (&foo e in v) @{
@node Ref.Stmt.Foreach
@subsection Ref.Stmt.Foreach
@c * Ref.Stmt.Foreach:: Statement for general conditional looping.
@cindex Foreach statement
@cindex Loops
@cindex Control-flow
An @dfn{foreach loop} is denoted by the @code{for each} keywords, and is
controlled by an iterator. The loop executes once for each value @code{put} by
@ -2963,6 +3169,8 @@ for each (&str s = _str.split(txt, "\n")) @{
@node Ref.Stmt.If
@subsection Ref.Stmt.If
@c * Ref.Stmt.If:: Statement for simple conditional branching.
@cindex If statement
@cindex Control-flow
An @code{if} statement is a conditional branch in program control. The form of
an @code{if} statement is a parenthesized condition expression, followed by a
@ -2975,6 +3183,9 @@ block is skipped and any @code{else} block is executed.
@node Ref.Stmt.Alt
@subsection Ref.Stmt.Alt
@c * Ref.Stmt.Alt:: Statement for complex conditional branching.
@cindex Alt statement
@cindex Control-flow
@cindex Switch statement, see @i{Alt statement}
An @code{alt} statement is a multi-directional branch in program control.
There are three kinds of @code{alt} statement: communication @code{alt}
@ -2997,6 +3208,10 @@ statement following the @code{alt} when the case block completes.
@node Ref.Stmt.Alt.Comm
@subsubsection Ref.Stmt.Alt.Comm
@c * Ref.Stmt.Alt.Comm:: Statement for branching on communication events.
@cindex Communication alt statement
@cindex Control-flow
@cindex Communication
@cindex Multiplexing
The simplest form of @code{alt} statement is the a @emph{communication}
@code{alt}. The cases of a communication @code{alt}'s arms are send, receive
@ -3030,6 +3245,8 @@ alt @{
@node Ref.Stmt.Alt.Pat
@subsubsection Ref.Stmt.Alt.Pat
@c * Ref.Stmt.Alt.Pat:: Statement for branching on pattern matches.
@cindex Pattern alt statement
@cindex Control-flow
A pattern @code{alt} statement branches on a @emph{pattern}. The exact form of
matching that occurs depends on the pattern. Patterns consist of some
@ -3069,6 +3286,8 @@ alt (x) @{
@node Ref.Stmt.Alt.Type
@subsubsection Ref.Stmt.Alt.Type
@c * Ref.Stmt.Alt.Type:: Statement for branching on type.
@cindex Type alt statement
@cindex Control-flow
An @code{alt type} statement is similar to a pattern @code{alt}, but branches
on the @emph{type} of its head expression, rather than the value. The head
@ -3102,6 +3321,8 @@ alt type (x) @{
@node Ref.Stmt.Prove
@subsection Ref.Stmt.Prove
@c * Ref.Stmt.Prove:: Statement for static assertion of typestate.
@cindex Prove statement
@cindex Typestate system
A @code{prove} statement has no run-time effect. Its purpose is to statically
check (and document) that its argument constraint holds at its statement entry
@ -3111,6 +3332,8 @@ the program containing it will fail to compile.
@node Ref.Stmt.Check
@subsection Ref.Stmt.Check
@c * Ref.Stmt.Check:: Statement for dynamic assertion of typestate.
@cindex Check statement
@cindex Typestate system
A @code{check} statement connects dynamic assertions made at run-time to the
static typestate system. A @code{check} statement takes a constraint to check
@ -3152,10 +3375,13 @@ fn test() @{
@node Ref.Stmt.IfCheck
@subsection Ref.Stmt.IfCheck
@c * Ref.Stmt.IfCheck:: Statement for dynamic testing of typestate.
@cindex If check statement
@cindex Typestate system
@cindex Control-flow
An @code{if check} statement combines a @code{if} statement and a @code{check}
statement in an indivisible unit that can be used to build more complex
conditional control flow than the @code{check} statement affords.
conditional control-flow than the @code{check} statement affords.
In fact, @code{if check} is a ``more primitive'' statement @code{check};
instances of the latter can be rewritten as instances of the former. The
@ -3182,6 +3408,7 @@ if check even(x) @{
@node Ref.Run
@section Ref.Run
@c * Ref.Run:: Organization of runtime services.
@cindex Runtime library
The Rust @dfn{runtime} is a relatively compact collection of C and Rust code
that provides fundamental services and datatypes to all Rust tasks at
@ -3201,6 +3428,7 @@ communication, reflection, logging and signal handling.
@node Ref.Run.Mem
@subsection Ref.Run.Mem
@c * Ref.Run.Mem:: Runtime memory management service.
@cindex Memory allocation
The runtime memory-management system is based on a @emph{service-provider
interface}, through which the runtime requests blocks of memory from its
@ -3215,6 +3443,7 @@ allocating and freeing boxed values.
@node Ref.Run.Type
@subsection Ref.Run.Type
@c * Ref.Run.Mem:: Runtime built-in type services.
@cindex Built-in types
The runtime provides C and Rust code to manage several built-in types:
@itemize
@ -3231,6 +3460,9 @@ records, and tags is open-coded by the Rust compiler.
@node Ref.Run.Comm
@subsection Ref.Run.Comm
@c * Ref.Run.Comm:: Runtime communication service.
@cindex Communication
@cindex Process
@cindex Thread
The runtime provides code to manage inter-task communication. This includes
the system of task-lifecycle state transitions depending on the contents of
@ -3241,6 +3473,8 @@ communication facilities.
@node Ref.Run.Refl
@subsection Ref.Run.Refl
@c * Ref.Run.Refl:: Runtime reflection system.
@cindex Reflection
@cindex DWARF
The runtime reflection system is driven by the DWARF tables emitted into a
crate at compile-time. Reflecting on a slot or item allocates a Rust data
@ -3249,6 +3483,7 @@ structure corresponding to the DWARF DIE for that slot or item.
@node Ref.Run.Log
@subsection Ref.Run.Log
@c * Ref.Run.Log:: Runtime logging system.
@cindex Logging
The runtime contains a system for directing logging statements to a logging
console and/or internal logging buffers. @xref{Ref.Stmt.Log}. Logging
@ -3279,6 +3514,7 @@ need to filter logs based on these two built-in dimensions.
@node Ref.Run.Sig
@subsection Ref.Run.Sig
@c * Ref.Run.Sig:: Runtime signal handler.
@cindex Signals
The runtime signal-handling system is driven by a signal-dispatch table and a
signal queue associated with each task. Sending a signal to a task inserts the