[3.13] GH-117759: Document incremental GC (GH-123266) (#123395)

GH-117759: Document incremental GC (GH-123266)

* Update what's new

* Update gc module docs and fix inconsistency in gc.get_objects
(cherry picked from commit f49a91648aac2ad55b2e005ba28fac1c7edca020)

Co-authored-by: Mark Shannon <mark@hotpy.org>

1 files changed, 16 insertions, 11 deletions

diff --git a/Python/gc.c b/Python/gc.c
index de24e48..392c527 100644
--- a/Python/gc.c
+++ b/Python/gc.c
@@ -1701,20 +1701,25 @@ _PyGC_GetObjects(PyInterpreterState *interp, int generation)
     GCState *gcstate = &interp->gc;
 
     PyObject *result = PyList_New(0);
-    if (result == NULL) {
-        return NULL;
+    /* Generation:
+     * -1: Return all objects
+     * 0: All young objects
+     * 1: No objects
+     * 2: All old objects
+     */
+    if (result == NULL || generation == 1) {
+        return result;
     }
-
-    if (generation == -1) {
-        /* If generation is -1, get all objects from all generations */
-        for (int i = 0; i < NUM_GENERATIONS; i++) {
-            if (append_objects(result, GEN_HEAD(gcstate, i))) {
-                goto error;
-            }
+    if (generation <= 0) {
+        if (append_objects(result, &gcstate->young.head)) {
+            goto error;
         }
     }
-    else {
-        if (append_objects(result, GEN_HEAD(gcstate, generation))) {
+    if (generation != 0) {
+        if (append_objects(result, &gcstate->old[0].head)) {
+            goto error;
+        }
+        if (append_objects(result, &gcstate->old[1].head)) {
             goto error;
         }
     }