The Dark Arts of Advanced and Unsafe Rust Programming
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Simon Mazur 3e25f93084
docs: anchors fixes
8 years ago
.gitignore blurp 8 years ago
LICENSE-APACHE first commit 8 years ago
LICENSE-MIT first commit 8 years ago
README.md rename TARPL to The Rustinomicon 8 years ago
SUMMARY.md fix title-casing 8 years ago
arc-and-mutex.md nits and realigning 8 years ago
atomics.md Reverse AtomicBool value in nomicon example to agree with its comment. 8 years ago
borrow-splitting.md fix code and error to match the surronding text 8 years ago
casts.md frob emphasis 8 years ago
checked-uninit.md frob emphasis 8 years ago
coercions.md nomicon: use current syntax 8 years ago
concurrency.md Fix some grammar in The Advanced Rust Programming Language 8 years ago
constructors.md frob emphasis 8 years ago
conversions.md frob emphasis 8 years ago
data.md frob emphasis 8 years ago
destructors.md Nomicon: Fix Links 8 years ago
dot-operator.md SHARD ALL THE CHAPTERS 8 years ago
drop-flags.md Fix some grammar in The Advanced Rust Programming Language 8 years ago
dropck.md Fix some grammar in The Advanced Rust Programming Language 8 years ago
exception-safety.md frob emphasis 8 years ago
exotic-sizes.md Revise TARPL's description for allocating 0 bytes 8 years ago
hrtb.md frob emphasis 8 years ago
leaking.md Remove superfluous line from Nomicon 8 years ago
lifetime-elision.md fix all the doc tests 8 years ago
lifetime-mismatch.md docs: anchors fixes 8 years ago
lifetimes.md Remove reference to diabetes 8 years ago
meet-safe-and-unsafe.md Nomicon: Fix Links 8 years ago
obrm.md OBRM for aturon 8 years ago
other-reprs.md Nomicon: Fix Links 8 years ago
ownership.md frob emphasis 8 years ago
phantom-data.md frob emphasis 8 years ago
poisoning.md frob emphasis 8 years ago
races.md last of the emphasis cleanup 8 years ago
references.md add warning about reference section 8 years ago
repr-rust.md docs: anchors fixes 8 years ago
safe-unsafe-meaning.md Nomicon: Fix Links 8 years ago
send-and-sync.md Nomicon: Fix Links 8 years ago
subtyping.md Fix variance ordering 8 years ago
transmutes.md Nomicon: Fix Links 8 years ago
unbounded-lifetimes.md fix all the doc tests 8 years ago
unchecked-uninit.md Fix some grammar in The Advanced Rust Programming Language 8 years ago
uninitialized.md SHARD ALL THE CHAPTERS 8 years ago
unwinding.md last of the emphasis cleanup 8 years ago
vec-alloc.md std: Internalize almost all of `std::rt` 8 years ago
vec-dealloc.md clean up vec chapter of tarpl 8 years ago
vec-deref.md clean up vec chapter of tarpl 8 years ago
vec-drain.md Rustonomicon: Reword potentially confusing comment in Vec::drain. 8 years ago
vec-final.md std: Internalize almost all of `std::rt` 8 years ago
vec-insert-remove.md last of the emphasis cleanup 8 years ago
vec-into-iter.md last of the emphasis cleanup 8 years ago
vec-layout.md fix example code 8 years ago
vec-push-pop.md last of the emphasis cleanup 8 years ago
vec-raw.md vec fixes for huonw 8 years ago
vec-zsts.md last of the emphasis cleanup 8 years ago
vec.md vec fixes for huonw 8 years ago
working-with-unsafe.md many many pnkfelix fixes 8 years ago

README.md

% The Rustonomicon

The Dark Arts of Advanced and Unsafe Rust Programming

NOTE: This is a draft document, and may contain serious errors

Instead of the programs I had hoped for, there came only a shuddering blackness and ineffable loneliness; and I saw at last a fearful truth which no one had ever dared to breathe before — the unwhisperable secret of secrets — The fact that this language of stone and stridor is not a sentient perpetuation of Rust as London is of Old London and Paris of Old Paris, but that it is in fact quite unsafe, its sprawling body imperfectly embalmed and infested with queer animate things which have nothing to do with it as it was in compilation.

This book digs into all the awful details that are necessary to understand in order to write correct Unsafe Rust programs. Due to the nature of this problem, it may lead to unleashing untold horrors that shatter your psyche into a billion infinitesimal fragments of despair.

Should you wish a long and happy career of writing Rust programs, you should turn back now and forget you ever saw this book. It is not necessary. However if you intend to write unsafe code -- or just want to dig into the guts of the language -- this book contains invaluable information.

Unlike The Book we will be assuming considerable prior knowledge. In particular, you should be comfortable with basic systems programming and Rust. If you don't feel comfortable with these topics, you should consider reading The Book first. Though we will not be assuming that you have, and will take care to occasionally give a refresher on the basics where appropriate. You can skip straight to this book if you want; just know that we won't be explaining everything from the ground up.

To be clear, this book goes into deep detail. We're going to dig into exception-safety, pointer aliasing, memory models, and even some type-theory. We will also be spending a lot of time talking about the different kinds of safety and guarantees.