Skip to content

bpo-28254: Add a C-API for controlling the state of the garbage collector #25687

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

Merged
vstinner merged 17 commits into from
Apr 28, 2021
Merged

bpo-28254: Add a C-API for controlling the state of the garbage collector #25687

Changes from 1 commit
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
6229a31
bpo-28254: Add a C-API for controlling the state of the garbage colle…
scoder Apr 28, 2021
bfbadb9
bpo-28254: Improve markup and add a What's New entry.
scoder Apr 28, 2021
f41d269
Apply suggestions from code review
pablogsal Apr 28, 2021
56465a9
bpo-28254: Return the previous GC state from the Enable/Disable funct…
scoder Apr 28, 2021
7b6e320
Update Modules/_testcapimodule.c
pablogsal Apr 28, 2021
b7e4ee3
Update Modules/_testcapimodule.c
pablogsal Apr 28, 2021
4e11560
Update Modules/_testcapimodule.c
pablogsal Apr 28, 2021
e5f0077
bpo-28254: Formatting.
scoder Apr 28, 2021
c64aa42
bpo-28254: Move new functions to a better place (not cutting into the…
scoder Apr 28, 2021
cbee918
Remove an incorrect part of a comment: PyGC_Collect() actually does n…
scoder Apr 28, 2021
0f7e608
bpo-28254: Add documentation for the PyGC_*() functions.
scoder Apr 28, 2021
80c3625
bpo-28254: Add new PyGC_*() functions to the stable ABI list.
scoder Apr 28, 2021
25fb2aa
bpo-28254: Apply suggestions from doc review.
scoder Apr 28, 2021
10ad929
Apply suggestions from doc review
scoder Apr 28, 2021
1ffe937
Add a word on how PyGC_Collect() and gc.collect() differ.
scoder Apr 28, 2021
d517665
Fix version marker.
scoder Apr 28, 2021
84fb2af
Fix version marker (II).
scoder Apr 28, 2021
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
Prev Previous commit
Next Next commit
bpo-28254: Add documentation for the PyGC_*() functions.
  • Loading branch information
@scoder
scoder committed Apr 28, 2021
commit 0f7e6088301597afccee6b5a1d61f04774c4ae11
40 changes: 40 additions & 0 deletions Doc/c-api/gcsupport.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,3 +173,43 @@ if the object is immutable.
this method (don't just call :c:func:`Py_DECREF` on a reference). The
collector will call this method if it detects that this object is involved
in a reference cycle.


Controlling the Garbage Collector State
---------------------------------------

The C-API provides the following functions for controlling
garbage collection runs.

Comment thread
scoder marked this conversation as resolved.
.. c:function:: Py_ssize_t PyGC_Collect(void)

Performs a garbage collection, if the garbage collector is enabled.
Comment thread
scoder marked this conversation as resolved.
Outdated
Returns the number of collected + uncollectable objects.
Copy link
Copy Markdown
Member

@vstinner vstinner Apr 28, 2021

Choose a reason for hiding this comment

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

Hum, uncollectable objects are stored in gc.garbage no? Shoud we document that?

The C code uses "unreachable objects that couldn't be collected" in a comment instead of "uncollectable objects". Maybe it's a more explicit definition.

Copy link
Copy Markdown
Contributor Author

@scoder scoder Apr 28, 2021

Choose a reason for hiding this comment

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

I don't think this C-API function is the right place to document these details. That's what the gc module is for.

If the garbage collector is disabled or already running,
returns ``0`` immediately.
Comment thread
scoder marked this conversation as resolved.
Outdated
Errors during garbage collection are ignored and printed.
Comment thread
scoder marked this conversation as resolved.
Outdated
This function does not raise exceptions.
Copy link
Copy Markdown
Member

@vstinner vstinner Apr 28, 2021

Choose a reason for hiding this comment

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

@pablogsal: Do we want to document that it's safe to call this function with an exception raised, and that the exception is saved and then restored?



.. c:function:: int PyGC_Enable(void)

Enable the garbage collector.
Comment thread
scoder marked this conversation as resolved.
Outdated
Returns the previous state, 0 for disabled and 1 for enabled.

.. versionchanged:: 3.10
Comment thread
scoder marked this conversation as resolved.
Outdated


.. c:function:: int PyGC_Disable(void)

Disable the garbage collector.
Comment thread
scoder marked this conversation as resolved.
Outdated
Returns the previous state, 0 for disabled and 1 for enabled.

.. versionchanged:: 3.10


.. c:function:: int PyGC_IsEnabled(void)

Queries the state of the garbage collector.
Returns the current state, 0 for disabled and 1 for enabled.

.. versionchanged:: 3.10