Skip to content

gh-145921: Clarify return value of tp_traverse - #160455

Merged
encukou merged 3 commits into
python:mainfrom
encukou:tp_traverse-retval
Oct 28, 2026
Merged

gh-145921: Clarify return value of tp_traverse#160455
encukou merged 3 commits into
python:mainfrom
encukou:tp_traverse-retval

Conversation

@encukou

@encukou encukou commented Oct 23, 2026 •
edited by bedevere-app Bot
Loading

Copy link
Copy Markdown
Member

@encukou
encukou requested a review from nascheme October 23, 2026 17:49
@bedevere-app bedevere-app Bot added awaiting core review type-feature A feature request or enhancement labels Oct 23, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Oct 23, 2026
Closed
@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels Oct 23, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Oct 23, 2026
@read-the-docs-community

read-the-docs-community Bot commented Oct 23, 2026 •
edited
Loading

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35367398 | 📁 Comparing c8f1f2a against main (8d11920)

  🔍 Preview build  

17 files changed · ± 17 modified

± Modified

nascheme
nascheme approved these changes Oct 23, 2026
View reviewed changes

@nascheme nascheme 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.

LTGM aside from the "unreachable" wording.

Comment thread Doc/c-api/gcsupport.rst Outdated

If an error occurs during traversal, ignore it and return 0.
If ``tp_traverse`` fails to visit some strong references, objects
may become unreachable and waste memory, but correctness won't be affected.

@nascheme nascheme Oct 23, 2026

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.

I would say something like "garbage reference cycles will not be broken and the program may waste memory". If you want to use to word "unreachable", I would say something like "the GC will not reliability determine which objects are unreachable and are only alive due to circular references"

@nascheme nascheme Oct 23, 2026

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.

Or maybe more precisely "garbage reference cycles involving the skipped strong references will not be reliably broken". I think that's accurate. The GC will still be able to break up cyclic garbage involving the working tp_traverse methods (i.e. one failing tp_traverse doesn't prevent the cyclic GC from functioning entirely, which could be wrongly inferred). OTOH, maybe we want to be careful about promising too much. As the GC is now, it's true that other garbage reference cycles can be broken, even in the face of some tp_traverse methods not revealing all strong references. But maybe that's too strong of a promise.

@encukou encukou Oct 23, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

I think we can guarantee that. If one incorrect tp_traverse could gum up the entire garbage collector, we'd have a big problem.
Also, “involving” isn't a very precise term...

@encukou encukou added needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Oct 28, 2026
@encukou
encukou merged commit cfe7e0a into python:main Oct 28, 2026
33 of 34 checks passed
@encukou
encukou deleted the tp_traverse-retval branch October 28, 2026 14:49
@miss-islington-app

miss-islington-app Bot commented Oct 28, 2026

Copy link
Copy Markdown

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

@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Oct 28, 2026
@miss-islington-app

miss-islington-app Bot commented Oct 28, 2026

Copy link
Copy Markdown

Sorry, @encukou, I could not cleanly backport this to 3.14 due to a conflict.

Please backport manually with cherry_picker, see the devguide for more information.

cherry_picker cfe7e0a5ea5043991492ee71a8c6a322172b353a 3.14

@bedevere-app

bedevere-app Bot commented Oct 28, 2026

Copy link
Copy Markdown

GH-160826 is a backport of this pull request to the 3.15 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Oct 28, 2026
encukou added a commit that referenced this pull request Oct 28, 2026
@miss-islington @encukou
[3.15] gh-145921: Clarify return value of tp_traverse (GH-160455) (GH…
a6616f2 
…-160826)

(cherry picked from commit cfe7e0a)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nascheme nascheme nascheme approved these changes
@ZeroIntensity ZeroIntensity Awaiting requested review from ZeroIntensity ZeroIntensity is a code owner

Assignees

@encukou encukou

Labels

docs Documentation in the Doc dir needs backport to 3.14 bugs and security fixes skip news type-feature A feature request or enhancement

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@encukou @nascheme