Hey all! As many of you know, my summer internship's primary project is to try to better specify and document all the fiddly details you need to understand to correctly write unsafe Rust code.
My current primary effort for this is TURPL: The Unsafe Rust Programming Language.
TURPL is meant to complement TRPL as an advanced text. What exactly should or should not be included in TURPL is currently up in the air for me, and as such it isn't an entirely cohesive document. Some sections are missing important things, and others are basically just curated copy-pastes of key RFCs (partly due to those RFCs just being absolutely excellent). Some information is duplicated or scattered because a lot of key concepts are
pervasive and tangled, and I haven't figured out a better "normalization".
Still, I've progressed far enough that I'd really like to get some feedback on it! So... here it is! (rendered with my own bespoke rustdoc setup -- didn't want to setup rustbook)
Right now the current set of chapters are:
- Intro (What is Unsafe?)
- Data Layout
- Ownership and Lifetimes
- Uninitialized Memory
- Ownership-oriented resource management (RAII)
- Example: Implementing Vec
The first 4 chapters try to address cross-cutting topics. This seems particularly necessary as these problems are vaguely pervasive throughout everything.
The next 3 look at more focused problems in detail. I try to focus on how to get the job done in Safe Rust first, and then look at how Unsafe Rust lets you go the extra mile when Safe Rust isn't adequate.
The last chapter is a stub of a cumulative "bring it together" example.
I've purposefully excluded FFI and no_std because it seems like TRPL actually gives a totally sufficient coverage of the topics. There's nothing really subtle there.
Anyway, I'm most concerned about missing important information and existing misinformation. In particular the lifetimes section is pretty technical, and my treatment of it is pretty... experimental. But really, the most important reason is that I know a bunch of you have a long plane trip with plenty of reading time ahead of you! I'll be waiting on the other end