Skip to content

Commit c61ed3f

Browse files
committed
Added definitions to the glossary
Specifically: - regulatory approach - memory safety (spatial and temporal) - mc/dc coverage - integer overflow - functional purity
1 parent f572fa7 commit c61ed3f

File tree

1 file changed

+57
-1
lines changed

1 file changed

+57
-1
lines changed

reference/src/glossary.md

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,21 @@ and accesses are only permitted if the address is in range of the allocation ass
112112
Data inside an allocation is stored as [abstract bytes][abstract byte];
113113
in particular, allocations do not track which type the data inside them has.
114114

115+
### Integer Overflow
116+
[integer overflow]: #integer-overflow
117+
118+
[Integer overflow](https://en.wikipedia.org/wiki/Integer_overflow) occurs when an arithmetic operation on integers attempts to create a numeric value that is outside of the range that can be represented with a given number of digits. Such out-of-range can be **either** higher than the maximum (overflow) or lower than the minimum (underflow) representable value.
119+
120+
For example, consider the following seemingly-harmless function:
121+
```rust
122+
pub const fn average(x: usize, y: usize) -> usize {
123+
(x + y) / 2
124+
}
125+
```
126+
If `x` and/or `y` are close to `usize::MAX`, the term `(x + y)` will no longer fit in a `usize`-sized integer, and the result will be incorrect.
127+
128+
Note that Rust enables runtime checking for integer overflow for `dev` builds but **not** `release` builds by default, although this [can be overridden](https://doc.rust-lang.org/cargo/reference/profiles.html#overflow-checks).
129+
115130
### Interior mutability
116131

117132
*Interior Mutation* means mutating memory where there also exists a live shared reference pointing to the same memory; or mutating memory through a pointer derived from a shared reference.
@@ -133,7 +148,7 @@ The *layout* of a type defines its size and alignment as well as the offsets of
133148

134149
Note that layout does not capture everything that there is to say about how a type is represented on the machine; it notably does not include [ABI][abi] or [Niches][niche].
135150

136-
Note: Originally, *layout* and *representation* were treated as synonyms, and Rust language features like the `#[repr]` attribute reflect this.
151+
Note: Originally, *layout* and *representation* were treated as synonyms, and Rust language features like the `#[repr]` attribute reflect this.
137152
In this document, *layout* and [*representation*][representation relation] are not synonyms.
138153

139154
### Memory Address
@@ -147,6 +162,22 @@ it's an address as understood by the CPU, it's what the load/store instructions
147162
Note that a pointer in Rust is *not* just a memory address.
148163
A pointer value consists of a memory address and [provenance][provenance].
149164

165+
### Memory Safety
166+
[memory safety]: #memory-safety
167+
168+
Memory safety can refer to **spatial** memory safety, **temporal** memory safety, or both. Rust's [ownership model](https://doc.rust-lang.org/book/ch04-00-understanding-ownership.html) guarantees specific types of memory safety, and makes it easier and less bug-prone than many other languages to address other types of memory safety.
169+
170+
* **Spatial** memory safety generally describes "invalid access" types of errors to a region of memory (space), such as out-of-bound array accesses or the dereferencing of an invalid pointer.
171+
172+
* **Temporal** memory safety generally refers to where the validity of memory access depends on _when_ the memory is accessed (time). Examples include use-after-free, use-before-allocation, or incorrect use of [atomics](https://doc.rust-lang.org/nomicon/atomics.html).
173+
174+
Note that there are _other_ types of temporal safety that do not involve memory, such as (incorrect) concurrency patterns, unintentional infinite loops, liveness guarantees, work starvation, and deadlocks. In general Rust makes it easier to ameliorate this type of "unsafety", such as with [mutexes](https://doc.rust-lang.org/book/ch16-03-shared-state.html), but without care temporal safety still requires care.
175+
176+
### Modified Condition/Decision Coverage
177+
[Modified Condition/Decision Coverage]: #modified-condition-decision-coverage
178+
179+
[Modified condition/decision coverage](https://en.wikipedia.org/wiki/Modified_condition/decision_coverage) (MC/DC) is a code coverage criterion used in software testing. It is one of the most stringent forms of [code coverage](https://en.wikipedia.org/wiki/Code_coverage) that is mandated at the highest levels of avionics, automotive, and industrial functiontional safety.
180+
150181
### Niche
151182
[niche]: #niche
152183

@@ -237,6 +268,31 @@ For some more information, see [this document proposing a more precise definitio
237268
Another example of pointer provenance is the "tag" from [Stacked Borrows][stacked-borrows].
238269
For some more information, see [this blog post](https://www.ralfj.de/blog/2018/07/24/pointers-and-bytes.html).
239270

271+
### Pure Function
272+
[pure function]: #pure-function
273+
274+
A [pure function](https://en.wikipedia.org/wiki/Pure_function) is one that:
275+
* Given the same input, always returns the same output
276+
* Has no side effects (doesn't modify state outside its scope)
277+
* Doesn't depend on external state
278+
279+
Pure functions are important because they make it considerably easier for both compilers and humans to reason about the information flow through a program.
280+
281+
Pure functions are often used in a "numerical mathematics" sense, such as trigonometric functions like `sin` and `cos`, or abstract operators such as matrix multiplication operators, where we know _a priori_ that the same inputs always give the same outputs.
282+
283+
However, pure functions are _also_ useful because they can be composed into a [monad](https://stackoverflow.com/questions/3870088/a-monad-is-just-a-monoid-in-the-category-of-endofunctors-whats-the-problem) design pattern. Monads can be thought of as a design pattern that helps us compose pure functions when we need to deal with effects or computations that wouldn't normally be pure. Monads provide a way to:
284+
* Wrap a value in a context, such as [`std::option`](https://doc.rust-lang.org/std/option/) or [`std::result`](https://doc.rust-lang.org/std/result/)
285+
* Chain operations on that wrapped value, such as [`std::iter::FlatMap`](https://doc.rust-lang.org/std/iter/struct.FlatMap.html)
286+
287+
### Regulatory Approach
288+
[regulatory approach]: #regulatory-approach
289+
290+
Although software engineers in general, and Rust programmers in specific, tend to view "unsafe code" through the lens of programming languages, _safety regulators_ usually view "unsafe code" through either a "risk-based" or "objective-based" approach. For example:
291+
292+
* **Risk-based** approaches, such as the automotive standard [ISO 26262](https://en.wikipedia.org/wiki/ISO_26262), use Hazard Analysis and Risk Assessment ([HARA](https://en.wikipedia.org/wiki/Hazard_analysis)) to identify potential hazards and determine appropriate safety requirements based on the risk class / Safety Integrity Level ([SIL](https://en.wikipedia.org/wiki/Safety_integrity_level)).
293+
294+
* **Objective-based** approaches, such as the guidance provided by [DO-178C/ED-12C](https://en.wikipedia.org/wiki/DO-178C) in aerospace, focus on achieving specific objectives rather than prescribing specific processes.
295+
240296
### Representation (relation)
241297
[representation relation]: #representation-relation
242298

0 commit comments

Comments
 (0)