Rewrote "How Safe and Unsafe Interact" Nomicon chapter. #33895

AndrewBrinker · May 27, 2016

The previous version of the chapter covered a lot of ground, but was a little meandering and hard to follow at times. This draft is intended to be clearer and more direct, while still providing the same information as the previous version.

r? @steveklabnik

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

rust-highfive · May 27, 2016

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

Here's the current version of the rewritten chapter, for convenience.

AndrewBrinker · May 27, 2016

Here's the current version of the rewritten chapter, for convenience.

pnkfelix · May 27, 2016

pnkfelix reviewed May 27, 2016

View changes

src/doc/nomicon/safe-unsafe-meaning.md

please squash

tshepang · May 31, 2016

please squash

Alright, I've squashed.

AndrewBrinker · Jun 1, 2016

Alright, I've squashed.

Hey, sorry for taking a while to review this. Will try to get to it tomorrow.

steveklabnik · Jun 6, 2016

Hey, sorry for taking a while to review this. Will try to get to it tomorrow.

No problem!

AndrewBrinker · Jun 7, 2016

No problem!

@AndrewBrinker so, since this is a pretty significant re-write, and it's hard to tell what's different and what's changed, I'm going to review this from the position of a brand-new chapter. Some of which, you inherited, of course :)

If you don't have the time/desire to make these kinds of tweaks, let me know, and we don't have to block the PR on them, but I might need your help in separating the past from the present, given the diff is so unhelpful here. 😄

steveklabnik · Jun 7, 2016

@AndrewBrinker so, since this is a pretty significant re-write, and it's hard to tell what's different and what's changed, I'm going to review this from the position of a brand-new chapter. Some of which, you inherited, of course :)

If you don't have the time/desire to make these kinds of tweaks, let me know, and we don't have to block the PR on them, but I might need your help in separating the past from the present, given the diff is so unhelpful here. 😄

steveklabnik · Jun 7, 2016

steveklabnik reviewed Jun 7, 2016

View changes

src/doc/nomicon/safe-unsafe-meaning.md

steveklabnik · Jun 7, 2016

steveklabnik reviewed Jun 7, 2016

View changes

src/doc/nomicon/safe-unsafe-meaning.md

steveklabnik · Jun 7, 2016

steveklabnik reviewed Jun 7, 2016

View changes

src/doc/nomicon/safe-unsafe-meaning.md

steveklabnik · Jun 7, 2016

steveklabnik reviewed Jun 7, 2016

View changes

src/doc/nomicon/safe-unsafe-meaning.md

I've rewritten the second paragraph to eliminate the FFI bits, and I think it's actually clearer now. I also made the smaller changes you suggested.

As far as what's different between this and the original, I'll start by noting that my goal with this was basically to reword and simplify the original, so there are a lot of similarities.

The first paragraph ("What's the relationship...") is the same in both versions.

The second paragraph in the new version ("The separation between...") is a combination of paragraphs 2 and 3 from the original, with the FFI stuff removed.

Paragraphs 3, 4, 5, and 6 in the new version ("The unsafe keyword..." to "There is also the...") are a rewording of paragraphs 4, 5, and 6 from the original. Paragraph 3, which is one sentence, describes the two uses of unsafe. Paragraphs 4 and 5 provide greater detail on the two uses, and paragraph 6 notes the one special case.

Paragraphs 7, 8, 9, and 10 in the new version ("The standard library has..." to "Send is a marker trait") are almost identical to paragraphs 7, 8, 9, and 10 in the original. They give examples of unsafe APIs in the standard and core libraries.

Paragraph 11 in the new version ("Much of the Rust standard library...") is pulled from paragraph 13 in the original. This just explains that the use of unsafe in the standard library isn't a cause for alarm.

Paragraphs 12 and 13 in the new version ("The need for all this..." and "No matter what...") are a rewording of paragraphs 11 and 12 in the original. These introduce probably the biggest point in the piece, the core idea that differentiates Safe Rust and Unsafe Rust: that Safe Rust can't cause undefined behavior.

Paragraphs 14-18 in the new version ("The design of the...") are a reworking of paragraphs 13-21 in the original. These provide greater detail about when to use unsafe, and how unsafe code must be written not to rely on safe code.

Paragraph 19 in the new version ("The decision of whether...") is a reworking of paragraphs 21-23 in the original. This tries to explain that use of unsafe is a design choice.

Paragraphs 20 and 21 in the new version are new, and not adapted from the original. Paragraph 20 clarifies how Send and Sync work, and paragraph 21 provides a small conclusion to the chapter.

Hope that helps!

AndrewBrinker · Jun 7, 2016