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 Queue.shutdown docs for condition to unblock a join#137088

Merged
rhettinger merged 2 commits intopython:mainpython/cpython:mainfrom
rhettinger:shutdown_docs_fixrhettinger/cpython:shutdown_docs_fixCopy head branch name to clipboard
Jul 25, 2025
Merged

Fix Queue.shutdown docs for condition to unblock a join#137088
rhettinger merged 2 commits intopython:mainpython/cpython:mainfrom
rhettinger:shutdown_docs_fixrhettinger/cpython:shutdown_docs_fixCopy head branch name to clipboard

Conversation

@rhettinger
Copy link
Contributor

@rhettinger rhettinger commented Jul 24, 2025 •
edited by github-actions bot
Loading

I missed this before. A hard shutdown only unblocks a join if all previous gets had a corresponding task_done.

Demonstration:

from threading import Thread
from queue import Queue
from time import sleep
from random import random
    
q = Queue()

def all_done():
    print('Waiting')
    q.join()
    print('All tasks finished')

# Load two tasks
q.put(0)
q.put(1)

# Wait for them to finish
Thread(target=all_done).start()
sleep(1)

# One task fetched and completed
print('Working on one task')
q.get()
if random() < 0.5:
    print('Finished one task')
    q.task_done()                     

# One task remains unfetched. One or two remain unfinished.
print(f'Pre shutdown: {q.qsize()=} {q.unfinished_tasks=}')

# Hard shutdown fetchs and decrements unfinished
q.shutdown(immediate=True)
sleep(1)
print(f'Post shutdown: {q.qsize()=} {q.unfinished_tasks=}')

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

@rhettinger rhettinger added docs Documentation in the Doc dir skip issue skip news needs backport to 3.13 bugs and security fixes labels Jul 24, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Jul 24, 2025
@rhettinger rhettinger added the needs backport to 3.14 bugs and security fixes label Jul 24, 2025
serhiy-storchaka
serhiy-storchaka reviewed Jul 25, 2025
View reviewed changes
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.

Confirmed.

Maybe update also the documentation for Queue.join()? It says when the count of unfinished tasks goes up or down. Since the claim that shutdown(immediate=True) calls task_done() was removed (as not literally correct), this no longer covers all cases.

@serhiy-storchaka serhiy-storchaka removed their assignment Jul 25, 2025
@rhettinger rhettinger merged commit ea06ae5 into python:main Jul 25, 2025
41 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Jul 25, 2025
@miss-islington-app
Copy link

miss-islington-app bot commented Jul 25, 2025

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

@miss-islington-app
Copy link

miss-islington-app bot commented Jul 25, 2025

Sorry, @rhettinger, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker ea06ae5b5e7b335efbdff03c087fad9980a53f69 3.14

@rhettinger rhettinger deleted the shutdown_docs_fix branch July 25, 2025 13:56
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 25, 2025
@rhettinger @miss-islington
Fix Queue.shutdown docs for condition to unblock a join (pythongh-137088
52ca647 
)

(cherry picked from commit ea06ae5)

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

bedevere-app bot commented Jul 25, 2025

GH-137102 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 25, 2025
rhettinger pushed a commit that referenced this pull request Jul 25, 2025
@miss-islington
[3.13] Fix Queue.shutdown docs for condition to unblock a join (gh-13…
eda6134 
…7088) (gh-137102)
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
@rhettinger @taegyunkim
Fix Queue.shutdown docs for condition to unblock a join (pythongh-137088
901ee57 
)
@serhiy-storchaka
Copy link
Member

serhiy-storchaka commented Aug 14, 2025

Reminder about backporting. @rhettinger

Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
@rhettinger @Agent-Hellboy
Fix Queue.shutdown docs for condition to unblock a join (pythongh-137088
7a9d851 
)
StanFromIreland pushed a commit to StanFromIreland/cpython that referenced this pull request Nov 5, 2025
@rhettinger @StanFromIreland
[3.14] Fix Queue.shutdown docs for condition to unblock a join (pytho…
cfbe774 
…ngh-137088)

(cherry picked from commit ea06ae5)

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

bedevere-app bot commented Nov 5, 2025

GH-141073 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 Nov 5, 2025
@StanFromIreland
Copy link
Member

StanFromIreland commented Nov 5, 2025

Backports cleanly, created it.

kumaraditya303 pushed a commit that referenced this pull request Nov 6, 2025
@StanFromIreland @rhettinger
[3.14] Fix Queue.shutdown docs for condition to unblock a join (gh-13…
12847bf 
…7088) (#141073)

(cherry picked from commit ea06ae5)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@serhiy-storchaka serhiy-storchaka serhiy-storchaka left review comments

@1st1 1st1 Awaiting requested review from 1st1 1st1 is a code owner

@asvetlov asvetlov Awaiting requested review from asvetlov asvetlov is a code owner

@kumaraditya303 kumaraditya303 Awaiting requested review from kumaraditya303 kumaraditya303 is a code owner

@willingc willingc Awaiting requested review from willingc willingc is a code owner

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip issue skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@rhettinger @serhiy-storchaka @StanFromIreland
Morty Proxy This is a proxified and sanitized view of the page, visit original site.