Update GC docs for incremental collection. by markshannon · Pull Request #1379 · python/devguide

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

+
+
+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

+* 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

+* 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

+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

+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

+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

+
+* 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

+
+
+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".

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

+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

+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

+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

+
+* 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

+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

-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

+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

+
+* 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

+* 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

+* 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.

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

+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


 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

+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

 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 · 2024-12-06T16:28:21Z

All these docs are now in main

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

Closed

3 tasks done

pablogsal reviewed Aug 27, 2024

View reviewed changes

willingc reviewed Aug 28, 2024

View reviewed changes

Comment thread internals/garbage-collector.rst

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

markshannon closed this Dec 6, 2024

markshannon deleted the update-gc-docs branch December 6, 2024 16:28



		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

Conversation

markshannon commented Aug 23, 2024 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brandtbucher left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markshannon commented Aug 27, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

willingc Aug 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mr-bronson commented Sep 4, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

pablogsal commented Sep 30, 2024

Uh oh!

willingc commented Oct 11, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markshannon commented Dec 6, 2024

Uh oh!

Reviewers

markshannon commented Aug 23, 2024 •

edited by github-actions Bot

Loading

brandtbucher left a comment •

edited

Loading

willingc Aug 28, 2024 •

edited

Loading