From 965e5287baf7666785941eb03ba41c06a7c1e2f1 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Sat, 3 Jul 2010 17:29:06 -0700 Subject: [PATCH] Add concept-index entries to docs, plus fix a few minor nits. --- doc/rust.texi | 260 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 248 insertions(+), 12 deletions(-) diff --git a/doc/rust.texi b/doc/rust.texi index 0f0a0f446f8..725ce572c78 100644 --- a/doc/rust.texi +++ b/doc/rust.texi @@ -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