docs: improved reference_internal documentation #5528
Merged
Conversation
This file contains 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
Improved the wording to make it easier to understand and added a note about the policy falling back to move if the return value is not an lvalue reference or pointer.
|
The test failure is unrelated to changes I made |
rwgk
reviewed
Feb 20, 2025
docs/advanced/functions.rst
Outdated
| | :enum:`return_value_policy::reference_internal` | If the return value is an lvalue reference or a pointer, the parent object | | ||
| | | (the implicit ``this``, or ``self`` argument of the called method or | | ||
| | | property) is kept alive for at least the lifespan of the return value. | | ||
| | | Otherwise this policy falls back to the policy | |
There was a problem hiding this comment.
That's a great and much needed clarification!
What do you think about:
- Making the "Otherwise ..." sentence bold, and ending it with "
(see #5528)."
?
|
I considered adding a line pointing out that keep_alive doesn't work when explicitly passed to the def_property methods because that is the users natural next response but it felt beyond the scope of it. |
rwgk
approved these changes
Feb 20, 2025
There was a problem hiding this comment.
Thanks @gentlegiantJGC!
Sorry I'm too busy right now to carefully think about your ideas for a more ambitious fix. I'll merge this, it's definitely useful!
henryiii
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Description
The documentation for the reference_internal return policy implies that
py::keep_alive<0, 1>()is always applied but this isn't true.There is quite a bit of confusion about the reference_internal return policy (myself included) stemming from this documentation.
Here are the related issues I have found.
#1764
#2618
#4124
#4236
#5046
These changes:
As documented thoroughtly in #4236 and #5046 the
def_propertyfamily does not honor thekeep_aliveargument passed to it and #2618 also mentions it does not honor thecall_guardargument. I think these issues should be fixed but should it be documented here until it is? The workaround is to usecpp_functionand add those arguments there.Fixes #1764
Fixes #2618
Fixes #4124
Suggested changelog entry:
Improved ``reference_internal`` policy documentation