The Rustonomicon

The Rustonomicon is a guide focused on the 'Dark Arts' of Unsafe Rust. It is intended for developers who already have a strong grasp of basic systems programming and Rust and wish to understand the low-level details of the language.

Key characteristics:

• Focus: It describes how to use language pieces together and the issues that arise when doing so (e.g., combining references, destructors, and unwinding), rather than just detailing syntax.
• Prerequisites: It assumes considerable prior knowledge of Rust and systems programming. It is recommended to read The Rust Programming Language first if you are not comfortable with these topics.
• Relationship to The Reference: While The Reference details syntax and semantics, The Rustonomicon explains the practical implications and complexities of those semantics. If the two documents disagree, assume The Reference is correct.
• Scope: Topics include (un)safety, unsafe primitives, creating safe abstractions, subtyping, variance, exception-safety, uninitialized memory, type punning, concurrency, FFI, and optimization.
• Edition: Unless otherwise noted, all Rust code examples in this book use the Rust 2024 edition.

MaybeUninit<T> is a wrapper type used to handle memory that has not been fully initialized. It is the standard replacement for the deprecated std::mem::uninitialized.

Key Properties:

• Drop Behavior: Dropping a MaybeUninit<T> does nothing. This makes it safe to use assignment (=) to initialize its contents, as Rust won't try to drop the 'old' uninitialized value.
• Memory Layout: For many containers (like arrays), MaybeUninit<T> has the same memory layout as T, allowing for transmute operations. However, this is not guaranteed for all containers (e.g., Option<MaybeUninit<bool>> does not have the same layout as Option<bool>).
• Safety Requirement: You must ensure that every control path (including panics) initializes the value before it is dropped if the underlying type T has a destructor. If a panic occurs before initialization, MaybeUninit prevents a double-free but may result in a memory leak of the already-initialized parts.

When implementing a thread-safe shared ownership type like Arc<T>, the layout must manage both the shared data and the reference count. Because the reference count is shared mutable state, it should be stored in the same heap allocation as the data to avoid extra indirection.

To implement this correctly in Rust, a naive structure using raw pointers is insufficient due to strict variance and incorrect ownership information provided to the drop checker. A correct implementation requires:

1. NonNull<T>: Used instead of a raw pointer to ensure the pointer is never null and to provide covariance over T (allowing Arc<&'static str> to be used where Arc<&'a str> is expected).
2. PhantomData<T>: Used to inform the compiler/drop checker that the structure has an ownership relationship with the inner data, ensuring proper destruction when the last owner is dropped.

The final layout consists of an Arc<T> struct holding a NonNull pointer to an ArcInner<T> and a PhantomData marker, while ArcInner<T> contains the AtomicUsize reference count and the actual data T.

use std::marker::PhantomData;
use std::ptr::NonNull;
use std::sync::atomic::AtomicUsize;

pub struct Arc<T> {
    ptr: NonNull<ArcInner<T>>,
    phantom: PhantomData<ArcInner<T>>,
}

pub struct ArcInner<T> {
    rc: AtomicUsize,
    data: T,
}

The dot operator (.) in Rust performs automatic type conversions to match a method's receiver type. When you call value.foo(), where value has type T, the compiler follows a specific lookup algorithm to find the correct implementation of foo:

1. By Value: The compiler first tries to call T::foo(value) directly.
2. Autoref: If by-value fails, the compiler attempts to add an automatic reference, trying <&T>::foo(value) and <&mut T>::foo(value).
3. Dereferencing: If autoref fails, the compiler uses the Deref trait to dereference T. If T: Deref<Target = U>, it tries again with type U.
4. Unsizing: If dereferencing fails, the compiler may try "unsizing" T. This converts a type with a known compile-time size into a slice type (e.g., converting [i32; 2] into [i32]) to resolve methods.

This process allows complex chains of indirections, such as accessing an index on an Rc<Box<[T; 3]>>, to work by traversing through Rc dereferencing, Box dereferencing, and finally unsizing the array into a slice.

let array: Rc<Box<[T; 3]>> = ...;
let first_entry = array[0];

Dynamically Sized Types (DSTs) are types without a statically known size or alignment. Because they lack a known size, they cannot be stored directly on the stack; they can only exist behind a pointer. These pointers are "wide pointers" that include the address plus additional metadata required to complete the type information.

Major DSTs in Rust include:

• Trait objects: dyn MyTrait. The pointer includes a vtable pointer for runtime reflection. The runtime size can be requested from the vtable.
• Slices: [T], str, etc. The pointer includes the number of elements. The runtime size is size_of::<T>() * number_of_elements.

You can define a struct containing a DST as its last field, but that struct itself becomes a DST. To create custom DSTs, use a generic type and perform an unsizing coercion.

// Can't be stored on the stack directly
struct MySuperSlice {
    info: u32,
    data: [u8],
}

struct MySuperSliceable<T: ?Sized> {
    info: u32,
    data: T,
}

fn main() {
    let sized: MySuperSliceable<[u8; 8]> = MySuperSliceable {
        info: 17,
        data: [0; 8],
    };

    let dynamic: &MySuperSliceable<[u8]> = &sized;

    // prints: "17 [0, 0, 0, 0, 0, 0, 0, 0]"
    println!("{} {:?}", dynamic.info, &dynamic.data);
}