Skip to content

Fix Queue.shutdown docs for condition to unblock a join #137088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 2 commits into from
Jul 25, 2025
Merged

Fix Queue.shutdown docs for condition to unblock a join #137088

merged 2 commits into from
Jul 25, 2025
+18 −12

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

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

@miss-islington-app
Copy link

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)
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 needs backport to 3.14 bugs and security fixes skip issue skip news
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@rhettinger @serhiy-storchaka
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy