Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Fix docs for Queue.shutdown#137028

Merged
rhettinger merged 14 commits intopython:mainpython/cpython:mainfrom
rhettinger:shutdown_docsrhettinger/cpython:shutdown_docsCopy head branch name to clipboard
Jul 24, 2025
Merged

Fix docs for Queue.shutdown#137028
rhettinger merged 14 commits intopython:mainpython/cpython:mainfrom
rhettinger:shutdown_docsrhettinger/cpython:shutdown_docsCopy head branch name to clipboard

Conversation

@rhettinger
Copy link
Contributor

@rhettinger rhettinger commented Jul 23, 2025

Fix errors. Clarify ambiguities. Improve presentation. Add cautionary note.

  • Removed incorrect note in the task_done docs. That method is not called by shutdown.
  • Separate the discussions of the normal case (the default) and the immediate case.
  • For the normal case, note that blocked callers of put will be unblocked but will also immediately raise 'ShutDown' in the formerly blocked thread.
  • For the normal case, note that get and task_done continue to operate normally except that a get on an empty queue will now raise ShutDown instead of Empty.
  • For the immediate case, present the actions in the order that they actually occur (drain the queue, reduce the unfinished tasks by the number drained, notify Queue.join waiters, notify get and put waiters.
  • For the immediate case, note that unfinished tasks is updated without calling task_done.
  • For the immediate case, note the Queue.join is unblocked even if the unfinished tasks are more than zero.
  • Add cautionary note about using Queue.join with immediate=True.

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

Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

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

Please update also the asyncio.queue documentation and the docstrings.

Doc/library/queue.rst Show resolved Hide resolved
Doc/library/queue.rst Show resolved Hide resolved
@serhiy-storchaka serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jul 23, 2025
Doc/library/queue.rst Show resolved Hide resolved
Doc/library/queue.rst Outdated Show resolved Hide resolved
@rhettinger
Copy link
Contributor Author

Please update also the asyncio.queue documentation and the docstrings.

I don't feel comfortable editing those docs (I don't use asyncio anymore). Someone else who knows the territory better can model an edit on this one.

@serhiy-storchaka
Copy link
Member

It is mostly just a copy of the queue.Queue documentation. It would be better to keep them in sync.

At least update the docstrings.

@rhettinger
Copy link
Contributor Author

Okay, I updated the asyncio docs to match. You were right, they were almost identical.

Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

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

Please update also the task_done docstrings, for both classes.

Doc/library/asyncio-queue.rst Outdated Show resolved Hide resolved
Doc/library/asyncio-queue.rst Outdated Show resolved Hide resolved
Doc/library/asyncio-queue.rst Outdated Show resolved Hide resolved
Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

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

LGTM. 👍

The queue can no longer grow.
Future calls to :meth:`~Queue.put` raise :exc:`QueueShutDown`.
Currently blocked callers of :meth:`~Queue.put` will be unblocked
and will raise :exc:`QueueShutDown` in the formerly blocked thread.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
and will raise :exc:`QueueShutDown` in the formerly blocked thread.
and will raise :exc:`QueueShutDown` in the formerly blocked tasks.

asyncio queues are not thread safe, they can only be used with tasks.

@rhettinger rhettinger merged commit 2456715 into python:main Jul 24, 2025
41 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Jul 24, 2025
@miss-islington-app
Copy link

Thanks @rhettinger for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

@rhettinger rhettinger deleted the shutdown_docs branch July 24, 2025 17:23
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 24, 2025
(cherry picked from commit 2456715)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 24, 2025
(cherry picked from commit 2456715)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
@bedevere-app
Copy link

bedevere-app bot commented Jul 24, 2025

GH-137080 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jul 24, 2025
@bedevere-app
Copy link

bedevere-app bot commented Jul 24, 2025

GH-137081 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jul 24, 2025
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
vstinner pushed a commit that referenced this pull request Oct 7, 2025
Fix docs for Queue.shutdown (gh-137028)
(cherry picked from commit 2456715)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
Co-authored-by: Zachary Ware <zach@python.org>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip issue skip news

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

4 participants

Morty Proxy This is a proxified and sanitized view of the page, visit original site.