Skip to content

Doc: Use critical sections for custom types #124802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Doc: Use critical sections for custom types #124802

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eddb0b1
Doc: Use critical sections for custom types
colesbury Sep 30, 2024
74d886d
Update Doc/c-api/init.rst
colesbury Oct 1, 2024
4f74b80
Update doc
colesbury Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Doc/c-api/init.rst
View file
Open in desktop
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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear to me what the "notable exception" means here. Is it saying that PyDict_Next doesn't use a critical section internally, so you should acquire the dict's critical section in client code that checks for the dict changing size to see if the iterator needs to be invalidated?

Or does it mean something else? Is there an appropriate cross-reference that could make this clearer?

Copy link
Contributor

@ngoldbaum ngoldbaum Oct 1, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there an appropriate cross-reference that could make this clearer?

I think this is referring to the last sentence and code example in https://docs.python.org/3.13/c-api/dict.html#c.PyDict_Next

Copy link
Contributor Author

@colesbury colesbury Oct 1, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, PyDict_Next doesn't use a critical section internally so you should use Py_BEGIN_CRITICAL_SECTION to lock the dictionary while iterating over it. The relevant cross-reference is the last paragraph of PyDict_Next. I don't know if we can link to that directly.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe:

...with the notable exception of PyDict_Next(), which requires external locking.


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
Loading