Unsafe guidelines
- Rust course
- Expert
- Lesson 41/46
- 4 min
Learn unsafe Rust writing guidelines and a checklist.
Unsafe guidelines
An API is sound if no undefined behaviour can occur however safe code uses it. Rules when writing unsafe code: next to every unsafe block, write a // SAFETY: comment explaining why it's safe; document the contract of unsafe fns with # Safety; enforce the contract at runtime with assert! where possible; and run the tests under Miri:
$ rustup +nightly component add miri
$ cargo +nightly miri test # catches unaligned access, use-after-free, data racesLints help too: #![deny(unsafe_op_in_unsafe_fn)], clippy::undocumented_unsafe_blocks.
A sound wrapper
Once the contract is checked and a safe result is returned on failure, the function containing unsafe stays safe:
fn ilk_iki(v: &[i32]) -> Option<(i32, i32)> {
if v.len() < 2 {
return None;
}
// SAFETY: v.len() >= 2 was checked above.
unsafe { Some((*v.get_unchecked(0), *v.get_unchecked(1))) }
}In this example unsafe isn't actually needed (v.get(..2) would do); unsafe should be used only when there's a measured gain.
Practice Sound access
Write the ilk_iki function above with a // SAFETY: comment. Print the results for [4, 5, 6] and [9] with {:?}, separated by a space.
Starter code
fn main() {
// buraya yaz
}Sample solution
fn ilk_iki(v: &[i32]) -> Option<(i32, i32)> {
if v.len() < 2 {
return None;
}
// SAFETY: yukarıda v.len() >= 2 olduğu denetlendi.
unsafe { Some((*v.get_unchecked(0), *v.get_unchecked(1))) }
}
fn main() {
println!("{:?} {:?}", ilk_iki(&[4, 5, 6]), ilk_iki(&[9]));
}Expected output
Some((4, 5)) None
Questions and answers
Review the lesson questions together with their answers. To test yourself, solve the lesson interactively.
1 If an unsafe block inside a safe function can produce UB on wrong input, what is the function?
- Safe
- Acceptable
- Unsound; it must either check the input or be an unsafe fn Correct answer
- Sound
Explanation: A safe signature is the promise "whatever input you call it with, there's no UB".
2 Justification comment
// ____: yukarıda v.len() >= 2 olduğu denetlendi.
unsafe { *v.get_unchecked(1) }// SAFETY: yukarıda v.len() >= 2 olduğu denetlendi.
unsafe { *v.get_unchecked(1) }Explanation: The // SAFETY: comment documents why the unsafe block is correct.
3 Concept and meaning
| Term | Meaning |
|---|---|
Sound |
UB impossible from safe code |
Miri |
Interpreter catching UB |
// SAFETY: |
Justification |
# Safety |
Contract documentation |