classification
Title: Docs on reference count detail. enhancement.
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bombs-kim, docs@python, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2018-12-17 04:45 by bombs-kim, last changed 2018-12-22 21:24 by cheryl.sabella.

Pull Requests
URL Status Linked Edit
PR 11277 open cheryl.sabella, 2018-12-22 21:24
Messages (1)
msg331946 - (view) Author: bombs (bombs-kim) * Date: 2018-12-17 04:45
https://docs.python.org/3/c-api/intro.html#reference-count-details

When I read that section of the docs first time, I found it hard to grasp what transferring of ownership is, which is an important and repeating concept throughout the docs. Some explanations were confusing. For example,

> When a function passes ownership of a reference on to its caller, the
> caller is said to receive a new reference

This part tries to explain what is to receive a new reference, in terms of passing ownership, when readers have no ideas of what transferring of ownership is. I think it is kind of a circular definition fallacy.

I think this section should've explained transferring of ownership, a high level concept, in terms of reference count changes, which are concrete operations.


(original version)
When a function passes ownership of a reference on to its caller, the caller is said to receive a new reference. When no ownership is transferred, the caller is said to borrow the reference. Nothing needs to be done for a borrowed reference.
Conversely, when a calling function passes in a reference to an object, there are two possibilities: the function steals a reference to the object, or it does not. Stealing a reference means that when you pass a reference to a function, that function assumes that it now owns that reference, and you are not responsible for it any longer.

(revision)
When a function returns an object and effectively increases the reference count of it, the function is said to give ownership of a new reference to its caller. When a function returns an object without changing the reference count of it, the caller is said to borrow the reference. Nothing needs to be done for a borrowed reference.
Conversely, if a function decreases the reference count of an object, it is said to steal the ownership of the reference from its owner. Stealing a reference means that when you pass a reference to a stealing function, that function assumes that it now owns that reference, and you are not responsible for it any longer.
History
Date User Action Args
2018-12-22 21:24:11cheryl.sabellasetkeywords: + patch
stage: patch review
pull_requests: + pull_request10518
2018-12-21 21:44:11terry.reedysetnosy: + serhiy.storchaka
2018-12-17 04:45:31bombs-kimcreate