|
6 | 6 |
|
7 | 7 | .. _chapter_refcount: |
8 | 8 |
|
| 9 | +.. |
| 10 | + .. _Reference Counting: https://docs.python.org/3.9/c-api/refcounting.html |
| 11 | + |
| 12 | +.. _Py_REFCNT(): https://docs.python.org/3.9/c-api/structures.html#c.Py_REFCNT |
| 13 | +.. _Py_INCREF(): https://docs.python.org/3.9/c-api/refcounting.html#c.Py_INCREF |
| 14 | +.. _Py_XINCREF(): https://docs.python.org/3.9/c-api/refcounting.html#c.Py_XINCREF |
| 15 | +.. _Py_DECREF(): https://docs.python.org/3.9/c-api/refcounting.html#c.Py_DECREF |
| 16 | +.. _Py_XDECREF(): https://docs.python.org/3.9/c-api/refcounting.html#c.Py_XDECREF |
| 17 | + |
9 | 18 | .. index:: |
10 | 19 | single: Reference Counts |
11 | 20 | single: Reference Counts; New |
@@ -37,6 +46,37 @@ In Python C extensions you always create and deallocate these ``PyObjects`` *ind |
37 | 46 | Creation is via Python's C API and destruction is done by decrementing the reference count. |
38 | 47 | If this count hits zero then CPython will free all the resources used by the object. |
39 | 48 |
|
| 49 | +The macros to manipulate reference counts are: |
| 50 | + |
| 51 | +.. list-table:: Reference Count Macros |
| 52 | + :widths: 20 85 |
| 53 | + :header-rows: 1 |
| 54 | + |
| 55 | + * - Macro |
| 56 | + - Description |
| 57 | + * - `Py_REFCNT()`_ |
| 58 | + - Get the reference count of an object. |
| 59 | + This expands to ``(((PyObject*)(o))->ob_refcnt)``. |
| 60 | + This will segfault if passed ``NULL``. |
| 61 | + * - `Py_INCREF()`_ |
| 62 | + - Increments the reference count of the given ``PyObject *``. |
| 63 | + This will segfault if passed ``NULL``. |
| 64 | + * - `Py_XINCREF()`_ |
| 65 | + - As `Py_INCREF()`_ but does nothing if passed ``NULL``. |
| 66 | + * - `Py_DECREF()`_ |
| 67 | + - Decrements the reference count of the given ``PyObject *``. |
| 68 | + This will segfault if passed ``NULL``. |
| 69 | + If the reference count reaches zero then the object will be deallocated and the memory *may* be reused. |
| 70 | + |
| 71 | + **Warning:** De-allocation might cause the execution of arbitrary Python code has free access to all Python |
| 72 | + global variables. |
| 73 | + |
| 74 | + **Warning:** Calling this when the reference count is 1 might reuse the memory so on exit the object reference |
| 75 | + count could be anything. |
| 76 | + * - `Py_XDECREF()`_ |
| 77 | + - As `Py_DECREF()`_ but does nothing if passed ``NULL``. |
| 78 | + |
| 79 | + |
40 | 80 | Here is an example of a normal ``PyObject`` creation, print and de-allocation: |
41 | 81 |
|
42 | 82 | .. code-block:: c |
@@ -151,7 +191,7 @@ And here is what happens to the memory if we use this function from Python (``cP |
151 | 191 | >>> s = ' ' * 100 * 1024**2 # Process uses about 101Mb |
152 | 192 | >>> del s # Process uses about 1Mb |
153 | 193 | >>> s = ' ' * 100 * 1024**2 # Process uses about 101Mb |
154 | | - >>> cPyRefs.incref(s) # Now do an increment without decrement |
| 194 | + >>> cPyRefs.bad_incref(s) # Now do an increment without decrement |
155 | 195 | >>> del s # Process still uses about 101Mb - leaked |
156 | 196 | >>> s # Officially 's' does not exist |
157 | 197 | Traceback (most recent call last): |
@@ -715,7 +755,7 @@ In other words is ``value`` or ``container[0]`` *strong* or *weak*? |
715 | 755 |
|
716 | 756 | This model determines that ``container`` holds the *strong* reference since on destruction of that container |
717 | 757 | ``Py_DECREF()`` will be called on that reference reducing the strong reference count to zero. |
718 | | -Therefor ``value``, once a *strong* reference is now a *weak* reference. |
| 758 | +Therefore ``value``, once a *strong* reference is now a *weak* reference. |
719 | 759 | This expresses the concept of *stealing* a reference. |
720 | 760 | So we end up with: |
721 | 761 |
|
|
0 commit comments