Skip to content

Commit

Permalink
Doc: Use critical sections for custom types
Browse files Browse the repository at this point in the history
You should generally not use critical sections with built-in types
because they already use critical sections internally.
  • Loading branch information
colesbury committed Sep 30, 2024
1 parent 7e7223e commit eddb0b1
Showing 1 changed file with 6 additions and 0 deletions.
6 changes: 6 additions & 0 deletions Doc/c-api/init.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit eddb0b1

Please sign in to comment.