gh-124379: Document _PyStackRef #142321
Open
gh-124379: Document _PyStackRef #142321
+81
−7
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Fidget-Spinner
approved these changes
Dec 5, 2025
Member
Fidget-Spinner
left a comment
Fidget-Spinner
left a comment
There was a problem hiding this comment.
This LGTM. Could you also please take a look at #141675 ? If that goes in, then some of the docs will go out of date as we won't be using different tagging schemes anymore.
mpage
reviewed
Dec 5, 2025
Contributor
mpage
left a comment
mpage
left a comment
There was a problem hiding this comment.
LGTM, just some suggestions inline
| Going back to `PyObject*` mirrors this: | ||
|
|
||
| - `PyStackRef_AsPyObjectBorrow(ref)` - borrow the underlying pointer | ||
| - `PyStackRef_AsPyObjectSteal(ref)` - transfer ownership from the stackref |
Contributor
There was a problem hiding this comment.
If ref is borrowed/deferred this will create a new owning reference. Not sure it's worth documenting, but I figured I'd call it out since this is not exactly the dual of PyStackRef_FromPyObjectSteal.
| Objects that support deferred reference counting can be pushed to the evaluation | ||
| stack and stored in local variables without directly incrementing the reference | ||
| count because they are only freed during cyclic garbage collection. This avoids | ||
| reference count contention on short-lived values such as methods and types. The GC |
Contributor
There was a problem hiding this comment.
This is confusing to me because methods and types tend to be long-lived.
Suggested change
| reference count contention on short-lived values such as methods and types. The GC | |
| reference count contention on commonly shared objects such as methods and types. The GC |
|
|
||
| In GIL builds, most objects carry their refcount; tagged borrowed refs skip decref on close. In free | ||
| threading builds, the tag is also used to mark deferred refcounted objects so the GC can see them and | ||
| to avoid refcount contention for short-lived stack values. |
Contributor
There was a problem hiding this comment.
I'm probably misreading this as it's written (it's Friday afternoon) but the following is clearer to me
Suggested change
| to avoid refcount contention for short-lived stack values. | |
| to avoid refcount contention on commonly shared objects. |
Comment on lines
+10
to
+12
| - `Py_TAG_REFCNT` clear - reference count lives on the pointed-to object. | ||
| - `Py_TAG_REFCNT` set - ownership is "borrowed" (no refcount to drop on close) or the object is immortal. | ||
| - `Py_INT_TAG` - tagged small integer stored directly in the stackref (no heap allocation). |
Contributor
There was a problem hiding this comment.
Suggested change
| - `Py_TAG_REFCNT` clear - reference count lives on the pointed-to object. | |
| - `Py_TAG_REFCNT` set - ownership is "borrowed" (no refcount to drop on close) or the object is immortal. | |
| - `Py_INT_TAG` - tagged small integer stored directly in the stackref (no heap allocation). | |
| - `Py_TAG_REFCNT` unset - reference count lives on the pointed-to object. | |
| - `Py_TAG_REFCNT` set - ownership is "borrowed" (no refcount to drop on close) or the object is immortal. | |
| - `Py_INT_TAG` set - tagged small integer stored directly in the stackref (no heap allocation). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.