From eddb0b11fe96bfb1fdf1ec12d9834dd9a8517ea7 Mon Sep 17 00:00:00 2001 From: Sam Gross Date: Mon, 30 Sep 2024 20:37:28 +0000 Subject: [PATCH] Doc: Use critical sections for custom types You should generally not use critical sections with built-in types because they already use critical sections internally. --- Doc/c-api/init.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 561c8a1b879bae..bb859ac0fe5f3c 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -2226,6 +2226,12 @@ is resumed, and its locks reacquired. This means the critical section API provides weaker guarantees than traditional locks -- they are useful because their behavior is similar to the :term:`GIL`. +Critical sections are appropriate for protecting custom types defined by your +C-API extensions. They should generally not be used with built-in types like +:c:struct:`PyDictObject` or :c:struct:`PyListObject` because their public APIs +already use critical sections internally, with the notable exception of +:c:func:`PyDict_Next`. + The functions and structs used by the macros are exposed for cases where C macros are not available. They should only be used as in the given macro expansions. Note that the sizes and contents of the structures may