From 6303969d2e0680fe38644872b60a507a65f4f205 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Tue, 12 Dec 2023 11:14:33 +0900 Subject: [PATCH 1/4] Add explanation about @critical_section target directive --- development-tools/clinic.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index fe1361e88c..439a23ed65 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1996,6 +1996,37 @@ The generated glue code looks like this: return return_value; } +If you want to specify a target object to lock then you can use a target directive for +``@critical_section``. Since the ``@critical_section`` locks the object which is located +as the first argument implicitly, you will need this feature when the ``@critical_section`` +locks an unwanted target object. Note that explicit target declaration only supports up to 2 objects. + +Example from :cpy-file:`Modules/_weakref.c`:: + + /*[clinic input] + @critical_section object + _weakref.getweakrefcount -> Py_ssize_t + + object: object + / + Return the number of weak references to 'object'. + [clinic start generated code]*/ + +The generated glue code looks like this: + +.. code-block:: c + + static PyObject * + _weakref_getweakrefs(PyObject *module, PyObject *object) + { + PyObject *return_value = NULL; + + Py_BEGIN_CRITICAL_SECTION(object); + return_value = _weakref_getweakrefs_impl(module, object); + Py_END_CRITICAL_SECTION(); + + return return_value; + } .. versionadded:: 3.13 From ad65877569543297aa8d786021ca9b25e7fa19da Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Tue, 12 Dec 2023 11:16:48 +0900 Subject: [PATCH 2/4] nit --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 439a23ed65..fe491076da 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1996,7 +1996,7 @@ The generated glue code looks like this: return return_value; } -If you want to specify a target object to lock then you can use a target directive for +If you want to specify a target object to be locked then you can use a target directive for ``@critical_section``. Since the ``@critical_section`` locks the object which is located as the first argument implicitly, you will need this feature when the ``@critical_section`` locks an unwanted target object. Note that explicit target declaration only supports up to 2 objects. From 0a94b077ef9fd228bfe2c7de77ed824bfc0efad9 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Tue, 12 Dec 2023 20:50:13 +0900 Subject: [PATCH 3/4] Update development-tools/clinic.rst Co-authored-by: Erlend E. Aasland --- development-tools/clinic.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index fe491076da..abf28fe9f1 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1996,12 +1996,11 @@ The generated glue code looks like this: return return_value; } -If you want to specify a target object to be locked then you can use a target directive for -``@critical_section``. Since the ``@critical_section`` locks the object which is located -as the first argument implicitly, you will need this feature when the ``@critical_section`` -locks an unwanted target object. Note that explicit target declaration only supports up to 2 objects. - -Example from :cpy-file:`Modules/_weakref.c`:: +You can lock up to two additional objects +by supplying their C variable names as arguments +to the ``@critical_section`` directive. +This example from :cpy-file:`Modules/_weakref.c` takes +one additional argument (a C variable named ``object``):: /*[clinic input] @critical_section object From 8e7e8ffabe6a542f233bdce6f99b7036ec2684e2 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Tue, 12 Dec 2023 23:09:41 +0900 Subject: [PATCH 4/4] Update development-tools/clinic.rst Co-authored-by: Ezio Melotti --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index abf28fe9f1..8592948945 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1996,7 +1996,7 @@ The generated glue code looks like this: return return_value; } -You can lock up to two additional objects +You can lock one or two additional objects by supplying their C variable names as arguments to the ``@critical_section`` directive. This example from :cpy-file:`Modules/_weakref.c` takes