update 'unsafe' #1278

RalfJung · 2022-09-29T13:47:05Z

I started equipping this with some examples for the more subtle situations (in particular fn in an unsafe trait vs an unsafe fn in a safe trait), but then I realized we have https://doc.rust-lang.org/nightly/std/keyword.unsafe.html which looks like a better place for the examples. So now rust-lang/rust#102475 adds the examples and this here just updates the reference documentation and adds the missing parts (unsafe trait and unsafe impl).

ehuss

Thanks so much for adding this!

Since this is mostly new content, can you wrap the lines on sentences (aka semantic line breaks)? For example, it helps keep diffs cleaner instead of rewrapping lines. We've been trying to move more of the reference to this style. There is also a style guide which has some of our guidelines.

src/unsafe-keyword.md

ehuss · 2022-09-30T00:25:49Z

src/unsafe-keyword.md

+condition that the index must be in-bounds. The module defining an unsafe
+function is responsible for documenting what those extra safety conditions are.


This seems rather specific to say it must go in the module documentation. For example, the aforementioned get_unchecked is just documented on the method itself, not in the module docs. Can this be reworded to be a little more general?

I'm going to say that we should point out that this isn't an actual requirement of the language, but rather expected practice. There's nothing in rustc that will (or could) stop your code from compiling because you failed to explain what extra conditions you are imposing.

I didn't mean this to imply it must be the module-level docs, just 'somewhere inside the module'.

src/unsafe-keyword.md

ehuss · 2022-09-30T00:34:53Z

src/unsafe-keyword.md

+upheld by *implementations* of the trait. The module defining an unsafe trait is
+responsible for documenting what those extra safety conditions are.


Ditto about being specific about the docs being in the module.

I have adjusted the wording, please let me know what you think.

src/unsafe-keyword.md

Havvy · 2022-09-30T05:17:56Z

src/unsafe-keyword.md

+in the language but the implementation of threads and message passing in the
+standard library uses unsafe blocks.
+
+Rust's type system is a conservative approximation of the dynamic safety


Small wording quibble. Is it an approximation, or is it a subset?

(You can also just change "Rust's" to "The")

"conservative approximation" means subset or superset, depending on which direction is the safe one.

I didn't write this part, but I think I prefer "conservative approximation" over subset or superset, since with subset/superset it is often ambiguous what the polarity of the order is.

src/unsafe-keyword.md

RalfJung · 2022-09-30T07:17:53Z

can you wrap the lines on sentences

That's how I wrote it, in fact; I forgot that the reference is switching to my preferred style ;)

ehuss

Looks great, thanks!

Update books ## nomicon 1 commits in f53bfa056929217870a5d2df1366d2e7ba35096d..9c73283775466d22208a0b28afcab44db4c0cc10 2022-09-05 07:19:02 -0700 to 2022-09-30 07:31:22 +0900 - Fix typo (rust-lang/nomicon#380) ## reference 9 commits in a7cdac33ca7356ad49d5c2b5e2c5010889b33eee..f6ed74f582bddcec73f753eafaab3749c4f7df61 2022-09-19 17:39:58 -0700 to 2022-10-08 02:43:26 -0700 - Typo 'a' -> 'an' (rust-lang/reference#1280) - One line one sentence for expressions and statements main chapters (rust-lang/reference#1277) - Document let else statements (rust-lang/reference#1156) - Document `label_break_value` in the reference (rust-lang/reference#1263) - Document target_has_atomic (rust-lang/reference#1171) - update 'unsafe' (rust-lang/reference#1278) - Update tokens.md (rust-lang/reference#1276) - One sentence, one line Patterns chapter (rust-lang/reference#1275) - Use semver-compliant example version (rust-lang/reference#1272) ## rust-by-example 9 commits in 767a6bd9727a596d7cfdbaeee475e65b2670ea3a..5e7b296d6c345addbd748f242aae28c42555c015 2022-09-14 09:17:18 -0300 to 2022-10-05 08:24:45 -0300 - Make it clear that rustdoc uses the commonmark spec (rust-lang/rust-by-example#1622) - Update defaults.md (rust-lang/rust-by-example#1615) - added "see also" for the @ binding sigil (rust-lang/rust-by-example#1612) - add more precision to the effects of --bin flag (rust-lang/rust-by-example#1607) - create bar project in cargo/dependencies example (rust-lang/rust-by-example#1606) - use consistent wording about type annotation (rust-lang/rust-by-example#1603) - cast.md improvements (rust-lang/rust-by-example#1599) - Fix typo in macros.md (rust-lang/rust-by-example#1598) - Corrected mistaken "The" instead of "There" (rust-lang/rust-by-example#1617) ## rustc-dev-guide 2 commits in 9a86c0467bbe42056f73fdf5b03fff757d7c4a9b..7518c3445dc02df0d196f5f84e568d633c5141fb 2022-10-07 18:34:51 +0200 to 2022-10-08 12:29:47 +0200 - Update debugging.md - Use llvm subdomain for compiler-explorer link ## embedded-book 1 commits in 4ce51cb7441a6f02b5bf9b07b2eb755c21ab7954..c533348edd69f11a8f4225d633a05d7093fddbf3 2022-09-15 08:53:09 +0000 to 2022-10-10 10:16:49 +0000 - Fix a typo in registers.md (rust-embedded/book#330)

merge unsafe-block and unsafe-function into one page

f24b8d4

RalfJung force-pushed the unsafe branch from 33cd535 to 9c6de6d Compare September 29, 2022 14:12

ehuss reviewed Sep 30, 2022

View reviewed changes

Havvy reviewed Sep 30, 2022

View reviewed changes

src/unsafe-keyword.md Outdated Show resolved Hide resolved

update unsafe docs

1423936

RalfJung force-pushed the unsafe branch from 9c6de6d to 1423936 Compare September 30, 2022 09:03

apply feedback

d1e4ea1

RalfJung force-pushed the unsafe branch from 1dd4eea to d1e4ea1 Compare September 30, 2022 10:03

ehuss approved these changes Oct 3, 2022

View reviewed changes

ehuss merged commit b5ff71d into rust-lang:master Oct 3, 2022

RalfJung mentioned this pull request Oct 5, 2022

unsafe keyword: trait examples and unsafe_op_in_unsafe_fn update rust-lang/rust#102475

Merged

RalfJung deleted the unsafe branch October 7, 2022 08:35

ehuss mentioned this pull request Oct 11, 2022

Update books rust-lang/rust#102940

Merged

ehuss mentioned this pull request Jan 5, 2024

What to do with "unsafe functions"? #575

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update 'unsafe' #1278

update 'unsafe' #1278

RalfJung commented Sep 29, 2022

ehuss left a comment •

edited

Loading

ehuss Sep 30, 2022

Havvy Sep 30, 2022

RalfJung Sep 30, 2022

ehuss Sep 30, 2022

RalfJung Sep 30, 2022

Havvy Sep 30, 2022 •

edited

Loading

RalfJung Sep 30, 2022

RalfJung commented Sep 30, 2022

ehuss left a comment

		condition that the index must be in-bounds. The module defining an unsafe
		function is responsible for documenting what those extra safety conditions are.

		upheld by implementations of the trait. The module defining an unsafe trait is
		responsible for documenting what those extra safety conditions are.

update 'unsafe' #1278

update 'unsafe' #1278

Conversation

RalfJung commented Sep 29, 2022

ehuss left a comment • edited Loading

Choose a reason for hiding this comment

ehuss Sep 30, 2022

Choose a reason for hiding this comment

Havvy Sep 30, 2022

Choose a reason for hiding this comment

RalfJung Sep 30, 2022

Choose a reason for hiding this comment

ehuss Sep 30, 2022

Choose a reason for hiding this comment

RalfJung Sep 30, 2022

Choose a reason for hiding this comment

Havvy Sep 30, 2022 • edited Loading

Choose a reason for hiding this comment

RalfJung Sep 30, 2022

Choose a reason for hiding this comment

RalfJung commented Sep 30, 2022

ehuss left a comment

Choose a reason for hiding this comment

ehuss left a comment •

edited

Loading

Havvy Sep 30, 2022 •

edited

Loading