mirror of https://github.com/rust-lang/nomicon
Alexis Beingessner
10 years ago
committed by
Manish Goregaokar
parent
03b2f6be59
commit
fad7507d4e
Binary file not shown.
Binary file not shown.
Binary file not shown.
@ -1,3 +1,254 @@
|
|||||||
# The Unsafe Rust Programming Language (Book)
|
% The Unsafe Rust Programming Language
|
||||||
|
|
||||||
|
**This document is about advanced functionality and low-level development practices
|
||||||
|
in the Rust Programming Language. Most of the things discussed won't matter
|
||||||
|
to the average Rust programmer. However if you wish to correctly write unsafe
|
||||||
|
code in Rust, this text contains invaluable information.**
|
||||||
|
|
||||||
|
This document seeks to complement [The Rust Programming Language Book][trpl] (TRPL).
|
||||||
|
Where TRPL introduces the language and teaches the basics, TURPL dives deep into
|
||||||
|
the specification of the language, and all the nasty bits necessary to write
|
||||||
|
Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know
|
||||||
|
the basics of the language and systems programming. We will not explain the
|
||||||
|
stack or heap, we will not explain the syntax.
|
||||||
|
|
||||||
|
|
||||||
|
# A Tale Of Two Languages
|
||||||
|
|
||||||
|
Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust.
|
||||||
|
Any time someone opines the guarantees of Rust, they are almost surely talking about
|
||||||
|
Safe Rust. However Safe Rust is not sufficient to write every program. For that,
|
||||||
|
we need the Unsafe Rust superset.
|
||||||
|
|
||||||
|
Most fundamentally, writing bindings to other languages
|
||||||
|
(such as the C exposed by your operating system) is never going to be safe. Rust
|
||||||
|
can't control what other languages do to program execution! However Unsafe Rust is
|
||||||
|
also necessary to construct fundamental abstractions where the type system is not
|
||||||
|
sufficient to automatically prove what you're doing is sound.
|
||||||
|
|
||||||
|
Indeed, the Rust standard library is implemented in Rust, and it makes substantial
|
||||||
|
use of Unsafe Rust for implementing IO, memory allocation, collections,
|
||||||
|
synchronization, and other low-level computational primitives.
|
||||||
|
|
||||||
|
Upon hearing this, many wonder why they would not simply just use C or C++ in place of
|
||||||
|
Rust (or just use a "real" safe language). If we're going to do unsafe things, why not
|
||||||
|
lean on these much more established languages?
|
||||||
|
|
||||||
|
The most important difference between C++ and Rust is a matter of defaults:
|
||||||
|
Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular
|
||||||
|
action. In deciding to work with unchecked uninitialized memory, this does not
|
||||||
|
suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`,
|
||||||
|
one does not have to suddenly worry about indexing out of bounds on `y`.
|
||||||
|
C and C++, by contrast, have pervasive unsafety baked into the language. Even the
|
||||||
|
modern best practices like `unique_ptr` have various safety pitfalls.
|
||||||
|
|
||||||
|
It should also be noted that writing Unsafe Rust should be regarded as an exceptional
|
||||||
|
action. Unsafe Rust is often the domain of *fundamental libraries*. Anything that needs
|
||||||
|
to make FFI bindings or define core abstractions. These fundamental libraries then expose
|
||||||
|
a *safe* interface for intermediate libraries and applications to build upon. And these
|
||||||
|
safe interfaces make an important promise: if your application segfaults, it's not your
|
||||||
|
fault. *They* have a bug.
|
||||||
|
|
||||||
|
And really, how is that different from *any* safe language? Python, Ruby, and Java libraries
|
||||||
|
can internally do all sorts of nasty things. The languages themselves are no
|
||||||
|
different. Safe languages regularly have bugs that cause critical vulnerabilities.
|
||||||
|
The fact that Rust is written with a healthy spoonful of Unsafe Rust is no different.
|
||||||
|
However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of
|
||||||
|
C to do the nasty things that need to get done.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# What does `unsafe` mean?
|
||||||
|
|
||||||
|
Rust tries to model memory safety through the `unsafe` keyword. Interestingly,
|
||||||
|
the meaning of `unsafe` largely revolves around what
|
||||||
|
its *absence* means. If the `unsafe` keyword is absent from a program, it should
|
||||||
|
not be possible to violate memory safety under *any* conditions. The presence
|
||||||
|
of `unsafe` means that there are conditions under which this code *could*
|
||||||
|
violate memory safety.
|
||||||
|
|
||||||
|
To be more concrete, Rust cares about preventing the following things:
|
||||||
|
|
||||||
|
* Dereferencing null/dangling pointers
|
||||||
|
* Reading uninitialized memory
|
||||||
|
* Breaking the pointer aliasing rules (TBD) (llvm rules + noalias on &mut and & w/o UnsafeCell)
|
||||||
|
* Invoking Undefined Behaviour (in e.g. compiler intrinsics)
|
||||||
|
* Producing invalid primitive values:
|
||||||
|
* dangling/null references
|
||||||
|
* a `bool` that isn't 0 or 1
|
||||||
|
* an undefined `enum` discriminant
|
||||||
|
* a `char` larger than char::MAX
|
||||||
|
* A non-utf8 `str`
|
||||||
|
* Unwinding into an FFI function
|
||||||
|
* Causing a data race
|
||||||
|
|
||||||
|
That's it. That's all the Undefined Behaviour in Rust. Libraries are free to
|
||||||
|
declare arbitrary requirements if they could transitively cause memory safety
|
||||||
|
issues, but it all boils down to the above actions. Rust is otherwise
|
||||||
|
quite permisive with respect to other dubious operations. Rust considers it
|
||||||
|
"safe" to:
|
||||||
|
|
||||||
|
* Deadlock
|
||||||
|
* Leak memory
|
||||||
|
* Fail to call destructors
|
||||||
|
* Access private fields
|
||||||
|
* Overflow integers
|
||||||
|
* Delete the production database
|
||||||
|
|
||||||
|
However any program that does such a thing is *probably* incorrect. Rust just isn't
|
||||||
|
interested in modeling these problems, as they are much harder to prevent in general,
|
||||||
|
and it's literally impossible to prevent incorrect programs from getting written.
|
||||||
|
|
||||||
|
There are several places `unsafe` can appear in Rust today, which can largely be
|
||||||
|
grouped into two categories:
|
||||||
|
|
||||||
|
* There are unchecked contracts here. To declare you understand this, I require
|
||||||
|
you to write `unsafe` elsewhere:
|
||||||
|
* On functions, `unsafe` is declaring the function to be unsafe to call. Users
|
||||||
|
of the function must check the documentation to determine what this means,
|
||||||
|
and then have to write `unsafe` somewhere to identify that they're aware of
|
||||||
|
the danger.
|
||||||
|
* On trait declarations, `unsafe` is declaring that *implementing* the trait
|
||||||
|
is an unsafe operation, as it has contracts that other unsafe code is free to
|
||||||
|
trust blindly.
|
||||||
|
|
||||||
|
* I am declaring that I have, to the best of my knowledge, adhered to the
|
||||||
|
unchecked contracts:
|
||||||
|
* On trait implementations, `unsafe` is declaring that the contract of the
|
||||||
|
`unsafe` trait has been upheld.
|
||||||
|
* On blocks, `unsafe` is declaring any unsafety from an unsafe
|
||||||
|
operation within to be handled, and therefore the parent function is safe.
|
||||||
|
|
||||||
|
There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for
|
||||||
|
historical reasons and is in the process of being phased out. See the section on
|
||||||
|
destructors for details.
|
||||||
|
|
||||||
|
Some examples of unsafe functions:
|
||||||
|
|
||||||
|
* `slice::get_unchecked` will perform unchecked indexing, allowing memory
|
||||||
|
safety to be freely violated.
|
||||||
|
* `ptr::offset` in an intrinsic that invokes Undefined Behaviour if it is
|
||||||
|
not "in bounds" as defined by LLVM (see the lifetimes section for details).
|
||||||
|
* `mem::transmute` reinterprets some value as having the given type,
|
||||||
|
bypassing type safety in arbitrary ways. (see the conversions section for details)
|
||||||
|
* All FFI functions are `unsafe` because they can do arbitrary things.
|
||||||
|
C being an obvious culprit, but generally any language can do something
|
||||||
|
that Rust isn't happy about. (see the FFI section for details)
|
||||||
|
|
||||||
|
As of Rust 1.0 there are exactly two unsafe traits:
|
||||||
|
|
||||||
|
* `Send` is a marker trait (it has no actual API) that promises implementors
|
||||||
|
are safe to send to another thread.
|
||||||
|
* `Sync` is a marker trait that promises that threads can safely share
|
||||||
|
implementors through a shared reference.
|
||||||
|
|
||||||
|
All other traits that declare any kind of contract *really* can't be trusted
|
||||||
|
to adhere to their contract when memory-safety is at stake. For instance Rust has
|
||||||
|
`PartialOrd` and `Ord` to differentiate between types which can "just" be
|
||||||
|
compared and those that implement a total ordering. However you can't actually
|
||||||
|
trust an implementor of `Ord` to actually provide a total ordering if failing to
|
||||||
|
do so causes you to e.g. index out of bounds. But if it just makes your program
|
||||||
|
do a stupid thing, then it's "fine" to rely on `Ord`.
|
||||||
|
|
||||||
|
The reason this is the case is that `Ord` is safe to implement, and it should be
|
||||||
|
impossible for bad *safe* code to violate memory safety. Rust has traditionally
|
||||||
|
avoided making traits unsafe because it makes `unsafe` pervasive in the language,
|
||||||
|
which is not desirable. The only reason `Send` and `Sync` are unsafe is because
|
||||||
|
thread safety is a sort of fundamental thing that a program can't really guard
|
||||||
|
against locally (even by-value message passing still requires a notion Send).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# Working with unsafe
|
||||||
|
|
||||||
|
Rust generally only gives us the tools to talk about safety in a scoped and
|
||||||
|
binary manner. Unfortunately reality is significantly more complicated than that.
|
||||||
|
For instance, consider the following toy function:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
fn do_idx(idx: usize, arr: &[u8]) -> Option<u8> {
|
||||||
|
if idx < arr.len() {
|
||||||
|
unsafe {
|
||||||
|
Some(*arr.get_unchecked(idx))
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
None
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Clearly, this function is safe. We check that the index is in bounds, and if it
|
||||||
|
is, index into the array in an unchecked manner. But even in such a trivial
|
||||||
|
function, the scope of the unsafe block is questionable. Consider changing the
|
||||||
|
`<` to a `<=`:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
fn do_idx(idx: usize, arr: &[u8]) -> Option<u8> {
|
||||||
|
if idx <= arr.len() {
|
||||||
|
unsafe {
|
||||||
|
Some(*arr.get_unchecked(idx))
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
None
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This program is now unsound, an yet *we only modified safe code*. This is the
|
||||||
|
fundamental problem of safety: it's non-local. The soundness of our unsafe
|
||||||
|
operations necessarily depends on the state established by "safe" operations.
|
||||||
|
Although safety *is* modular (we *still* don't need to worry about about
|
||||||
|
unrelated safety issues like uninitialized memory), it quickly contaminates the
|
||||||
|
surrounding code.
|
||||||
|
|
||||||
|
Trickier than that is when we get into actual statefulness. Consider a simple
|
||||||
|
implementation of `Vec`:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
// Note this defintion is insufficient. See the section on lifetimes.
|
||||||
|
struct Vec<T> {
|
||||||
|
ptr: *mut T,
|
||||||
|
len: usize,
|
||||||
|
cap: usize,
|
||||||
|
}
|
||||||
|
|
||||||
|
// Note this implementation does not correctly handle zero-sized types.
|
||||||
|
// We currently live in a nice imaginary world of only positive fixed-size
|
||||||
|
// types.
|
||||||
|
impl<T> Vec<T> {
|
||||||
|
fn push(&mut self, elem: T) {
|
||||||
|
if self.len == self.cap {
|
||||||
|
// not important for this example
|
||||||
|
self.reallocate();
|
||||||
|
}
|
||||||
|
unsafe {
|
||||||
|
ptr::write(self.ptr.offset(len as isize), elem);
|
||||||
|
self.len += 1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This code is simple enough to reasonably audit and verify. Now consider
|
||||||
|
adding the following method:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
fn make_room(&mut self) {
|
||||||
|
// grow the capacity
|
||||||
|
self.cap += 1;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This code is safe, but it is also completely unsound. Changing the capacity
|
||||||
|
violates the invariants of Vec (that `cap` reflects the allocated space in the
|
||||||
|
Vec). This is not something the rest of `Vec` can guard against. It *has* to
|
||||||
|
trust the capacity field because there's no way to verify it.
|
||||||
|
|
||||||
|
`unsafe` does more than pollute a whole function: it pollutes a whole *module*.
|
||||||
|
Generally, the only bullet-proof way to limit the scope of unsafe code is at the
|
||||||
|
module boundary with privacy.
|
||||||
|
|
||||||
|
[trpl]: https://doc.rust-lang.org/book/
|
||||||
|
|
||||||
[Start at the intro](http://www.cglab.ca/~abeinges/blah/turpl/intro.html)
|
|
||||||
@ -0,0 +1,9 @@
|
|||||||
|
# Summary
|
||||||
|
|
||||||
|
* [Data Layout](data.md)
|
||||||
|
* [Ownership and Lifetimes](lifetimes.md)
|
||||||
|
* [Conversions](conversions.md)
|
||||||
|
* [Uninitialized Memory](uninitialized.md)
|
||||||
|
* [Ownership-oriented resource management (RAII)](raii.md)
|
||||||
|
* [Concurrency](concurrency.md)
|
||||||
|
* [Example: Implementing Vec](vec.md)
|
||||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@ -1,267 +0,0 @@
|
|||||||
% The Unsafe Rust Programming Language
|
|
||||||
|
|
||||||
**This document is about advanced functionality and low-level development practices
|
|
||||||
in the Rust Programming Language. Most of the things discussed won't matter
|
|
||||||
to the average Rust programmer. However if you wish to correctly write unsafe
|
|
||||||
code in Rust, this text contains invaluable information.**
|
|
||||||
|
|
||||||
This document seeks to complement [The Rust Programming Language Book][] (TRPL).
|
|
||||||
Where TRPL introduces the language and teaches the basics, TURPL dives deep into
|
|
||||||
the specification of the language, and all the nasty bits necessary to write
|
|
||||||
Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know
|
|
||||||
the basics of the language and systems programming. We will not explain the
|
|
||||||
stack or heap, we will not explain the syntax.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# Chapters
|
|
||||||
|
|
||||||
* [Data Layout](data.html)
|
|
||||||
* [Ownership and Lifetimes](lifetimes.html)
|
|
||||||
* [Conversions](conversions.html)
|
|
||||||
* [Uninitialized Memory](uninitialized.html)
|
|
||||||
* [Ownership-oriented resource management (RAII)](raii.html)
|
|
||||||
* [Concurrency](concurrency.html)
|
|
||||||
* [Example: Implementing Vec](vec.html)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# A Tale Of Two Languages
|
|
||||||
|
|
||||||
Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust.
|
|
||||||
Any time someone opines the guarantees of Rust, they are almost surely talking about
|
|
||||||
Safe Rust. However Safe Rust is not sufficient to write every program. For that,
|
|
||||||
we need the Unsafe Rust superset.
|
|
||||||
|
|
||||||
Most fundamentally, writing bindings to other languages
|
|
||||||
(such as the C exposed by your operating system) is never going to be safe. Rust
|
|
||||||
can't control what other languages do to program execution! However Unsafe Rust is
|
|
||||||
also necessary to construct fundamental abstractions where the type system is not
|
|
||||||
sufficient to automatically prove what you're doing is sound.
|
|
||||||
|
|
||||||
Indeed, the Rust standard library is implemented in Rust, and it makes substantial
|
|
||||||
use of Unsafe Rust for implementing IO, memory allocation, collections,
|
|
||||||
synchronization, and other low-level computational primitives.
|
|
||||||
|
|
||||||
Upon hearing this, many wonder why they would not simply just use C or C++ in place of
|
|
||||||
Rust (or just use a "real" safe language). If we're going to do unsafe things, why not
|
|
||||||
lean on these much more established languages?
|
|
||||||
|
|
||||||
The most important difference between C++ and Rust is a matter of defaults:
|
|
||||||
Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular
|
|
||||||
action. In deciding to work with unchecked uninitialized memory, this does not
|
|
||||||
suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`,
|
|
||||||
one does not have to suddenly worry about indexing out of bounds on `y`.
|
|
||||||
C and C++, by contrast, have pervasive unsafety baked into the language. Even the
|
|
||||||
modern best practices like `unique_ptr` have various safety pitfalls.
|
|
||||||
|
|
||||||
It should also be noted that writing Unsafe Rust should be regarded as an exceptional
|
|
||||||
action. Unsafe Rust is often the domain of *fundamental libraries*. Anything that needs
|
|
||||||
to make FFI bindings or define core abstractions. These fundamental libraries then expose
|
|
||||||
a *safe* interface for intermediate libraries and applications to build upon. And these
|
|
||||||
safe interfaces make an important promise: if your application segfaults, it's not your
|
|
||||||
fault. *They* have a bug.
|
|
||||||
|
|
||||||
And really, how is that different from *any* safe language? Python, Ruby, and Java libraries
|
|
||||||
can internally do all sorts of nasty things. The languages themselves are no
|
|
||||||
different. Safe languages regularly have bugs that cause critical vulnerabilities.
|
|
||||||
The fact that Rust is written with a healthy spoonful of Unsafe Rust is no different.
|
|
||||||
However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of
|
|
||||||
C to do the nasty things that need to get done.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# What does `unsafe` mean?
|
|
||||||
|
|
||||||
Rust tries to model memory safety through the `unsafe` keyword. Interestingly,
|
|
||||||
the meaning of `unsafe` largely revolves around what
|
|
||||||
its *absence* means. If the `unsafe` keyword is absent from a program, it should
|
|
||||||
not be possible to violate memory safety under *any* conditions. The presence
|
|
||||||
of `unsafe` means that there are conditions under which this code *could*
|
|
||||||
violate memory safety.
|
|
||||||
|
|
||||||
To be more concrete, Rust cares about preventing the following things:
|
|
||||||
|
|
||||||
* Dereferencing null/dangling pointers
|
|
||||||
* Reading uninitialized memory
|
|
||||||
* Breaking the pointer aliasing rules (TBD) (llvm rules + noalias on &mut and & w/o UnsafeCell)
|
|
||||||
* Invoking Undefined Behaviour (in e.g. compiler intrinsics)
|
|
||||||
* Producing invalid primitive values:
|
|
||||||
* dangling/null references
|
|
||||||
* a `bool` that isn't 0 or 1
|
|
||||||
* an undefined `enum` discriminant
|
|
||||||
* a `char` larger than char::MAX
|
|
||||||
* A non-utf8 `str`
|
|
||||||
* Unwinding into an FFI function
|
|
||||||
* Causing a data race
|
|
||||||
|
|
||||||
That's it. That's all the Undefined Behaviour in Rust. Libraries are free to
|
|
||||||
declare arbitrary requirements if they could transitively cause memory safety
|
|
||||||
issues, but it all boils down to the above actions. Rust is otherwise
|
|
||||||
quite permisive with respect to other dubious operations. Rust considers it
|
|
||||||
"safe" to:
|
|
||||||
|
|
||||||
* Deadlock
|
|
||||||
* Leak memory
|
|
||||||
* Fail to call destructors
|
|
||||||
* Access private fields
|
|
||||||
* Overflow integers
|
|
||||||
* Delete the production database
|
|
||||||
|
|
||||||
However any program that does such a thing is *probably* incorrect. Rust just isn't
|
|
||||||
interested in modeling these problems, as they are much harder to prevent in general,
|
|
||||||
and it's literally impossible to prevent incorrect programs from getting written.
|
|
||||||
|
|
||||||
There are several places `unsafe` can appear in Rust today, which can largely be
|
|
||||||
grouped into two categories:
|
|
||||||
|
|
||||||
* There are unchecked contracts here. To declare you understand this, I require
|
|
||||||
you to write `unsafe` elsewhere:
|
|
||||||
* On functions, `unsafe` is declaring the function to be unsafe to call. Users
|
|
||||||
of the function must check the documentation to determine what this means,
|
|
||||||
and then have to write `unsafe` somewhere to identify that they're aware of
|
|
||||||
the danger.
|
|
||||||
* On trait declarations, `unsafe` is declaring that *implementing* the trait
|
|
||||||
is an unsafe operation, as it has contracts that other unsafe code is free to
|
|
||||||
trust blindly.
|
|
||||||
|
|
||||||
* I am declaring that I have, to the best of my knowledge, adhered to the
|
|
||||||
unchecked contracts:
|
|
||||||
* On trait implementations, `unsafe` is declaring that the contract of the
|
|
||||||
`unsafe` trait has been upheld.
|
|
||||||
* On blocks, `unsafe` is declaring any unsafety from an unsafe
|
|
||||||
operation within to be handled, and therefore the parent function is safe.
|
|
||||||
|
|
||||||
There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for
|
|
||||||
historical reasons and is in the process of being phased out. See the section on
|
|
||||||
destructors for details.
|
|
||||||
|
|
||||||
Some examples of unsafe functions:
|
|
||||||
|
|
||||||
* `slice::get_unchecked` will perform unchecked indexing, allowing memory
|
|
||||||
safety to be freely violated.
|
|
||||||
* `ptr::offset` in an intrinsic that invokes Undefined Behaviour if it is
|
|
||||||
not "in bounds" as defined by LLVM (see the lifetimes section for details).
|
|
||||||
* `mem::transmute` reinterprets some value as having the given type,
|
|
||||||
bypassing type safety in arbitrary ways. (see the conversions section for details)
|
|
||||||
* All FFI functions are `unsafe` because they can do arbitrary things.
|
|
||||||
C being an obvious culprit, but generally any language can do something
|
|
||||||
that Rust isn't happy about. (see the FFI section for details)
|
|
||||||
|
|
||||||
As of Rust 1.0 there are exactly two unsafe traits:
|
|
||||||
|
|
||||||
* `Send` is a marker trait (it has no actual API) that promises implementors
|
|
||||||
are safe to send to another thread.
|
|
||||||
* `Sync` is a marker trait that promises that threads can safely share
|
|
||||||
implementors through a shared reference.
|
|
||||||
|
|
||||||
All other traits that declare any kind of contract *really* can't be trusted
|
|
||||||
to adhere to their contract when memory-safety is at stake. For instance Rust has
|
|
||||||
`PartialOrd` and `Ord` to differentiate between types which can "just" be
|
|
||||||
compared and those that implement a total ordering. However you can't actually
|
|
||||||
trust an implementor of `Ord` to actually provide a total ordering if failing to
|
|
||||||
do so causes you to e.g. index out of bounds. But if it just makes your program
|
|
||||||
do a stupid thing, then it's "fine" to rely on `Ord`.
|
|
||||||
|
|
||||||
The reason this is the case is that `Ord` is safe to implement, and it should be
|
|
||||||
impossible for bad *safe* code to violate memory safety. Rust has traditionally
|
|
||||||
avoided making traits unsafe because it makes `unsafe` pervasive in the language,
|
|
||||||
which is not desirable. The only reason `Send` and `Sync` are unsafe is because
|
|
||||||
thread safety is a sort of fundamental thing that a program can't really guard
|
|
||||||
against locally (even by-value message passing still requires a notion Send).
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# Working with unsafe
|
|
||||||
|
|
||||||
Rust generally only gives us the tools to talk about safety in a scoped and
|
|
||||||
binary manner. Unfortunately reality is significantly more complicated than that.
|
|
||||||
For instance, consider the following toy function:
|
|
||||||
|
|
||||||
```rust
|
|
||||||
fn do_idx(idx: usize, arr: &[u8]) -> Option<u8> {
|
|
||||||
if idx < arr.len() {
|
|
||||||
unsafe {
|
|
||||||
Some(*arr.get_unchecked(idx))
|
|
||||||
}
|
|
||||||
} else {
|
|
||||||
None
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Clearly, this function is safe. We check that the index is in bounds, and if it
|
|
||||||
is, index into the array in an unchecked manner. But even in such a trivial
|
|
||||||
function, the scope of the unsafe block is questionable. Consider changing the
|
|
||||||
`<` to a `<=`:
|
|
||||||
|
|
||||||
```rust
|
|
||||||
fn do_idx(idx: usize, arr: &[u8]) -> Option<u8> {
|
|
||||||
if idx <= arr.len() {
|
|
||||||
unsafe {
|
|
||||||
Some(*arr.get_unchecked(idx))
|
|
||||||
}
|
|
||||||
} else {
|
|
||||||
None
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
This program is now unsound, an yet *we only modified safe code*. This is the
|
|
||||||
fundamental problem of safety: it's non-local. The soundness of our unsafe
|
|
||||||
operations necessarily depends on the state established by "safe" operations.
|
|
||||||
Although safety *is* modular (we *still* don't need to worry about about
|
|
||||||
unrelated safety issues like uninitialized memory), it quickly contaminates the
|
|
||||||
surrounding code.
|
|
||||||
|
|
||||||
Trickier than that is when we get into actual statefulness. Consider a simple
|
|
||||||
implementation of `Vec`:
|
|
||||||
|
|
||||||
```rust
|
|
||||||
// Note this defintion is insufficient. See the section on lifetimes.
|
|
||||||
struct Vec<T> {
|
|
||||||
ptr: *mut T,
|
|
||||||
len: usize,
|
|
||||||
cap: usize,
|
|
||||||
}
|
|
||||||
|
|
||||||
// Note this implementation does not correctly handle zero-sized types.
|
|
||||||
// We currently live in a nice imaginary world of only positive fixed-size
|
|
||||||
// types.
|
|
||||||
impl<T> Vec<T> {
|
|
||||||
fn push(&mut self, elem: T) {
|
|
||||||
if self.len == self.cap {
|
|
||||||
// not important for this example
|
|
||||||
self.reallocate();
|
|
||||||
}
|
|
||||||
unsafe {
|
|
||||||
ptr::write(self.ptr.offset(len as isize), elem);
|
|
||||||
self.len += 1;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
This code is simple enough to reasonably audit and verify. Now consider
|
|
||||||
adding the following method:
|
|
||||||
|
|
||||||
```rust
|
|
||||||
fn make_room(&mut self) {
|
|
||||||
// grow the capacity
|
|
||||||
self.cap += 1;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
This code is safe, but it is also completely unsound. Changing the capacity
|
|
||||||
violates the invariants of Vec (that `cap` reflects the allocated space in the
|
|
||||||
Vec). This is not something the rest of `Vec` can guard against. It *has* to
|
|
||||||
trust the capacity field because there's no way to verify it.
|
|
||||||
|
|
||||||
`unsafe` does more than pollute a whole function: it pollutes a whole *module*.
|
|
||||||
Generally, the only bullet-proof way to limit the scope of unsafe code is at the
|
|
||||||
module boundary with privacy.
|
|
||||||
|
|
||||||
@ -0,0 +1,407 @@
|
|||||||
|
/**
|
||||||
|
* Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
|
||||||
|
* file at the top-level directory of this distribution and at
|
||||||
|
* http://rust-lang.org/COPYRIGHT.
|
||||||
|
* With elements taken from Bootstrap v3.0.2 (MIT licensed).
|
||||||
|
*
|
||||||
|
* Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
||||||
|
* http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
||||||
|
* <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
||||||
|
* option. This file may not be copied, modified, or distributed
|
||||||
|
* except according to those terms.
|
||||||
|
*/
|
||||||
|
@font-face {
|
||||||
|
font-family: 'Fira Sans';
|
||||||
|
font-style: normal;
|
||||||
|
font-weight: 400;
|
||||||
|
src: local('Fira Sans'), url("FiraSans-Regular.woff") format('woff');
|
||||||
|
}
|
||||||
|
@font-face {
|
||||||
|
font-family: 'Fira Sans';
|
||||||
|
font-style: normal;
|
||||||
|
font-weight: 500;
|
||||||
|
src: local('Fira Sans Medium'), url("FiraSans-Medium.woff") format('woff');
|
||||||
|
}
|
||||||
|
@font-face {
|
||||||
|
font-family: 'Source Serif Pro';
|
||||||
|
font-style: normal;
|
||||||
|
font-weight: 400;
|
||||||
|
src: local('Source Serif Pro'), url("SourceSerifPro-Regular.woff") format('woff');
|
||||||
|
}
|
||||||
|
@font-face {
|
||||||
|
font-family: 'Source Serif Pro';
|
||||||
|
font-style: italic;
|
||||||
|
font-weight: 400;
|
||||||
|
src: url("Heuristica-Italic.woff") format('woff');
|
||||||
|
}
|
||||||
|
@font-face {
|
||||||
|
font-family: 'Source Serif Pro';
|
||||||
|
font-style: normal;
|
||||||
|
font-weight: 700;
|
||||||
|
src: local('Source Serif Pro Bold'), url("SourceSerifPro-Bold.woff") format('woff');
|
||||||
|
}
|
||||||
|
@font-face {
|
||||||
|
font-family: 'Source Code Pro';
|
||||||
|
font-style: normal;
|
||||||
|
font-weight: 400;
|
||||||
|
src: local('Source Code Pro'), url("SourceCodePro-Regular.woff") format('woff');
|
||||||
|
}
|
||||||
|
|
||||||
|
*:not(body) {
|
||||||
|
-webkit-box-sizing: border-box;
|
||||||
|
-moz-box-sizing: border-box;
|
||||||
|
box-sizing: border-box;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* General structure */
|
||||||
|
|
||||||
|
body {
|
||||||
|
background-color: white;
|
||||||
|
margin: 0 auto;
|
||||||
|
padding: 0 15px;
|
||||||
|
font-family: "Source Serif Pro", Georgia, Times, "Times New Roman", serif;
|
||||||
|
font-size: 18px;
|
||||||
|
color: #333;
|
||||||
|
line-height: 1.428571429;
|
||||||
|
|
||||||
|
-webkit-font-feature-settings: "kern", "liga";
|
||||||
|
-moz-font-feature-settings: "kern", "liga";
|
||||||
|
font-feature-settings: "kern", "liga";
|
||||||
|
}
|
||||||
|
@media (min-width: 768px) {
|
||||||
|
body {
|
||||||
|
max-width: 750px;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
h1, h2, h3, h4, h5, h6, nav, #versioninfo {
|
||||||
|
font-family: "Fira Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
|
||||||
|
}
|
||||||
|
h1, h2, h3, h4, h5, h6 {
|
||||||
|
color: black;
|
||||||
|
font-weight: 400;
|
||||||
|
line-height: 1.1;
|
||||||
|
}
|
||||||
|
h1, h2, h3 {
|
||||||
|
margin-top: 20px;
|
||||||
|
margin-bottom: 15px;
|
||||||
|
}
|
||||||
|
h1 {
|
||||||
|
margin-bottom: 20px;
|
||||||
|
}
|
||||||
|
h4, h5, h6 {
|
||||||
|
margin-top: 12px;
|
||||||
|
margin-bottom: 10px;
|
||||||
|
padding: 5px 10px;
|
||||||
|
}
|
||||||
|
h5, h6 {
|
||||||
|
text-decoration: underline;
|
||||||
|
}
|
||||||
|
|
||||||
|
h1 {
|
||||||
|
font-size: 28px;
|
||||||
|
font-weight: 500;
|
||||||
|
padding: .1em .4em;
|
||||||
|
border-bottom: 2px solid #ddd;
|
||||||
|
}
|
||||||
|
h1.title {
|
||||||
|
line-height: 1.5em;
|
||||||
|
}
|
||||||
|
h2 {
|
||||||
|
font-size: 26px;
|
||||||
|
padding: .2em .5em;
|
||||||
|
border-bottom: 1px solid #ddd;
|
||||||
|
}
|
||||||
|
h3 {
|
||||||
|
font-size: 24px;
|
||||||
|
padding: .2em .7em;
|
||||||
|
border-bottom: 1px solid #DDE8FC;
|
||||||
|
}
|
||||||
|
h4 {
|
||||||
|
font-size: 22px;
|
||||||
|
}
|
||||||
|
h5 {
|
||||||
|
font-size: 20px;
|
||||||
|
}
|
||||||
|
h6 {
|
||||||
|
font-size: 18px;
|
||||||
|
}
|
||||||
|
@media (min-width: 992px) {
|
||||||
|
h1 {
|
||||||
|
font-size: 36px;
|
||||||
|
}
|
||||||
|
h2 {
|
||||||
|
font-size: 30px;
|
||||||
|
}
|
||||||
|
h3 {
|
||||||
|
font-size: 26px;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
nav {
|
||||||
|
column-count: 2;
|
||||||
|
-moz-column-count: 2;
|
||||||
|
-webkit-column-count: 2;
|
||||||
|
font-size: 15px;
|
||||||
|
margin: 0 0 1em 0;
|
||||||
|
}
|
||||||
|
p {
|
||||||
|
margin: 0 0 1em 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
strong {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
|
||||||
|
em {
|
||||||
|
font-style: italic;
|
||||||
|
}
|
||||||
|
|
||||||
|
footer {
|
||||||
|
border-top: 1px solid #ddd;
|
||||||
|
font-size: 14.3px;
|
||||||
|
font-style: italic;
|
||||||
|
padding-top: 5px;
|
||||||
|
margin-top: 3em;
|
||||||
|
margin-bottom: 1em;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Links layout */
|
||||||
|
|
||||||
|
a {
|
||||||
|
text-decoration: none;
|
||||||
|
color: #428BCA;
|
||||||
|
background: transparent;
|
||||||
|
}
|
||||||
|
a:hover, a:focus {
|
||||||
|
color: #2A6496;
|
||||||
|
text-decoration: underline;
|
||||||
|
}
|
||||||
|
a:focus {
|
||||||
|
outline: thin dotted #333;
|
||||||
|
outline: 5px auto -webkit-focus-ring-color;
|
||||||
|
outline-offset: -2px;
|
||||||
|
}
|
||||||
|
a:hover, a:active {
|
||||||
|
outline: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
h1 a:link, h1 a:visited, h2 a:link, h2 a:visited,
|
||||||
|
h3 a:link, h3 a:visited, h4 a:link, h4 a:visited,
|
||||||
|
h5 a:link, h5 a:visited {color: black;}
|
||||||
|
h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover,
|
||||||
|
h5 a:hover {text-decoration: none;}
|
||||||
|
|
||||||
|
/* Code */
|
||||||
|
|
||||||
|
pre, code {
|
||||||
|
font-family: "Source Code Pro", Menlo, Monaco, Consolas, "DejaVu Sans Mono", monospace;
|
||||||
|
word-wrap: break-word;
|
||||||
|
}
|
||||||
|
pre {
|
||||||
|
border-left: 2px solid #eee;
|
||||||
|
white-space: pre-wrap;
|
||||||
|
padding: 14px;
|
||||||
|
padding-right: 0;
|
||||||
|
margin: 20px 0;
|
||||||
|
font-size: 13px;
|
||||||
|
word-break: break-all;
|
||||||
|
}
|
||||||
|
code {
|
||||||
|
padding: 0 2px;
|
||||||
|
color: #8D1A38;
|
||||||
|
}
|
||||||
|
pre code {
|
||||||
|
padding: 0;
|
||||||
|
font-size: inherit;
|
||||||
|
color: inherit;
|
||||||
|
}
|
||||||
|
|
||||||
|
a > code {
|
||||||
|
color: #428BCA;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Code highlighting */
|
||||||
|
pre.rust .kw { color: #8959A8; }
|
||||||
|
pre.rust .kw-2, pre.rust .prelude-ty { color: #4271AE; }
|
||||||
|
pre.rust .number, pre.rust .string { color: #718C00; }
|
||||||
|
pre.rust .self, pre.rust .boolval, pre.rust .prelude-val,
|
||||||
|
pre.rust .attribute, pre.rust .attribute .ident { color: #C82829; }
|
||||||
|
pre.rust .comment { color: #8E908C; }
|
||||||
|
pre.rust .doccomment { color: #4D4D4C; }
|
||||||
|
pre.rust .macro, pre.rust .macro-nonterminal { color: #3E999F; }
|
||||||
|
pre.rust .lifetime { color: #B76514; }
|
||||||
|
|
||||||
|
/* The rest */
|
||||||
|
|
||||||
|
#versioninfo {
|
||||||
|
text-align: center;
|
||||||
|
margin: 0.5em;
|
||||||
|
font-size: 1.1em;
|
||||||
|
}
|
||||||
|
@media (min-width: 992px) {
|
||||||
|
#versioninfo {
|
||||||
|
font-size: 0.8em;
|
||||||
|
position: fixed;
|
||||||
|
bottom: 0px;
|
||||||
|
right: 0px;
|
||||||
|
}
|
||||||
|
.white-sticker {
|
||||||
|
background-color: #fff;
|
||||||
|
margin: 2px;
|
||||||
|
padding: 0 2px;
|
||||||
|
border-radius: .2em;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
#versioninfo a.hash {
|
||||||
|
color: gray;
|
||||||
|
font-size: 80%;
|
||||||
|
}
|
||||||
|
|
||||||
|
blockquote {
|
||||||
|
color: #000;
|
||||||
|
margin: 20px 0;
|
||||||
|
padding: 15px 20px;
|
||||||
|
background-color: #f2f7f9;
|
||||||
|
border-top: .1em solid #e5eef2;
|
||||||
|
border-bottom: .1em solid #e5eef2;
|
||||||
|
}
|
||||||
|
blockquote p {
|
||||||
|
font-size: 17px;
|
||||||
|
font-weight: 300;
|
||||||
|
line-height: 1.4;
|
||||||
|
}
|
||||||
|
blockquote p:last-child {
|
||||||
|
margin-bottom: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
ul, ol {
|
||||||
|
padding-left: 25px;
|
||||||
|
}
|
||||||
|
ul ul, ol ul, ul ol, ol ol {
|
||||||
|
margin-bottom: 0;
|
||||||
|
}
|
||||||
|
dl {
|
||||||
|
margin-bottom: 20px;
|
||||||
|
}
|
||||||
|
dd {
|
||||||
|
margin-left: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
nav ul {
|
||||||
|
list-style-type: none;
|
||||||
|
margin: 0;
|
||||||
|
padding-left: 0px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Only display one level of hierarchy in the TOC */
|
||||||
|
nav ul ul {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
sub,
|
||||||
|
sup {
|
||||||
|
font-size: 75%;
|
||||||
|
line-height: 0;
|
||||||
|
position: relative;
|
||||||
|
}
|
||||||
|
|
||||||
|
hr {
|
||||||
|
margin-top: 20px;
|
||||||
|
margin-bottom: 20px;
|
||||||
|
border: 0;
|
||||||
|
border-top: 1px solid #eeeeee;
|
||||||
|
}
|
||||||
|
|
||||||
|
table {
|
||||||
|
border-collapse: collapse;
|
||||||
|
border-spacing: 0;
|
||||||
|
overflow-x: auto;
|
||||||
|
display: block;
|
||||||
|
}
|
||||||
|
|
||||||
|
table tr.odd {
|
||||||
|
background: #eee;
|
||||||
|
}
|
||||||
|
|
||||||
|
table td,
|
||||||
|
table th {
|
||||||
|
border: 1px solid #ddd;
|
||||||
|
padding: 5px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Code snippets */
|
||||||
|
|
||||||
|
.rusttest { display: none; }
|
||||||
|
pre.rust { position: relative; }
|
||||||
|
.test-arrow {
|
||||||
|
display: inline-block;
|
||||||
|
position: absolute;
|
||||||
|
top: 0;
|
||||||
|
right: 10px;
|
||||||
|
font-size: 150%;
|
||||||
|
-webkit-transform: scaleX(-1);
|
||||||
|
transform: scaleX(-1);
|
||||||
|
}
|
||||||
|
|
||||||
|
.unstable-feature {
|
||||||
|
border: 2px solid red;
|
||||||
|
padding: 5px;
|
||||||
|
}
|
||||||
|
|
||||||
|
@media (min-width: 1170px) {
|
||||||
|
pre {
|
||||||
|
font-size: 15px;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@media print {
|
||||||
|
* {
|
||||||
|
text-shadow: none !important;
|
||||||
|
color: #000 !important;
|
||||||
|
background: transparent !important;
|
||||||
|
box-shadow: none !important;
|
||||||
|
}
|
||||||
|
a, a:visited {
|
||||||
|
text-decoration: underline;
|
||||||
|
}
|
||||||
|
p a[href]:after {
|
||||||
|
content: " (" attr(href) ")";
|
||||||
|
}
|
||||||
|
footer a[href]:after {
|
||||||
|
content: "";
|
||||||
|
}
|
||||||
|
a[href^="javascript:"]:after, a[href^="#"]:after {
|
||||||
|
content: "";
|
||||||
|
}
|
||||||
|
pre, blockquote {
|
||||||
|
border: 1px solid #999;
|
||||||
|
page-break-inside: avoid;
|
||||||
|
}
|
||||||
|
@page {
|
||||||
|
margin: 2cm .5cm;
|
||||||
|
}
|
||||||
|
h1:not(.title), h2, h3 {
|
||||||
|
border-bottom: 0px none;
|
||||||
|
}
|
||||||
|
p, h2, h3 {
|
||||||
|
orphans: 3;
|
||||||
|
widows: 3;
|
||||||
|
}
|
||||||
|
h2, h3 {
|
||||||
|
page-break-after: avoid;
|
||||||
|
}
|
||||||
|
table {
|
||||||
|
border-collapse: collapse !important;
|
||||||
|
}
|
||||||
|
table td, table th {
|
||||||
|
background-color: #fff !important;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#keyword-table-marker + table thead { display: none; }
|
||||||
|
#keyword-table-marker + table td { border: none; }
|
||||||
|
#keyword-table-marker + table {
|
||||||
|
margin-left: 2em;
|
||||||
|
margin-bottom: 1em;
|
||||||
|
}
|
||||||
Loading…
Reference in new issue