8000 borrowed references · adamtheturtle/pythoncapi@3708300 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3708300

Browse files
vstinnervstinner
committed
borrowed references
1 parent 51d6a91 commit 3708300

File tree

4 files changed

+53
-9
lines changed

4 files changed

+53
-9
lines changed

‎doc/bad_api.rst

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ See also :ref:`Remove functions <remove-funcs>`.
1515
Borrowed references
1616
===================
1717

18-
CPython 3.7 has 36 functions and macros which return borrowed references.
18+
CPython 3.7 has many functions and macros which return or use borrowed
19+
references. For example, ``PyTuple_GetItem()`` returns a borrowed reference,
20+
whereas ``PyTuple_SetItem()`` stores a borrowed reference (store an item into a
21+
tuple without increasing the reference counter).
1922

2023
CPython contains ``Doc/data/refcounts.dat`` (file is edited manually) which
2124
documents how functions handle reference count.
@@ -40,6 +43,7 @@ Functions
4043
* ``Py_InitModule4()``
4144
* ``PyImport_GetModuleDict()``
4245
* ``PyList_GetItem()``
46+
* ``PyList_SetItem()``
4347
* ``PyMethod_Class()``
4448
* ``PyMethod_Function()``
4549
* ``PyMethod_Self()``
@@ -50,20 +54,28 @@ Functions
5054
* ``PySys_GetXOptions()``
5155
* ``PyThreadState_GetDict()``
5256
* ``PyTuple_GetItem()``
57+
* ``PyTuple_SetItem()``
5358
* ``PyWeakref_G 10000 etObject()``
5459

5560
Macros
5661
------
5762

58-
* ``PyCell_GET()``: access directly ``PyCellObject.ob_ref``
59-
* ``PyList_GET_ITEM()``: access directly ``PyListObject.ob_item``
63+
* ``PyCell_GET()``
64+
* ``PyList_GET_ITEM()``
65+
* ``PyList_SET_ITEM()``
6066
* ``PyMethod_GET_CLASS()``
61-
* ``PyMethod_GET_FUNCTION()``: access directly ``PyMethodObject.im_func``
62-
* ``PyMethod_GET_SELF()``: access directly ``PyMethodObject.im_self``
63-
* ``PySequence_Fast_GET_ITEM()``: use ``PyList_GET_ITEM()``
64-
or ``PyTuple_GET_ITEM()``
65-
* ``PyTuple_GET_ITEM()``: access directly ``PyTupleObject.ob_item``
66-
* ``PyWeakref_GET_OBJECT()``: access directly ``PyWeakReference.wr_object``
67+
* ``PyMethod_GET_FUNCTION()``
68+
* ``PyMethod_GET_SELF()``
69+
* ``PySequence_Fast_GET_ITEM()``
70+
* ``PyTuple_GET_ITEM()``
71+
* ``PyTuple_SET_ITEM()``
72+
* ``PyWeakref_GET_OBJECT()``
73+
* ``Py_TYPE()``
74+
75+
Border line:
76+
77+
* ``Py_SETREF()``, ``Py_XSETREF()``: the caller has to manually increment the
78+
reference counter of the new value
6779

6880
Borrowed references: PyEval_GetFuncName()
6981
=========================================
@@ -121,6 +133,17 @@ Don't leak the structures like ``PyObject`` or ``PyTupleObject`` to not
121133
access directly fields, to not use fixed offset at the ABI level. Replace
122134
macros with functions calls. PyPy already does this in its C API (``cpyext``).
123135

136+
Example of macros:
137+
138+
* ``PyCell_GET()``: access directly ``PyCellObject.ob_ref``
139+
* ``PyList_GET_ITEM()``: access directly ``PyListObject.ob_item``
140+
* ``PyMethod_GET_FUNCTION()``: access directly ``PyMethodObject.im_func``
141+
* ``PyMethod_GET_SELF()``: access directly ``PyMethodObject.im_self``
142+
* ``PySequence_Fast_GET_ITEM()``: use ``PyList_GET_ITEM()``
143+
or ``PyTuple_GET_ITEM()``
144+
* ``PyTuple_GET_ITEM()``: access directly ``PyTupleObject.ob_item``
145+
* ``PyWeakref_GET_OBJECT()``: access directly ``PyWeakReference.wr_object``
146+
124147
PyType_Ready() and setting directly PyTypeObject fields
125148
=======================================================
126149

‎doc/consumers.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Popular modules using Cython
1818

1919
* uvloop
2020

21+
.. _debug-tools:
22+
2123
Debugging tools
2224
===============
2325

‎doc/remove_functions.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,17 @@ C extensions should call abstract functions like ``PyObject_GetItem()``.
1414

1515
See :ref:`Bad C API <bad-c-api>`.
1616

17+
Functions and macros removed from the new CAPI
18+
==============================================
19+
20+
Removed functions and macros which use :ref:`borrowed references
21+
<borrowed-ref>`:
22+
23+
* ``PyTuple_GET_ITEM()``
24+
* ``PyTuple_GetItem()``
25+
* ``PyTuple_SetItem()``
26+
* ``PyTuple_SET_ITEM()``
27+
1728
Only keep abstract functions
1829
============================
1930

‎doc/roadmap.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,14 @@ Roadmap
1919
the :ref:`new C API <new-c-api>` as the default in CPython and add an option
2020
for **opt-out** to stick with the :ref:`old C API <old-c-api>`.
2121

22+
Open questions
23+
==============
24+
25+
* Remove or deprecate APIs using borrowed references? If ``PyTuple_GetItem()``
26+
must be replaced with ``PyTuple_GetItemRef()``, how do we provide
27+
``PyTuple_GetItemRef()`` for Python 3.7 and older? See :ref:`Backward
28+
compatibility <back-compat>`.
29+
2230
Status
2331
======
2432

0 commit comments

Comments
 (0)
0