Complete the containers_and_refcounts.rst by adding code, tests and documentation for sets.

Author: paulross

doc/sphinx/source/containers_and_refcounts.rst

@@ -823,7 +823,6 @@ Summary
 
 
 .. Links, mostly to the Python documentation:
-   TODO: Investigate/create tests for all of these.
 
 .. Setters
 
@@ -1481,10 +1480,14 @@ The C function signature is:
 ``Py_BuildValue("{OO}", key, value);`` will increment the refcount of the key and value and this can,
 potentially, leak.
 
-.. code-block:: c
 
-    int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue);
+.. Links, mostly to the Python documentation:
+
+.. Setters
 
+.. _PySet_Add(): https://docs.python.org/3/c-api/set.html#c.PySet_Add
+.. _PySet_Discard(): https://docs.python.org/3/c-api/set.html#c.PySet_Discard
+.. _PySet_Pop(): https://docs.python.org/3/c-api/set.html#c.PySet_Pop
 
 .. _chapter_containers_and_refcounts.sets:
 
@@ -1495,21 +1498,128 @@ potentially, leak.
 Sets
 -----------------------
 
-.. todo::
+.. index::
+    single: PySet_Add()
+    single: Set; PySet_Add()
 
-    Complete chapter :ref:`chapter_containers_and_refcounts` section :ref:`chapter_containers_and_refcounts.sets`.
+``PySet_Add()``
+--------------------
 
+`PySet_Add()`_ is fairly straightforward.
+The set will increment the reference count of the value thus:
 
-.. _chapter_containers_and_refcounts.summary:
+.. code-block:: c
 
------------------------
-Summary
------------------------
+    PyObject *container = PySet_New(NULL);
+    /* Py_REFCNT(container) is 1 */
+    PyObject *value = new_unique_string(__FUNCTION__, NULL);
+    /* Py_REFCNT(value) is 1 */
+    int ret_val = PySet_Add(container, value);
+    assert(ret_val == 0);
+    /* Py_REFCNT(value) is now 2 */
 
-.. todo::
+    /* Add duplicate. */
+    ret_val = PySet_Add(container, value);
+    assert(ret_val == 0);
+    /* Py_REFCNT(value) is still 2 */
+
+    /* Clean up. */
+    Py_DECREF(container);
+    /* Py_REFCNT(value) is now 1 */
+    Py_DECREF(value);
+
+.. index::
+    single: PySet_Discard()
+    single: Set; PySet_Discard()
+
+``PySet_Discard()``
+--------------------
 
-    Complete chapter :ref:`chapter_containers_and_refcounts` section :ref:`chapter_containers_and_refcounts.summary`.
+`PySet_Discard()`_ is also fairly straightforward.
+The set will discard (:ref:`chapter_containers_and_refcounts.discarded`) the value thus:
 
