diff options
Diffstat (limited to 'doc/rust.texi')
| -rw-r--r-- | doc/rust.texi | 150 |
1 files changed, 78 insertions, 72 deletions
diff --git a/doc/rust.texi b/doc/rust.texi index 1576f4f8..5fc1a8b7 100644 --- a/doc/rust.texi +++ b/doc/rust.texi @@ -250,9 +250,7 @@ Many values in Rust are allocated @emph{within} their containing stack-frame or parent structure. Numbers, records, tuples and tags are all allocated this way. To allocate such values in the heap, they must be explicitly @emph{boxed}. A @dfn{box} is a pointer to a heap allocation that holds another -value, its @emph{content}. If the content of a box is a @emph{state} value -- -the sort that may contain mutable members -- then the heap allocation is also -subject to garbage collection. +value, its @emph{content}. Boxing and unboxing in Rust is explicit, though in many cases (arithmetic operations, name-component dereferencing) Rust will automatically ``reach @@ -275,35 +273,42 @@ still guaranteeing that every use of a slot occurs after it has been initialized. @sp 1 -@item Static control over mutability. +@item Static control over mutability and garbage collection. -Types in Rust are classified as either immutable or mutable. By default, -all types are immutable. +Types in Rust are classified into @emph{layers}. There is a layer of immutable +values, a layer of state values, and a layer of GC values. By default, all +types are immutable. -If a type is declared as @code{mutable}, then the type is a @code{state} type -and must be declared as such. Any type directly marked as @code{mutable} -@emph{or indirectly containing} a state type is also a state type. +If a field within a type is declared as @code{mutable}, then the type is part +of the @code{state} layer and must be declared as such. Any type directly +marked as @code{state} @emph{or indirectly referring to} a state type is also +a state type. -This classification of data types in Rust interacts with the memory allocation -and transmission rules. In particular: +If a field within a type is potentially cyclic (this is a narrow, but +well-defined condition involving mutable recursive types) then it is part of +the @code{gc} layer and must be declared as such. + +This classification of data types in Rust interacts with the memory allocation, +transmission and destruction rules. In particular: @itemize -@item Only immutable (non-state) values can be sent over channels. -@item Only immutable (non-state) objects can have destructor functions. +@item Only immutable values can be sent over channels. +@item Only non-GC objects can have destructor functions. @end itemize -Boxed state values are subject to local (per-task) garbage-collection. Garbage -collection costs are therefore also task-local and do not interrupt or suspend -other tasks. +Garbage collection, when present, operates per-task and does not interrupt +other tasks while running. It is limited to types that need it and can be +statically avoided altogether by limiting the types in a program to the state +and immutable layers. -Boxed immutable values are reference-counted and have a deterministic -destruction order: top-down, immediately upon release of the last live -reference. +Non-GC 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 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. +State values can refer to non-state values, but not vice-versa; likewise GC +values can refer to non-GC 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, +and provides local (per-task) GC only when required. @sp 1 @item Stack-based iterators @@ -360,8 +365,7 @@ Rust has a lightweight object system based on structural object types: there is no ``class hierarchy'' nor any concept of inheritance. Method overriding and object restriction are performed explicitly on object values, which are little more than order-insensitive records of methods sharing a common private -value. Objects can be state or non-state, and only non-state objects can have -destructors. +value. Objects that reside outside the GC layer can have destructors. @sp 1 @item Dynamic type @@ -407,29 +411,29 @@ organizing tasks into mutually-supervising or mutually-failing groups. @sp 1 @item Deterministic destruction -Immutable objects can have destructor functions, which are executed +Non-GC objects can have destructor functions, which are executed deterministically in top-down ownership order, as control frames are exited and/or objects are otherwise freed from data structures holding them. The same destructors are run in the same order whether the object is deleted by unwinding during failure or normal execution. -Similarly, the rules for freeing immutable values are deterministic and +Similarly, the rules for freeing non-GC values are deterministic and predictable: on scope-exit or structure-release, local slots are released immediately. Referenced boxes have their reference count decreased and are released if the count drops to zero. Aliases are silently forgotten. -State values are local to a task, and are subject to per-task garbage -collection. As a result, unreferenced state boxes are not necessarily freed -immediately; if an unreferenced state box is part of an acyclic graph, it is +GC values are local to a task, and are subject to per-task garbage +collection. As a result, unreferenced GC-layer boxes are not necessarily freed +immediately; if an unreferenced GC box is part of an acyclic graph, it is freed when the last reference to it drops, but if it is part of a reference cycle it will be freed when the GC collects it (or when the owning task terminates, at the latest). -State values can point to immutable values but not vice-versa. Doing so merely +GC values can point to non-GC values but not vice-versa. Doing so merely delays (to an undefined future time) the moment when the deterministic, -top-down destruction sequence for the referenced immutable values -@emph{start}. In other words, the immutable ``leaves'' of a state value are -released in a locally-predictable order, even if the ``interior'' of the state +top-down destruction sequence for the referenced non-GC values +@emph{start}. In other words, the non-GC ``leaves'' of a GC value are released +in a locally-predictable order, even if the ``interior'' cyclic part of the GC value is released in an unpredictable order. @sp 1 @@ -1265,15 +1269,16 @@ entry to each function as the task executes. A stack allocation is reclaimed when control leaves the frame containing it. The @dfn{heap} is a general term that describes two separate sets of boxes: -@emph{task-local} state boxes and the @emph{shared} non-state boxes. +@emph{task-local} state and GC boxes, and the @emph{shared} immutable boxes. -State boxes are @dfn{task-local}, owned by the task. Like any other state -value, they cannot pass over channels. State boxes do not outlive the task -that owns them. When unreferenced, they are collected using a general +State and GC boxes are @dfn{task-local}, owned by the task. Like any other +state or GC value, they cannot pass over channels. State and GC boxes do not +outlive the task that owns them. When unreferenced, they are either +immediately destructed (if acyclic) or else collected using a general (cycle-aware) garbage-collector local to each task. Garbage collection within a local heap does not interrupt execution of other tasks. -Non-state boxes are @dfn{shared}, and can be multiply-referenced by many +Immutable boxes are @dfn{shared}, and can be multiply-referenced by many different tasks. Like any other immutable type, they can pass over channels, and live as long as the last task referencing them within a given domain. When unreferenced, they are destroyed immediately (due to reference-counting) and @@ -1794,9 +1799,9 @@ statement. If a control path lacks a @code{ret} statement in source code, an implicit @code{ret} statement is appended to the end of the control path during compilation, returning the implicit @code{()} value. -A function may have an @emph{effect}, which may be either @code{io}, -@code{state}, @code{unsafe}. If no effect is specified, the function is said -to be @dfn{pure}. +A function may have an @emph{effect}, which may be either @code{impure} or +@code{unsafe}. If no effect is specified, the function is said to be +@dfn{pure}. Any pure boolean function is also called a @emph{predicate}, and may be used as part of the static typestate system. @xref{Ref.Stmt.Stat.Constr}. @@ -1933,23 +1938,23 @@ variables to initial values. @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 -type's interpretation is used for the values held in any slot with that -type. @xref{Ref.Mem.Slot}. The interpretation of a value includes: +A @dfn{type} defines a set of possible values in +memory. @xref{Ref.Type}. Types are declared with the keyword +@code{type}. Every value has a single, specific type; the type-specified +aspects of a value include: @itemize @item Whether the value is composed of sub-values or is indivisible. @item Whether the value represents textual or numerical information. @item Whether the value represents integral or floating-point information. @item The sequence of memory operations required to access the value. -@item Whether the value is mutable or immutable. +@item The storage layer the value resides in (immutable, state or gc). @end itemize -For example, the type @code{rec(u8 x, u8 y)} defines the interpretation of -values that are composite records, each containing two unsigned 8-bit -integers accessed through the components @code{x} and @code{y}, and laid -out in memory with the @code{x} component preceding the @code{y} component. +For example, the type @code{rec(u8 x, u8 y)} defines the set of immutable +values that are composite records, each containing two unsigned 8-bit integers +accessed through the components @code{x} and @code{y}, and laid out in memory +with the @code{x} component preceding the @code{y} component. @node Ref.Item.Tag @subsection Ref.Item.Tag @@ -2238,9 +2243,9 @@ check (p._1 == "world"); @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 -vector is a state type, then vector is a @emph{state} type, like any type -containing another type. +values of a given type. A vector has a fixed size. The layer of a vector type +is to the layer of its member type, like any type that contains a single +member type. Vectors can be sliced. A slice expression builds a new vector by copying a contiguous range -- given by a pair of indices representing a half-open @@ -2342,10 +2347,13 @@ communication facility. @xref{Ref.Task.Comm}. A @code{port} type takes a single type parameter, denoting the type of value that can be received from a @code{port} value of that type. -Ports are modeled as mutable native types with built-in meaning to the +Ports are modeled as stateful native types, with built-in meaning to the language. They cannot be transmitted over channels or otherwise replicated, and are always local to the task that creates them. +Ports (like channels) can only be carry types of the immutable layer. No +mutable values can pass over a port or channel. + An example of a @code{port} type: @example type port[vec[str]] svp; @@ -2369,6 +2377,9 @@ Channels are immutable, and can be transmitted over channels to other tasks. They are modeled as immutable native types with built-in meaning to the language. +Channels (like ports) can only be carry types of the immutable layer. No +mutable values can pass over a port or channel. + When a task sends a message into a channel, the task forms an outgoing queue associated with that channel. The per-task queue @emph{associated} with a channel can be indirectly manipulated by the task, but is @emph{not} otherwise @@ -2379,8 +2390,8 @@ associated with the channel. Channels are also @emph{weak}: a channel is directly coupled to a particular destination port on a particular task, but does not keep that port or task @emph{alive}. A channel may therefore fail to operate at any moment. If a task -sends to a channel that is connected to a nonexistent port, it receives a -signal. +sends a message to a channel that is connected to a nonexistent port, the +message is dropped. An example of a @code{chan} type: @example @@ -2407,8 +2418,8 @@ the language. They cannot be transmitted over channels or otherwise replicated, and are always local to the task that spawns them. If all references to a task are dropped (due to the release of any structure -holding those references), the released task immediately fails. -@xref{Ref.Task.Life}. +holding those references), the runtime signals the un-referenced task, which +then fails. @xref{Ref.Task.Life}. @node Ref.Type.Obj @@ -2427,15 +2438,10 @@ declaration. Such a ``plain'' object type can be used to describe an interface that a variety of particular objects may conform to, by supporting a superset of the methods. -An object type that can contain a state must be declared as a @code{state obj} -like any other state type. And similarly a method type that performs I/O or -makes native calls must be declared @code{io} or @code{unsafe}, like any other -function. - -Moreover, @emph{all} methods of a state object are implicitly state functions -- as -they all bind the same mutable state field(s) -- so implicitly have an effect -lower than @code{io}. It is therefore unnecessary to declare methods within a -state object type (or state object item) as @code{io}. +An object type that can contain fields of a given layer must be declared as +residing in that layer (or lower), like any other type. And similarly a method +with a given effect must be declared as having that effect (or lower) in the +object type, like any other function. An example of an object type with two separate object items supporting it, and a client function using both items via the object type: @@ -2444,17 +2450,17 @@ a client function using both items via the object type: state type taker = state obj @{ - fn take(int); + impure fn take(int); @}; state obj adder(mutable int x) @{ - fn take(int y) @{ + impure fn take(int y) @{ x += y; @} @} obj sender(chan[int] c) @{ - io fn take(int z) @{ + impure fn take(int z) @{ c <| z; @} @} @@ -3113,7 +3119,7 @@ by the runtime or emitted to a system console. Log statements are enabled or disabled dynamically at run-time on a per-task and per-item basis. @xref{Ref.Run.Log}. -Executing a @code{log} statement is not considered an @code{io} effect in the +Executing a @code{log} statement is not considered an impure effect in the effect system. In other words, a pure function remains pure even if it contains a log statement. |