Skip to content

Conversation

borsakv
Copy link
Member

@borsakv borsakv commented Sep 14, 2025

cc @joshtriplett

Explanation:
After analyzing the FLS, I found that there were various chapters within the FLS that are missing from the Rust Reference. Most of the information in the said chapters was present in the Reference, just scattered. However, the information from the Concurrency Chapter in the FLS seemed to be missing almost entirely, due to this I wrote the named Concurrency chapter with the help of @joshtriplett under the Rust 2025H2 Reference Expansion Goal.

I believe this chapter covers stable concepts that will not change often and is an important addition for Rust users to reference when they are working with concurrency.

Changes:
Added the initial proposal of the Concurrency Chapter with the following subheadings:

  • Send and Sync
  • Atomics
  • Asynchronous Computation

Also added new entries to the Glossary:

  • Atomic types
  • Data race
  • Marker trait

@rustbot rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Sep 14, 2025
@traviscross
Copy link
Contributor

traviscross commented Sep 24, 2025

Thanks for your efforts on this chapter.

@ehuss and I reviewed and talked about this chapter today. Tough one. There's a lot of good here. And it's good to cover places where the FLS has a chapter but the Reference doesn't.

At the same time, there are some questions and challenges here. The section on "combining async and unsafe" probably just needs to be deleted -- this is covered elsewhere in the Reference -- and this may be true of some of the other content.

That said, I realize what this chapter may be trying to do is to "put things in one place". There may be some merit in that, but in that same way, this chapter reads in places a bit like a tutorial rather than Reference material.

Similarly, one of the longstanding questions we've had on the Reference is how much of the standard library documentation we want to duplicate, in what cases we should do that, how to go about it, etc. In its coverage of Send, Sync`, atomics, etc., this chapter dives right into that challenge.

Probably I question whether the async bits belong in the same chapter as the discussion of Send, Sync, atomics, etc., in the sense that parallelism and concurrency are rather different.

There's a lot more to untangle here, but the main point we want to get across is this meta one:

It'd probably be better if you were to have a conversation with us first before writing a chapter like this about how to approach it. Maybe file an issue here with an outline of what you have in mind or open a thread on our Zulip channel and ping us. That's likely to be more efficient than trying to work out, with a full chapter here in front of us, what can be accepted and what maybe-substantial changes will need to be made to the rest.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-review Status: The marked PR is awaiting review from a maintainer
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants