rust-lang / rust-lang/book

Chapter 16.3: is a microphone at a panel a good analogy?

Open
#4,530 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
18.3k
Forks
4.1k
Avg merge
14m
Merged PRs (30d)
1

Description

  • I have searched open and closed issues and pull requests for duplicates, using these search terms:
    • microphone
  • I have checked the latest main branch to see if this has already been fixed, in this file:
    • src/ch16-03-shared-state.md

URL to the section(s) of the book with this problem: https://doc.rust-lang.org/book/ch16-03-shared-state.html

The introduction of this chapter uses this analogy:

For a real-world metaphor for a mutex, imagine a panel discussion at a conference with only one microphone. Before a panelist can speak, they have to ask or signal that they want to use the microphone. When they get the microphone, they can talk for as long as they want to and then hand the microphone to the next panelist who requests to speak. If a panelist forgets to hand the microphone off when they’re finished with it, no one else is able to speak. If management of the shared microphone goes wrong, the panel won’t work as planned!

In my opinion this is a pretty bad analogy. Here are some reasons why:

  • In real world conferences where there's a panel discussion, each panelist would usually have their own microphone. And they can often speak at the same time, for better or worse.
  • If a panelist forgets to hand off the microphone, the other panelists can easily remind them to do so or request it, which isn't a realistic possibility with a mutex.
  • Two panelists absolutely can share a microphone, and it's quite common to place a stationary microphone between two panelists to reduce the number of microphones on stage.

Some options I thought of for a different analogy:

An old-school phone booth: only one person can practically use it at any one time, and while they're using it the door is closed preventing others from entering. When they are finished using it, they have no choice but to leave the booth, freeing it up for other people.

Questions after a presentation: steering closer to the conference metaphor, we could discuss the questions at the end, which I think is a far more accurate analogy. When a presentation ends, audience members have a chance to ask questions, and they raise their hand to indicate they want to do so. A staff member selects one, gives them a wireless microphone, and they ask their question and receive an answer. Afterwards the staff member takes the microphone away and selects a new audience member.

The audience members are threads, the microphone is the shared resource, and the staff member handing off the microphone is the mutex.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read src/ch16-03-shared-state.md and compare the mutex introduction with the linked book section. Evaluate the existing microphone analogy and the alternatives described in the issue, then update the section only after choosing a clearer analogy. Done means the revised explanation accurately communicates mutex ownership and reads naturally in the surrounding chapter.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.