Learn unsafe Rust: Provide initial content for the chapter "Dangling and unaligned pointers"

[PLeVasseur]

Provide initial content for the Dangling and unaligned pointers chapter of the Learn unsafe Rust book.

Based on the guidelines for a chapter,

Dangling and unsafe pointers

Intro to what danging and unaligned pointers are

Usage:

• Working across FFI bounds, needing to pass pointer and length of a buffer
• Performance sensitive operations, e.g. I recall nalgebra uses unsafe for some things like this
• ... others

How UB happen when dealing with them

• Some operations we perform are OK to do and arrive at unaligned, others must be aligned
• Good to have some definition here about alignment and references

Thinking about dangling and unaligned pointers is relevant (not always obvious)

• Todo

Common techniques to work safely to avoid dangling and unaligned pointers

• The stdlib seems to have some reasonable resources here
  • A fair number are marked unstable and nightly-only, would be good to see their usage in reality too (see e.g. ptr::as_uninit_slice_mut for a fairy comprehensive list of things that must be true to not get UB!)

Decided vs current gaps in specification vs direction of Rust / Rust's spec

For example ptr::read_volatile, which acknowledges:

Rust does not currently have a rigorously and formally defined memory model, so the precise semantics of what “volatile” means here is subject to change over time. That being said, the semantics will almost always end up pretty similar to C11’s definition of volatile.

General notes to me / team

• In general, if there's a stdlib unsafe function to do something, we should lean towards recommending that when relevant
  • For someone new to this part of unsafe like me, they also seem to go into enough detail to learn

Resources

Filling in some resources that seem useful, feel free to sound off with more and I can add them to the first comment.

• stdlib ptr documentation
• nalgebra makes use of pointers and pointer arithmetic IIRC to do things like get custom views into matrices

Folks interested

• @squell
• @valexandru
• @iglesias

[squell]

I've been reviewing https://rust-lang.github.io/unsafe-code-guidelines/layout/pointers.html and generally, the 'size' and 'alignment' requirements for the most part don't really surprise me. But I'm going to dump some thoughts here since otherwise, they'll be lost again :-)

• I think it's fairly clear to summarise the UCG as "there are thin (1-word) and fat (2-word) pointers and they're all word-aligned", but this is only guaranteed this Sized types as well as the three most common !Sized types.

  A more helpful coding guidelines (which I guess is our aim) should be a bit more expansive:

  • If there are common examples of !Sized types that do not fit the mold given above---why not list a few
  • There are "downstream consequences" of the above rule. E.g. given the implementation of &Cstr, due to the #repr(transparant)], I'm very confident that &CStr will also be a "fat pointer" with "word-alignment". It's perhaps very tedious to list every type in the standard library like this, but we can do at least more than UCG's three...
  • How to remedy this (e.g. when and how to write tests that verify your assumptions about the type's size/alignment).

• When passing a pointer across a FFI boundary, of course the rules of the 'target' may also matter. E.g., the commonest is probably bridging Rust<->C; and in C the aliasing rules are of course stricter and things like restrict and -fstrict-aliasing can create hazards that Rust doesn't have. Not sure how deep the Rust unsafe coding guidelines can go into that (and then, this part probably falls more under the FFI chapter).

• A sideways related observation, but it needs to go somewhere: I've observed (and felt) the incentive to quickly "convert a pointer to a reference", since in Rust that only requires a single unsafe block instead of needing unsafe every time you dereference the pointer. It's less unsafe, that has to be good, right? But of course Rust places strong type guarantees on references which makes this perhaps not such a great idea. So maybe a coding guidelines on using pointers should also point out that converting a pointer to a Rust-reference is not an innocent thing to do, and alternatives such as NonNull should be considered first, as well.

[PLeVasseur]

Thanks @squell for your thoughts. I definitely feel your last point, does make it seem "more safe".