Update GC docs for incremental collection. #1379

markshannon · 2024-08-23T16:27:43Z

📚 Documentation preview 📚: https://cpython-devguide--1379.org.readthedocs.build/

brandtbucher

Thanks for taking the time to do this. A couple of notes:

(Also, @savannahostrowski: this PR diff is a good summary of the differences between the GC implementation you've been working with and the current devguide article, which is outdated.)

brandtbucher · 2024-08-23T19:28:36Z

internals/garbage-collector.rst

+
+
+To collect all unreachable cycles in the heap, the garbage collector must scan the
+whole heap. This whole heap scan is called a cycle.


Maybe consider a different term here (and throughout below) since "cycle" already has an important meaning here and it can be confusing if we overload it:

Suggested change

whole heap. This whole heap scan is called a cycle.

whole heap. This whole heap scan is called a full collection.

Maybe instead of cycle use "full scavenge".

A collection is an increment, so that's not a good term.
Cycle is overloaded, so that's not great either.
"Scavenge" is the least ambiguous, but obscure.

Anyone have any other suggestions? I'll go with "scavenge" if not.

brandtbucher · 2024-08-23T19:30:29Z

internals/garbage-collector.rst

+* All any objects reachable from those objects that have not yet been scanned this cycle.
+
+Any objects surviving this collection are moved to the old generation.
+ollection from cycles.


Suggested change

ollection from cycles.

brandtbucher · 2024-08-23T19:31:38Z

internals/garbage-collector.rst

+* The oldest fraction of the old generation
+* All any objects reachable from those objects that have not yet been scanned this cycle.
+
+Any objects surviving this collection are moved to the old generation.


Maybe clarify that the objects that started in the old generation are considered "youngest of the old" instead of "oldest of the old" now (there's probably a better way of phrasing it).

It isn't really the oldest, it is the "least recently scanned". I'll rework this section.

willingc · 2024-08-23T21:06:04Z

internals/garbage-collector.rst

+implementation for the default build uses incremental collection with two
+generations.
+
+The purpose of generations is to take advantage of what is known as the weak


Suggested change

The purpose of generations is to take advantage of what is known as the weak

Generational garbage collection takes advantage of what is known as the weak

willingc · 2024-08-23T21:12:45Z

internals/garbage-collector.rst

+two generations: young and old. Every new object starts in the young generation.
+
+
+To collect all unreachable cycles in the heap, the garbage collector must scan the


Perhaps add detection as distinct from collection.

Suggested change

To collect all unreachable cycles in the heap, the garbage collector must scan the

To detect and collect all unreachable cycles in the heap, the garbage collector must scan the

willingc · 2024-08-23T21:22:20Z

internals/garbage-collector.rst

+To collect all unreachable cycles in the heap, the garbage collector must scan the
+whole heap. This whole heap scan is called a cycle.
+
+In order to limit the time each garbage collection takes, the previous algorithm


Suggested change

In order to limit the time each garbage collection takes, the previous algorithm

To limit the time each garbage collection takes, the detection and collection algorithm

willingc · 2024-08-23T21:25:58Z

internals/garbage-collector.rst

+
+* The young generation
+* The oldest fraction of the old generation
+* All any objects reachable from those objects that have not yet been scanned this cycle.


Suggested change

* All any objects reachable from those objects that have not yet been scanned this cycle.

* All objects reachable from those objects that have not yet been scanned this cycle.

willingc · 2024-08-23T21:43:09Z

internals/garbage-collector.rst

+
+
+To collect all unreachable cycles in the heap, the garbage collector must scan the
+whole heap. This whole heap scan is called a cycle.


Maybe instead of cycle use "full scavenge".

internals/garbage-collector.rst

savannahostrowski · 2024-08-24T19:48:59Z

internals/garbage-collector.rst

+When all objects in the heap have been scanned a cycle ends, and all objects are
+considered unscanned again.
+
+In order to collect all unreachable cycles, each increment must contain all of


To make sure that I understand this section on unreachable cycles, I think you're saying that we want to ensure that we fully capture the unreachable cycle because we want to ensure that the cycle is either fully gc'd or not, to avoid partial processing, which could be problematic later on?

If so, maybe it's worth mentioning explicitly.

If we don't scan the full cycle at once, we cannot collect it. It is otherwise safe.

The old generational collector would scan part cycles all the time; it just delayed the collection of the cycle, at worst until a full collection.

With the incremental collector, if we only scan part of a cycle, it may never be collected. Which would be a problem.

markshannon · 2024-08-27T08:53:27Z

Thanks for the comments and suggestions.

pablogsal · 2024-08-27T20:47:34Z

internals/garbage-collector.rst

+Survivors are moved to the back of the scanned list. The old part of increment is taken
+from the front of the unscanned list.
+
+When a cycle starts, no objects in the heap are considered to have been scanned.


Using cycle of a "reference cycle" and a "gc execution" it's a bit confusing, can we use other terminology?

I've used "full scavenge"

pablogsal · 2024-08-27T20:48:53Z

internals/garbage-collector.rst

+In order to make sure that the whole of any unreachable cycle is contained in an
+increment,  all unscanned objects reachable from any object in the increment must
+be included in the increment.
+Thus, to form a complete increment we perform a transitive closure over reachable,


As much as I enjoy proper terminology myself. Many people reading this document may not immediately know what a transitive closure is, could you add a brief explanation in parentheses or just explain the process?

pablogsal · 2024-08-27T20:50:06Z

internals/garbage-collector.rst

+
+* The young generation
+* The least recently scanned fraction of the old generation.
+* All objects reachable from those objects that have not yet been scanned this cycle.


Same as my other comments about "cycle"

pablogsal · 2024-08-27T21:05:32Z

internals/garbage-collector.rst

+unscanned objects from the initial increment.
+We can exclude scanned objects, as they must have been reachable when scanned.
+If a scanned object becomes part of an unreachable cycle after being scanned, it
+will not be collected this cycle, but it will be collected next cycle.


I think this can benefit from a concrete simple example showing how this can happen and how will be eventually cleaned. Either in English or with some diagram or pseudo code

willingc · 2024-08-28T23:19:39Z

internals/garbage-collector.rst

-generations.  Every collection operates on the entire heap.
+two generations: young and old. Every new object starts in the young generation.
+
+To detect and collect all unreachable cycles in the heap, the garbage collector


Perhaps use objects instead of cycles here.

Suggested change

To detect and collect all unreachable cycles in the heap, the garbage collector

To detect and collect all unreachable objects in the heap, the garbage collector

willingc · 2024-08-28T23:24:58Z

internals/garbage-collector.rst

+of three parts:
+
+* The young generation
+* The least recently scanned fraction of the old generation.


Suggested change

* The least recently scanned fraction of the old generation.

* The old generation's least recently scanned heap found in the scanned objects list

willingc · 2024-08-28T23:29:37Z

internals/garbage-collector.rst

+
+* The young generation
+* The least recently scanned fraction of the old generation.
+* All objects reachable from those objects that have not yet been scanned this cycle.


Suggested change

* All objects reachable from those objects that have not yet been scanned this cycle.

* All objects reachable from those objects that have not yet been scanned.

willingc · 2024-08-28T23:31:36Z

internals/garbage-collector.rst

+* The least recently scanned fraction of the old generation.
+* All objects reachable from those objects that have not yet been scanned this cycle.
+
+Any objects surviving this collection are moved to the old generation.


Suggested change

Any objects surviving this collection are moved to the old generation.

Any young generation objects surviving this collection are moved to the old generation, and reachable objects in the old generation remain in the old generation.

willingc · 2024-08-28T23:32:58Z

internals/garbage-collector.rst

+* All objects reachable from those objects that have not yet been scanned this cycle.
+
+Any objects surviving this collection are moved to the old generation.
+The old generation is composed of two lists, scanned and unscanned.


Suggested change

The old generation is composed of two lists, scanned and unscanned.

The old generation is composed of two lists: scanned increments and unscanned.

internals/garbage-collector.rst

mr-bronson · 2024-09-04T11:57:13Z

Please note the inconsistency in argument or variable names:

This devguide speaks of threshold_0 and threshold_1 (note the underscore), but also threshold2 (no underscore). If the aim is to match the main gc documentation, the underscores should be omitted.

willingc · 2024-09-09T23:22:00Z

internals/garbage-collector.rst

+If a scanned object becomes part of an unreachable cycle after being scanned, it
+will not be collected this cycle, but it will be collected next cycle.
+
+The GC implementation for the free-threaded build does not use incremental collection.


This probably should be called out in an Important block.

willingc · 2024-09-09T23:22:23Z

internals/garbage-collector.rst

+will not be collected this cycle, but it will be collected next cycle.
+
+The GC implementation for the free-threaded build does not use incremental collection.
+Every collection operates on the entire heap.

 In order to decide when to run, the collector keeps track of the number of object
 allocations and deallocations since the last collection. When the number of
 allocations minus the number of deallocations exceeds ``threshold_0``,


Suggested change

allocations minus the number of deallocations exceeds ``threshold_0``,

allocations minus the number of deallocations exceeds ``threshold0``,

willingc · 2024-09-09T23:24:04Z

internals/garbage-collector.rst

+collection starts. ``threshold_1`` determines the fraction of the old
+collection that is included in the increment.
+The fraction is inversely proportional to ``threshold_1``,
+as historically a larger ``threshold_1`` meant that old generation
+collections were performed less frequency.
+``threshold2`` is ignored.


Correct as mentioned in @mr-bronson's message. Good catch @mr-bronson. 😄

Suggested change

collection starts. ``threshold_1`` determines the fraction of the old

collection that is included in the increment.

The fraction is inversely proportional to ``threshold_1``,

as historically a larger ``threshold_1`` meant that old generation

collections were performed less frequency.

``threshold2`` is ignored.

collection starts. ``threshold1`` determines the fraction of the old

collection that is included in the increment.

The fraction is inversely proportional to ``threshold1``,

as historically a larger ``threshold1`` meant that old generation

collections were performed less frequency.

``threshold2`` is ignored.

willingc

Changes look good to me! Thanks @markshannon.

pablogsal · 2024-09-30T13:41:03Z

Let's hold until we figure out https://discuss.python.org/t/incremental-gc-and-pushing-back-the-3-13-0-release/65285

willingc · 2024-10-11T21:18:38Z

Garbage collection doc has been moved to the CPython repo. Unless there is an objection, I recommend closing this devguide issue.

hugovk · 2024-10-15T13:09:49Z

internals/garbage-collector.rst

@@ -399,6 +439,10 @@ more information. These thresholds can be examined using the
 The content of these generations can be examined using the
 ``gc.get_objects(generation=NUM)`` function and collections can be triggered
 specifically in a generation by calling ``gc.collect(generation=NUM)``.
+Prior to 3.13, there we three generations. For that reason the


Suggested change

Prior to 3.13, there we three generations. For that reason the

Prior to 3.14, there we three generations. For that reason the

markshannon added 2 commits August 23, 2024 17:26

Update GC docs

3fd5f0b

Fix link

87f8466

brandtbucher reviewed Aug 23, 2024

View reviewed changes

willingc reviewed Aug 23, 2024

View reviewed changes

savannahostrowski reviewed Aug 24, 2024

View reviewed changes

Address review comments

481562c

markshannon mentioned this pull request Aug 27, 2024

Document the new incremental GC python/cpython#117759

Open

3 tasks

pablogsal reviewed Aug 27, 2024

View reviewed changes

willingc reviewed Aug 28, 2024

View reviewed changes

internals/garbage-collector.rst Show resolved Hide resolved

willingc reviewed Sep 9, 2024

View reviewed changes

markshannon added 2 commits September 23, 2024 17:00

Address review comments

357783d

Remove trailing whitespace

d724cfa

willingc approved these changes Sep 25, 2024

View reviewed changes

hugovk reviewed Oct 15, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update GC docs for incremental collection. #1379

Update GC docs for incremental collection. #1379

markshannon commented Aug 23, 2024 •

edited by github-actions bot

Loading

brandtbucher left a comment •

edited

Loading

brandtbucher Aug 23, 2024

willingc Aug 23, 2024

markshannon Aug 27, 2024

brandtbucher Aug 23, 2024

brandtbucher Aug 23, 2024

markshannon Aug 27, 2024

willingc Aug 23, 2024

willingc Aug 23, 2024

willingc Aug 23, 2024

willingc Aug 23, 2024

willingc Aug 23, 2024

savannahostrowski Aug 24, 2024

markshannon Aug 27, 2024

markshannon commented Aug 27, 2024

pablogsal Aug 27, 2024

markshannon Sep 23, 2024

pablogsal Aug 27, 2024

pablogsal Aug 27, 2024

pablogsal Aug 27, 2024

willingc Aug 28, 2024

willingc Aug 28, 2024 •

edited

Loading

willingc Aug 28, 2024

willingc Aug 28, 2024

willingc Aug 28, 2024

mr-bronson commented Sep 4, 2024

willingc Sep 9, 2024

willingc Sep 9, 2024

willingc Sep 9, 2024

willingc left a comment

pablogsal commented Sep 30, 2024

willingc commented Oct 11, 2024

hugovk Oct 15, 2024



		To collect all unreachable cycles in the heap, the garbage collector must scan the
		whole heap. This whole heap scan is called a cycle.

	The purpose of generations is to take advantage of what is known as the weak
	Generational garbage collection takes advantage of what is known as the weak

		two generations: young and old. Every new object starts in the young generation.


		To collect all unreachable cycles in the heap, the garbage collector must scan the

	To collect all unreachable cycles in the heap, the garbage collector must scan the
	To detect and collect all unreachable cycles in the heap, the garbage collector must scan the

	In order to limit the time each garbage collection takes, the previous algorithm
	To limit the time each garbage collection takes, the detection and collection algorithm

	* All any objects reachable from those objects that have not yet been scanned this cycle.
	* All objects reachable from those objects that have not yet been scanned this cycle.

	To detect and collect all unreachable cycles in the heap, the garbage collector
	To detect and collect all unreachable objects in the heap, the garbage collector

	* The least recently scanned fraction of the old generation.
	* The old generation's least recently scanned heap found in the scanned objects list

	Any objects surviving this collection are moved to the old generation.
	Any young generation objects surviving this collection are moved to the old generation, and reachable objects in the old generation remain in the old generation.

	The old generation is composed of two lists, scanned and unscanned.
	The old generation is composed of two lists: scanned increments and unscanned.

	allocations minus the number of deallocations exceeds ``threshold_0``,
	allocations minus the number of deallocations exceeds ``threshold0``,

	Prior to 3.13, there we three generations. For that reason the
	Prior to 3.14, there we three generations. For that reason the

Update GC docs for incremental collection. #1379

Are you sure you want to change the base?

Update GC docs for incremental collection. #1379

Conversation

markshannon commented Aug 23, 2024 • edited by github-actions bot Loading

brandtbucher left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markshannon commented Aug 27, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

willingc Aug 28, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mr-bronson commented Sep 4, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

willingc left a comment

Choose a reason for hiding this comment

pablogsal commented Sep 30, 2024

willingc commented Oct 11, 2024

Choose a reason for hiding this comment

markshannon commented Aug 23, 2024 •

edited by github-actions bot

Loading

brandtbucher left a comment •

edited

Loading

willingc Aug 28, 2024 •

edited

Loading