search

rust-lang / nomicon

The Dark Arts of Advanced and Unsafe Rust Programming
https://doc.rust-lang.org/nomicon/
Apache License 2.0
1.79k stars 261 forks source link

Suggestion: Adding/linking to my explanation of Send/Sync? #267

Closed nyanpasu64 closed 3 years ago

nyanpasu64 commented 3 years ago

I noticed that the published Nomicon website (link) doesn't explain what can be Send/Sync or not, instead containing a TODO comment. An example actually has been added to the repo (link), but it hasn't been published to the website, sadly.

A few months ago I wrote a blog post (link) explaining Send/Sync from my perspective, giving examples of why standard library types (&, &mut, Cell-like, Rc, Arc, MutexGuard) have the trait bounds they have. I'm not sure whether it's appropriate to adapt and incorporate it to the Nomicon, link it as a footnote, or if the maintainers don't want to accept it either way.

One potential style issue is that there's too many headers with large font sizes splitting up the document, and the organization is suboptimal.

JohnTitor commented 3 years ago

Note that you should check the nightly doc for the latest changes: https://doc.rust-lang.org/nightly/nomicon/send-and-sync.html And I'd prefer that the nomicon itself tries to document everything on itself. If it's a sub-topic, I think it's fine to add a link but your post seems to document "Send and Sync" itself. If something is missing here, please point out that with a new issue. Thanks for the suggestion, though!

nyanpasu64 commented 2 years ago

I just noticed that the Nomicon actually mentions Arc's bounds in the Arc chapter, but not the Send/Sync chapter. Is it a good idea to add a link in the Send/Sync chapter pointing to Arc (perhaps in the "Major exceptions include" bullets, or in the "Example" section)?

Another specific criticism is that the Send/Sync chapter doesn't mention why both &mut T requires Send like T does, making them equivalent AFAIK for thread-safety (because &mut T allows you to swap the target with a local-variable T and then drop your local variable). (If they're not equivalent, let me know and I'll have to update my blog post :crying_cat_face:)