What does the return value of gc.collect() actually mean?

Question

When I do gc.collect() in my Python script, it returns values like 86, 14, etc.

I understand that this call performs garbage collection and I've already gone through the documentation here. But can someone explain through an example what do the numbers actually mean?

Answer 1

As you're being chided about for not reading yourself ;-) , it returns "the number of unreachable objects". But the docs aren't really detailed enough to know exactly what that means.

It's really the sum of two numbers: the number of objects that were identified as garbage and actually freed, plus the number of objects that were identified as garbage but could not be freed. For an example of the latter, objects directly involved in unreachable ("garbage") reference cycles containing at least one object with a __del__ method could not be freed automatically before Python 3.4.

Here's an example under Python 3.6.5:

>>> gc.collect() # no trash to begin with
0
>>> a = []
>>> a.append(a) # create an object that references itself
>>> gc.collect()  # but it's not trash because name "a" is bound to it
0
>>> a = None  # break the binding; _now_ it's trash
              # but refcounting alone can't discover that it's trash
>>> gc.collect() # .collect() finds this cyclic trash
1                # and reports that one trash object was collected

In general, there's scant use for this return value.