◐ Shell
reader mode source ↗
Skip to content

gh-123152: Add a Concurrency Howto Page#123163

Draft
ericsnowcurrently wants to merge 81 commits into
python:mainfrom
ericsnowcurrently:concurrency-howto
Draft

gh-123152: Add a Concurrency Howto Page#123163
ericsnowcurrently wants to merge 81 commits into
python:mainfrom
ericsnowcurrently:concurrency-howto

Conversation

@ericsnowcurrently

@ericsnowcurrently ericsnowcurrently commented Aug 19, 2024 •
edited
Loading

Copy link
Copy Markdown
Member

There's still a lot to do, but this mostly has the structure and content I have in mind. My personal objective is to show people what realistic code using the different concurrency models looks like (especially subinterpreters), with the ultimate destination being the side-by-side examples. To me, everything else sets the stage for that. However, I recognize that the value of this doc for users extends beyond my own motivations. 😄

This change includes:

  • the actual doc page
  • a new Doc/includes/concurrency directory where the .py file are stored
  • one .py file for each full example implementation
  • one .py file to hold the chunks of example code (grep-parts.py)
  • a script to run all the example code (run-examples.py)

There are some (tricky?) formatting things I've done:

  • CSS to vertical-align (top) table cells
  • |-prefixed text to manage table cell widths
  • HTML <details> tags for collapsible sections around long code samples
  • <details> in table cells for compact side-by-side code comparisons
  • <br/> tags and ---- dividers to make some sections more distinct
  • limit lines for side-by-side examples to ~60 characters, to ensure the table (usually) fits on the screen when 2 implementations are expanded

Still incomplete:

  • make the "complexity" comparison table more human-friendly?
  • the "Tracing execution" section under "Critical caveats" (possible text is hidden)
  • pretty much all of "Designing A Program For Concurrency" (possible text is hidden)
  • the whole "Python Concurrency Primitives" section
  • grep: steps 4 & 5 of the design/analysis section
  • grep: the list of things we don't do in the example code
  • grep: the "Model-specific details" section
  • grep; async example needs concurrent file read
  • workload example 2 missing
  • workload example 3 missing

Open questions:

  • reduce exposition?
  • move the "Python Concurrency Workload Examples" section to its own doc?
  • drop the "Python Concurrency Primitives" section?
  • reduce the "Designing A Program For Concurrency" section--make it less significant?
  • add a separate tutorial? (probably not)
  • don't mention "distributed" at all?

📚 Documentation preview 📚: https://cpython-previews--123163.org.readthedocs.build/

@bedevere-app bedevere-app Bot mentioned this pull request Aug 19, 2024
Open
@ericsnowcurrently ericsnowcurrently force-pushed the concurrency-howto branch 2 times, most recently from e3fb944 to 1e9ccf6 Compare August 20, 2024 17:12
75 hidden items Load more…
facundobatista
facundobatista reviewed Oct 13, 2024
View reviewed changes

@facundobatista facundobatista left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

Hey! Great work! Added some comments in the doc itself. Thanks for this!

@ericsnowcurrently

ericsnowcurrently commented Oct 15, 2024

Copy link
Copy Markdown
Member Author

Thanks for the feedback, @facundobatista. I'll try to get to it in the next few days.

@AA-Turner

AA-Turner commented Apr 29, 2025

Copy link
Copy Markdown
Member

@ericsnowcurrently is this in a mergeable state, or one where we can iterate on it later?

A

@AA-Turner AA-Turner added the docs Documentation in the Doc dir label Apr 29, 2025
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Apr 29, 2025
@ericsnowcurrently

ericsnowcurrently commented Apr 29, 2025

Copy link
Copy Markdown
Member Author

It's still a bit of a mess, unfortunately. I'm going to circle back to it at the PyCon sprints.

@AA-Turner

AA-Turner commented Apr 29, 2025

Copy link
Copy Markdown
Member

Let me know if I can offer any help, I think getting some or all of this merged would be useful, even if it takes a series of PRs. I won't be at PyCon unfortunatley -- couldn't make the dates work.

A

@github-actions

github-actions Bot commented Apr 18, 2026

Copy link
Copy Markdown

This PR is stale because it has been open for 30 days with no activity.

@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@facundobatista facundobatista facundobatista left review comments

@savannahostrowski savannahostrowski

@Eclips4 Eclips4 Eclips4 left review comments

@gpshead gpshead Awaiting requested review from gpshead gpshead will be requested when the pull request is marked ready for review gpshead is a code owner

@1st1 1st1 Awaiting requested review from 1st1 1st1 will be requested when the pull request is marked ready for review 1st1 is a code owner

@asvetlov asvetlov Awaiting requested review from asvetlov asvetlov will be requested when the pull request is marked ready for review

@kumaraditya303 kumaraditya303 Awaiting requested review from kumaraditya303 kumaraditya303 will be requested when the pull request is marked ready for review kumaraditya303 is a code owner

@willingc willingc Awaiting requested review from willingc willingc will be requested when the pull request is marked ready for review willingc is a code owner

@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner will be requested when the pull request is marked ready for review AA-Turner is a code owner

+1 more reviewer

@tonybaloney tonybaloney tonybaloney left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

docs Documentation in the Doc dir stale Stale PR or inactive for long period of time.

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@ericsnowcurrently @AA-Turner @facundobatista @tonybaloney @savannahostrowski @Eclips4