+.. code-block:: c
+
+    PyObject *container = PySet_New(NULL);
+    /* Py_REFCNT(container) is 1 */
+    PyObject *value = new_unique_string(__FUNCTION__, NULL);
+    /* Py_REFCNT(value) is 1 */
+    int ret_val = PySet_Add(container, value);
+    assert(ret_val == 0);
+    /* Py_REFCNT(value) is now 2 */
+
+    /* Discard. */
+    ret_val = PySet_Discard(container, value);
+    assert(ret_val == 1);
+    /* Py_REFCNT(value) is now 1 */
+
+    /* Clean up. */
+    Py_DECREF(container);
+    /* Py_REFCNT(value) is still 1 */
+    Py_DECREF(value);
+
+.. index::
+    single: PySet_Pop()
+    single: Set; PySet_Pop()
+
+``PySet_Pop()``
+--------------------
+
+`PySet_Pop()`_ will return a *new* reference to the existing object and it is up to caller to decrement the
+reference count appropriately.
+
+For example, the reference counts work as follows:
+
+.. code-block:: c
+
+    PyObject *container = PySet_New(NULL);
+    /* Py_REFCNT(container) is 1 */
+    PyObject *value = new_unique_string(__FUNCTION__, NULL);
+    /* Py_REFCNT(value) is 1 */
+    int ret_val = PySet_Add(container, value);
+    assert(ret_val == 0);
+    /* Py_REFCNT(value) is now 2 */
+
+    /* Pop. */
+    PyObject *popped_value = PySet_Pop(container);
+    assert(popped_value == value);
+    /* Py_REFCNT(value) is still 2 */
+
+    /* Clean up. */
+    Py_DECREF(container);
+    /* Py_REFCNT(value) is still 2 so need to double Py_DECREF calls. */
+    Py_DECREF(value);
+    Py_DECREF(value);
+
+So this is how `PySet_Pop()`_  might be used in practice:
+
+.. code-block:: c
+
+
+    void add_to_set(PyObject *container) {
+        PyObject *value = new_unique_string(__FUNCTION__, NULL);
+        /* Py_REFCNT(value) is 1 */
+        int ret_val = PySet_Add(container, value);
+        assert(ret_val == 0);
+        /* Py_REFCNT(value) is now 2 */
+        /* Decrement our local value */
+        Py_DECREF(value);
+        /* Now the container has the only reference to the value. */
+    }
+
+    void pop_from_set(PyObject *container) {
+        PyObject *value = PySet_Pop(container);
+        /* Do something with the value... */
+
+        /* Then as we 'own' value we need to free it. */
+        Py_DECREF(value);
+    }
+
+    PyObject *container = PySet_New(NULL);
+    add_to_set(container);
+    pop_from_set(container);
+    /* Clean up. */
+    Py_DECREF(container);
 
 .. Example footnote [#]_.
 

doc/sphinx/source/introduction.rst

@@ -38,14 +38,14 @@ Python extension in C.
 I really struggled to bring my knowledge of both languages to their very complicated, and crucial, codebase.
 To be honest I don't think I did a great job, but as I was the 'owner' I somehow got away with it.
 
-After about six months of anxiety it occurred to me that, rather learning from their scrappy CPython C code,
+After some time it occurred to me that, rather learning from their scrappy CPython C code,
 I asked myself "how would you write a Python C Extension from scratch?".
 So on the commute and at weekends I did just that and slowly things became clearer.
 This eventually lead me to being invited to PyConUS to give a talk about the subject.
 This document is a synthesis of the latter journey which ended up giving me far more confidence about the subject than
 during my earlier difficulties.
 
-My fond hope is that you will find that this document makes it much easier to work in this field.
+My fond hope is that you will find that this document makes it much easier to work in this field than I found initially.
 Another way of saying that is that I dedicate this document to you, and your work.
 
 So why write Python C Extensions?
@@ -88,7 +88,8 @@ C and C++ have more specific deallocation policies than with a garbage collected
 The GIL
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-C Extensions do not need the Global Interpreter Lock (GIL) when working with C/C++ code.
+C Extensions do not need the Global Interpreter Lock (GIL) when working with C/C++ code which do *not* make calls to
+the CPython API.
 
 ---------------------
 Why Not?
@@ -178,4 +179,4 @@ Next up: a simple example showing the effect on code performance.
 .. rubric:: Footnotes
 
 .. [#] Huge, but pretty consistent once mastered.
-.. [#] Version 0.2 of this project supports Python versions: 3.9, 3.10, 3.11, 3.12, 3.13.
+.. [#] Version 0.3 of this project supports Python versions: 3.9, 3.10, 3.11, 3.12, 3.13.

src/cpy/Containers/DebugContainers.c

@@ -2336,6 +2336,173 @@ void dbg_PyDict_Pop_key_absent(void) {
 
 #endif // #if PY_MAJOR_VERSION >= 3 && PY_MINOR_VERSION >= 13
 
+#pragma mark - Sets
+
+void dbg_PySet_Add(void) {
+    printf("%s():\n", __FUNCTION__);
+    if (PyErr_Occurred()) {
+        fprintf(stderr, "%s(): On entry PyErr_Print() %s#%d:\n", __FUNCTION__, __FILE_NAME__, __LINE__);
+        PyErr_Print();
+        return;
+    }
+    assert(!PyErr_Occurred());
+    Py_ssize_t ref_count;
+
+    PyObject *container = PySet_New(NULL);
+    assert(container);
+
+    ref_count = Py_REFCNT(container);
+    assert(ref_count == 1);
+
+    PyObject *value = new_unique_string(__FUNCTION__, NULL);
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 1);
+
+    assert(PySet_GET_SIZE(container) == 0);
+
+    if (PySet_Add(container, value)) {
+        assert(0);
+    }
+    assert(PySet_GET_SIZE(container) == 1);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 2);
+
+    assert(PySet_Contains(container, value) == 1);
+
+    // Now insert the same object again, dupe of the code above.
+    if (PySet_Add(container, value)) {
+        assert(0);
+    }
+    assert(PySet_GET_SIZE(container) == 1);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 2);
+
+    assert(PySet_Contains(container, value) == 1);
+
+    Py_DECREF(container);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 1);
+
+    /* Clean up. */
+    Py_DECREF(value);
+
+    assert(!PyErr_Occurred());
+}
+
+void dbg_PySet_Discard(void) {
+    printf("%s():\n", __FUNCTION__);
+    if (PyErr_Occurred()) {
+        fprintf(stderr, "%s(): On entry PyErr_Print() %s#%d:\n", __FUNCTION__, __FILE_NAME__, __LINE__);
+        PyErr_Print();
+        return;
+    }
+    assert(!PyErr_Occurred());
+    Py_ssize_t ref_count;
+
+    PyObject *container = PySet_New(NULL);
+    assert(container);
+
+    ref_count = Py_REFCNT(container);
+    assert(ref_count == 1);
+
+    PyObject *value = new_unique_string(__FUNCTION__, NULL);
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 1);
+
+    assert(PySet_GET_SIZE(container) == 0);
+
+    if (PySet_Add(container, value)) {
+        assert(0);
+    }
+    assert(PySet_GET_SIZE(container) == 1);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 2);
+
+    assert(PySet_Contains(container, value) == 1);
+
+    if (PySet_Discard(container, value) != 1) {
+        assert(0);
+    }
+    assert(PySet_GET_SIZE(container) == 0);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 1);
+
+    assert(PySet_Contains(container, value) == 0);
+
+    Py_DECREF(container);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 1);
+
+    /* Clean up. */
+    Py_DECREF(value);
+
+    assert(!PyErr_Occurred());
+}
+
+void dbg_PySet_Pop(void) {
+    printf("%s():\n", __FUNCTION__);
+    if (PyErr_Occurred()) {
+        fprintf(stderr, "%s(): On entry PyErr_Print() %s#%d:\n", __FUNCTION__, __FILE_NAME__, __LINE__);
+        PyErr_Print();
+        return;
+    }
+    assert(!PyErr_Occurred());
+    Py_ssize_t ref_count;
+
+    PyObject *container = PySet_New(NULL);
+    assert(container);
+
+    ref_count = Py_REFCNT(container);
+    assert(ref_count == 1);
+
+    PyObject *value = new_unique_string(__FUNCTION__, NULL);
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 1);
+
+    assert(PySet_GET_SIZE(container) == 0);
+
+    if (PySet_Add(container, value)) {
+        assert(0);
+    }
+    assert(PySet_GET_SIZE(container) == 1);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 2);
+
+    assert(PySet_Contains(container, value) == 1);
+
+    // Now pop()
+    PyObject *popped_value = PySet_Pop(container);
+
+    assert(popped_value == value);
+
+    assert(PySet_GET_SIZE(container) == 0);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 2);
+
+    assert(PySet_Contains(container, value) == 0);
+
+    Py_DECREF(container);
+
+    ref_count = Py_REFCNT(value);
+    assert(ref_count == 2);
+
+    /* Clean up. */
+    Py_DECREF(value);
+    Py_DECREF(value);
+
+    assert(!PyErr_Occurred());
+}
+
+#pragma mark - Code that sefgfaults
+
 #if ACCEPT_SIGSEGV
 
 void dbg_PyTuple_SetItem_SIGSEGV_on_same_value(void) {

src/cpy/Containers/DebugContainers.h

@@ -78,6 +78,13 @@ void dbg_PyDict_Pop_key_present(void);
 void dbg_PyDict_Pop_key_absent(void);
 #endif // #if PY_MAJOR_VERSION >= 3 && PY_MINOR_VERSION >= 13
 
+#pragma mark - Sets
+
+void dbg_PySet_Add(void);
+void dbg_PySet_Discard(void);
+void dbg_PySet_Pop(void);
+
+
 #if ACCEPT_SIGSEGV
 void dbg_PyTuple_SetItem_SIGSEGV_on_same_value(void);
 void dbg_PyList_SetItem_SIGSEGV_on_same_value(void);