From cecf2335366bfd9faaa62d4070aba317b76e1aed Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Sun, 24 Aug 2025 12:54:34 +0530 Subject: [PATCH 1/8] gh-138098: Clarify strong references in PyDict_Next docs for free-threaded build --- Doc/c-api/dict.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index e55c5c80cb83c0e..71cdb04e47533fd 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -258,6 +258,14 @@ Dictionary Objects value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are not consecutive. + .. note:: + + In the free-threaded build, this function can be used safely inside + a critical section. However, the references returned for *pkey* and + *pvalue* are borrowed and only valid while the critical section is + held. If you need to use these objects outside the critical section, + create strong references (for example, with :c:func:`Py_NewRef`). + For example:: PyObject *key, *value; From 597c0b59fac8c52bc84e4cff8f1897de6e1228be Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Mon, 25 Aug 2025 08:29:09 +0530 Subject: [PATCH 2/8] Doc: clarify PyDict_Next docs for free-threaded build --- Doc/c-api/dict.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 71cdb04e47533fd..0afb809ebecbe2c 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -260,11 +260,12 @@ Dictionary Objects .. note:: - In the free-threaded build, this function can be used safely inside + On the :term:`free threaded ` build, this function can be used safely inside a critical section. However, the references returned for *pkey* and - *pvalue* are borrowed and only valid while the critical section is - held. If you need to use these objects outside the critical section, - create strong references (for example, with :c:func:`Py_NewRef`). + *pvalue* are :term:`borrowed ` and only valid while the critical section is + held. If you need to use these objects outside the critical section or when the critical section + can be suspended, create :term:`strong references ` (for example, with + :c:func:`Py_NewRef`). For example:: From 5e7c4e1e8fcfbcf4d55bd579112ce47634c343e0 Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Mon, 25 Aug 2025 13:40:17 +0530 Subject: [PATCH 3/8] Move PyDict_Next strong ref note closer to free-threading section --- Doc/c-api/dict.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 0afb809ebecbe2c..9344c5faaaf5156 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -258,15 +258,6 @@ Dictionary Objects value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are not consecutive. - .. note:: - - On the :term:`free threaded ` build, this function can be used safely inside - a critical section. However, the references returned for *pkey* and - *pvalue* are :term:`borrowed ` and only valid while the critical section is - held. If you need to use these objects outside the critical section or when the critical section - can be suspended, create :term:`strong references ` (for example, with - :c:func:`Py_NewRef`). - For example:: PyObject *key, *value; @@ -304,6 +295,15 @@ Dictionary Objects :c:macro:`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating over it:: + .. note:: + + On the :term:`free threaded ` build, this function can be used safely inside + a critical section. However, the references returned for *pkey* and + *pvalue* are :term:`borrowed ` and only valid while the critical section is + held. If you need to use these objects outside the critical section or when the critical section + can be suspended, create :term:`strong references ` (for example, with + :c:func:`Py_NewRef`). + Py_BEGIN_CRITICAL_SECTION(self->dict); while (PyDict_Next(self->dict, &pos, &key, &value)) { ... From 423768334dfc885710d9dda27410d14f3513f728 Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Mon, 25 Aug 2025 14:06:24 +0530 Subject: [PATCH 4/8] Move PyDict_Next strong ref note closer to free-threading section --- Doc/c-api/dict.rst | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 9344c5faaaf5156..13744cc5d040abd 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -295,20 +295,23 @@ Dictionary Objects :c:macro:`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating over it:: - .. note:: +.. note:: - On the :term:`free threaded ` build, this function can be used safely inside - a critical section. However, the references returned for *pkey* and - *pvalue* are :term:`borrowed ` and only valid while the critical section is - held. If you need to use these objects outside the critical section or when the critical section - can be suspended, create :term:`strong references ` (for example, with - :c:func:`Py_NewRef`). + On the :term:`free threaded ` build, this function can be used safely inside + a critical section. However, the references returned for *pkey* and + *pvalue* are :term:`borrowed ` and only valid while the critical section is + held. If you need to use these objects outside the critical section or when the critical section + can be suspended, create :term:`strong reference ` (for example, with + :c:func:`Py_NewRef`). + +.. code-block:: c + + Py_BEGIN_CRITICAL_SECTION(self->dict); + while (PyDict_Next(self->dict, &pos, &key, &value)) { + ... + } + Py_END_CRITICAL_SECTION(); - Py_BEGIN_CRITICAL_SECTION(self->dict); - while (PyDict_Next(self->dict, &pos, &key, &value)) { - ... - } - Py_END_CRITICAL_SECTION(); .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override) From 43b9356b6279f5d761f46e4e0864a8a71b5f3264 Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Mon, 25 Aug 2025 14:18:10 +0530 Subject: [PATCH 5/8] Move PyDict_Next strong ref note closer to free-threading section --- Doc/c-api/dict.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 13744cc5d040abd..cc11484d7e6478c 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -299,20 +299,18 @@ Dictionary Objects On the :term:`free threaded ` build, this function can be used safely inside a critical section. However, the references returned for *pkey* and - *pvalue* are :term:`borrowed ` and only valid while the critical section is - held. If you need to use these objects outside the critical section or when the critical section + *pvalue* are :term:`borrowed ` and only valid while the critical section + is held. If you need to use these objects outside the critical section or when the critical section can be suspended, create :term:`strong reference ` (for example, with :c:func:`Py_NewRef`). -.. code-block:: c - - Py_BEGIN_CRITICAL_SECTION(self->dict); - while (PyDict_Next(self->dict, &pos, &key, &value)) { - ... - } - Py_END_CRITICAL_SECTION(); - + .. code-block:: c + Py_BEGIN_CRITICAL_SECTION(self->dict); + while (PyDict_Next(self->dict, &pos, &key, &value)) { + ... + } + Py_END_CRITICAL_SECTION(); .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override) From 954852e828ca947d236f8f3fb8de175d834d7497 Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Mon, 25 Aug 2025 14:28:43 +0530 Subject: [PATCH 6/8] Move PyDict_Next strong ref note closer to free-threading section --- Doc/c-api/dict.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index cc11484d7e6478c..fdb4e924099eb2e 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -297,11 +297,12 @@ Dictionary Objects .. note:: - On the :term:`free threaded ` build, this function can be used safely inside - a critical section. However, the references returned for *pkey* and - *pvalue* are :term:`borrowed ` and only valid while the critical section - is held. If you need to use these objects outside the critical section or when the critical section - can be suspended, create :term:`strong reference ` (for example, with + On the :term:`free-threaded ` build, this function can be + used safely inside a critical section. However, the references returned + for *pkey* and *pvalue* are :term:`borrowed ` and only + valid while the critical section is held. If you need to use these objects + outside the critical section or when the critical section can be suspended, + create :term:`strong reference ` (for example, with :c:func:`Py_NewRef`). .. code-block:: c From f3caa2dca2bfa38d0cb56080f062a55242705e89 Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Mon, 25 Aug 2025 15:51:12 +0530 Subject: [PATCH 7/8] Move PyDict_Next strong ref note closer to free-threading section --- Doc/c-api/dict.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index fdb4e924099eb2e..196fe9acb3c6bf3 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -258,6 +258,17 @@ Dictionary Objects value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are not consecutive. + .. note:: + + On the free-threaded build, this function can be used safely inside a + critical section. However, the references returned for *pkey* and *pvalue* + are :term:`borrowed ` and are only valid while the + critical section is held. If you need to use these objects outside the + critical section or when the critical section can be suspended, create a + :term:`strong reference ` (for example, using + :c:func:`Py_NewRef`). + + For example:: PyObject *key, *value; @@ -295,24 +306,13 @@ Dictionary Objects :c:macro:`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating over it:: -.. note:: - - On the :term:`free-threaded ` build, this function can be - used safely inside a critical section. However, the references returned - for *pkey* and *pvalue* are :term:`borrowed ` and only - valid while the critical section is held. If you need to use these objects - outside the critical section or when the critical section can be suspended, - create :term:`strong reference ` (for example, with - :c:func:`Py_NewRef`). - - .. code-block:: c - Py_BEGIN_CRITICAL_SECTION(self->dict); while (PyDict_Next(self->dict, &pos, &key, &value)) { - ... + ... } Py_END_CRITICAL_SECTION(); + .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override) Iterate over mapping object *b* adding key-value pairs to dictionary *a*. From 75019255cc8c9db79a7e72cbbd7a93efd32145fa Mon Sep 17 00:00:00 2001 From: PrineNaroliya Date: Mon, 25 Aug 2025 16:50:27 +0530 Subject: [PATCH 8/8] Move PyDict_Next strong ref note closer to free-threading section --- Doc/c-api/dict.rst | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 196fe9acb3c6bf3..0fbe26b56c0a7c6 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -258,17 +258,6 @@ Dictionary Objects value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are not consecutive. - .. note:: - - On the free-threaded build, this function can be used safely inside a - critical section. However, the references returned for *pkey* and *pvalue* - are :term:`borrowed ` and are only valid while the - critical section is held. If you need to use these objects outside the - critical section or when the critical section can be suspended, create a - :term:`strong reference ` (for example, using - :c:func:`Py_NewRef`). - - For example:: PyObject *key, *value; @@ -308,10 +297,19 @@ Dictionary Objects Py_BEGIN_CRITICAL_SECTION(self->dict); while (PyDict_Next(self->dict, &pos, &key, &value)) { - ... + ... } Py_END_CRITICAL_SECTION(); + .. note:: + + On the free-threaded build, this function can be used safely inside a + critical section. However, the references returned for *pkey* and *pvalue* + are :term:`borrowed ` and are only valid while the + critical section is held. If you need to use these objects outside the + critical section or when the critical section can be suspended, create a + :term:`strong reference ` (for example, using + :c:func:`Py_NewRef`). .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)