Commit 2e2a3cf
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -15,9 +15,14 @@ See also :ref:`Remove functions <remove-funcs>`. | |||
| 15 | 15 | Borrowed references | |
| 16 | 16 | =================== | |
| 17 | 17 | ||
| 18 | - CPython 3.7 has 36 functions and macros which return borrowed references: | ||
| 18 | + CPython 3.7 has 36 functions and macros which return borrowed references. | ||
| 19 | + | ||
| 20 | + CPython contains ``Doc/data/refcounts.dat`` (file is edited manually) which | ||
| 21 | + documents how functions handle reference count. | ||
| 22 | + | ||
| 23 | + Functions | ||
| 24 | + --------- | ||
| 19 | 25 | ||
| 20 | - * ``PyCell_GET()`` | ||
| 21 | 26 | * ``PyDict_GetItem()`` | |
| 22 | 27 | * ``PyDict_GetItemWithError()`` | |
| 23 | 28 | * ``PyDict_GetItemString()`` | |
@@ -34,47 +39,50 @@ CPython 3.7 has 36 functions and macros which return borrowed references: | |||
| 34 | 39 | * ``Py_InitModule3()`` | |
| 35 | 40 | * ``Py_InitModule4()`` | |
| 36 | 41 | * ``PyImport_GetModuleDict()`` | |
| 37 | - * ``PyList_GET_ITEM()`` | ||
| 38 | 42 | * ``PyList_GetItem()`` | |
| 39 | 43 | * ``PyMethod_Class()`` | |
| 40 | 44 | * ``PyMethod_Function()`` | |
| 41 | - * ``PyMethod_GET_CLASS()`` | ||
| 42 | - * ``PyMethod_GET_FUNCTION()`` | ||
| 43 | - * ``PyMethod_GET_SELF()`` | ||
| 44 | 45 | * ``PyMethod_Self()`` | |
| 45 | 46 | * ``PyModule_GetDict()`` | |
| 46 | 47 | * ``PyNumber_Check()`` | |
| 47 | 48 | * ``PyObject_Init()`` | |
| 48 | - * ``PySequence_Fast_GET_ITEM()`` | ||
| 49 | 49 | * ``PySys_GetObject()`` | |
| 50 | 50 | * ``PySys_GetXOptions()`` | |
| 51 | 51 | * ``PyThreadState_GetDict()`` | |
| 52 | - * ``PyTuple_GET_ITEM()`` | ||
| 53 | 52 | * ``PyTuple_GetItem()`` | |
| 54 | - * ``PyWeakref_GET_OBJECT()`` | ||
| 55 | 53 | * ``PyWeakref_GetObject()`` | |
| 56 | 54 | ||
| 57 | - CPython contains ``Doc/data/refcounts.dat`` (file is edited manually) which | ||
| 58 | - documents how functions handle reference count. | ||
| 55 | + Macros | ||
| 56 | + ------ | ||
| 59 | 57 | ||
| 58 | + * ``PyCell_GET()``: access directly ``PyCellObject.ob_ref`` | ||
| 59 | + * ``PyList_GET_ITEM()``: access directly ``PyListObject.ob_item`` | ||
| 60 | + * ``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`` | ||
| 60 | 67 | ||
| 61 | - ``PyObject**`` | ||
| 62 | - ============== | ||
| 68 | + | ||
| 69 | + Array of pointers to Python objects (``PyObject**``) | ||
| 70 | + ==================================================== | ||
| 63 | 71 | ||
| 64 | 72 | ``PyObject**`` must not be exposed: ``PyObject** PySequence_Fast_ITEMS(ob)`` | |
| 65 | 73 | has to go. | |
| 66 | 74 | ||
| 67 | - Evil PyDict_GetItem() | ||
| 68 | - ===================== | ||
| 75 | + PyDict_GetItem() | ||
| 76 | + ================ | ||
| 69 | 77 | ||
| 70 | 78 | The ``PyDict_GetItem()`` API is one of the most commonly called function but | |
| 71 | 79 | it has multiple flaws: | |
| 72 | 80 | ||
| 73 | 81 | * it returns a :ref:`borrowed reference <borrowed-ref>` | |
| 74 | 82 | * it ignores any kind of error: it calls ``PyErr_Clear()`` | |
| 75 | 83 | ||
| 76 | - The lookup is surrounded by ``PyErr_Fetch()`` and ``PyErr_Restore()`` to ignore | ||
| 77 | - any exception. | ||
| 84 | + The dictionary lookup is surrounded by ``PyErr_Fetch()`` and | ||
| 85 | + ``PyErr_Restore()`` to ignore any exception. | ||
| 78 | 86 | ||
| 79 | 87 | If hash(key) raises an exception, it clears the exception and just returns | |
| 80 | 88 | ``NULL``. | |
@@ -120,12 +128,17 @@ See also ``PyLong_AsLongAndOverflow()``. | |||
| 120 | 128 | Open questions | |
| 121 | 129 | ============== | |
| 122 | 130 | ||
| 131 | + .. _refcount: | ||
| 132 | + | ||
| 123 | 133 | Reference counting | |
| 124 | 134 | ------------------ | |
| 125 | 135 | ||
| 126 | 136 | Should we do something for reference counting, Py_INCREF and Py_DECREF? | |
| 127 | 137 | Replace them with function calls at least? | |
| 128 | 138 | ||
| 139 | + See :ref:`Change the garbage collector <change-gc>` and :ref:`Py_INCREF | ||
| 140 | + <incref>`. | ||
| 141 | + | ||
| 129 | 142 | ``PyObject_CallFunction("O")`` | |
| 130 | 143 | ------------------------------ | |
| 131 | 144 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -79,6 +79,9 @@ Py_INCREF() | |||
| 79 | 79 | The open question remains if it will be possible to replace ``Py_INCREF()`` and | |
| 80 | 80 | ``Py_DECREF()`` with function calls without killing performances. | |
| 81 | 81 | ||
| 82 | + See :ref:`Reference counting <refcount>` and :ref:`Change the garbage collector | ||
| 83 | + <change-gc>`. | ||
| 84 | + | ||
| 82 | 85 | Hide C structures | |
| 83 | 86 | ----------------- | |
| 84 | 87 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -16,6 +16,8 @@ Remove debug checks | |||
| 16 | 16 | See :ref:`Regular runtime <regular-runtime>`: since a debug runtime will be | |
| 17 | 17 | provided by default, many sanity checks can be removed from the release build. | |
| 18 | 18 | ||
| 19 | + .. _change-gc: | ||
| 20 | + | ||
| 19 | 21 | Change the garbage collector: unlikely | |
| 20 | 22 | ====================================== | |
| 21 | 23 | ||
@@ -30,6 +32,8 @@ the C API, which is out of the scope of the :ref:`new C API project | |||
| 30 | 32 | <new-c-api>`. The main risk is to break too many C extensions which would make | |
| 31 | 33 | this idea unsuable in practice. | |
| 32 | 34 | ||
| 35 | + See also :ref:`Reference counting <refcount>`. | ||
| 36 | + | ||
| 33 | 37 | Remove the GIL: unlikely | |
| 34 | 38 | ======================== | |
| 35 | 39 | ||
0 commit comments