Skip to content

Commit

Permalink
reword reference management paragraph
Browse files Browse the repository at this point in the history
  • Loading branch information
iritkatriel committed Oct 27, 2023
1 parent d95b882 commit 9cd58b9
Showing 1 changed file with 14 additions and 5 deletions.
19 changes: 14 additions & 5 deletions peps/pep-0733.rst
Original file line number Diff line number Diff line change
Expand Up @@ -366,17 +366,26 @@ different memory management schemes
Object Reference Management
---------------------------

There are C API functions that return borrowed references, and
functions that decref arguments, but there isn't a
naming convention that makes this obvious, so this is error prone
There does not exist a consistent naming convention for functions
which makes their reference semantics obvious, and this leads to
error prone C API functions, where they do not follow the typical
behaviour. When a C API function returns a ``PyObject*``, the
caller typically gains ownership of a reference to the object.
However, there are exceptions where a function returns a
"borrowed" reference, which the caller can access but does not own
a reference to. Similarly, functions typically do not change the
ownership of references to their arguments, but there are
exceptions where a function "steals" a reference, i.e., the
ownership of the reference is permanently transferred from the
caller to the callee by the call
[`Issue 8 <https://github.com/capi-workgroup/problems/issues/8>`__
and `Issue 52 <https://github.com/capi-workgroup/problems/issues/52>`__].
The terminology used to describe these situations in the documentation
can also be improved
[`Issue 11 <https://github.com/capi-workgroup/problems/issues/11>`__].

A more radical change is necessary in the case of a function that
returns a ``PyObject*`` that it did not incref (such as ``PyList_GetItem``)
A more radical change is necessary in the case of functions that
return "borrowed" references (such as ``PyList_GetItem``)
[`Issue 5 <https://github.com/capi-workgroup/problems/issues/5>`__ and
`Issue 21 <https://github.com/capi-workgroup/problems/issues/21>`__]
or pointers to parts of the internal structure of an object
Expand Down

0 comments on commit 9cd58b9

Please sign in to comment.