Memory: Reference Counting and Garbage Collection

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Reference count

A number stored on each object: how many things point at it. At zero the object is freed.

Garbage collection

Automatically freeing memory that the program can no longer reach.

Reference cycle

Objects that point at each other in a loop, so their counts never reach zero by themselves.

Cycle collector

The part of CPython (gc module) that finds and frees unreachable cycles.

Weak reference

A pointer that does not keep its target alive. It gives None after the target is freed.

`__del__`

A method called just before an object is freed. Rarely needed, easy to get wrong.

Memory leak

Memory that is never freed because something still references it.

Immortal object

In 3.12 and later, objects such as None and small ints have a fixed count that never changes.

1. 1

   Count references yourself

   In the first example, add z = {"k": x} after y = x and print the difference again. A dict value counts as a reference too. Then del z and check it drops.

2. 2

   Remove the collector call

   In the second example, delete gc.collect() and add import time; time.sleep(0) at the end. The freed a and freed b lines may move or not appear before the program ends: the objects are freed whenever the collector decides to run. This is why you never depend on __del__ for cleanup in a cycle.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

import weakref

numbers = [1, 2, 3]
ref = weakref.ref(numbers)

1. 1

   Things that add one to the count: a name bound to the object, an item in a list, tuple, set or dict, an attribute of another object, an argument while a function runs, a closure. Things that subtract one: del name, rebinding the name to something else, a name going out of scope when a function returns, removing the item from its container. sys.getrefcount(x) shows the number, but it is always one higher than you expect because passing x to the function adds a temporary reference.

2. 2

   Because freeing is immediate, Python has deterministic cleanup: when the last reference to a file or lock object vanishes, its __del__ runs right then. This is a CPython property, not a language promise. PyPy and others free objects later. For resources like files and locks, always use with and context managers (Topics 7.4 and 9.8) instead of relying on counts.

3. 3

   Reference counting has one weakness: cycles. If object A points to B and B points to A, each keeps the other's count at 1 forever, even when nothing else can reach them. To fix this, CPython has a cycle collector (the gc module). It periodically looks at container objects (lists, dicts, instances) and finds groups that are only reachable from each other, then frees them. You can run it yourself with gc.collect() and pause it with gc.disable().

4. 4

   del x does not delete an object. It removes the name x and lowers the count by one. The object is freed only if that was the last reference. Beginners often write del big_list hoping to 'free memory' while another name or a cache still holds it. The memory then stays.

5. 5

   weakref solves two problems. A weak reference points at an object without raising its count, and returns None once the object is gone. That lets caches, observer lists and parent pointers avoid keeping objects alive. weakref.WeakValueDictionary is a cache that drops entries automatically. Not everything can be weakly referenced: plain list, dict, int, str and tuple objects cannot (a subclass such as class Bag(list): pass can), but ordinary class instances, functions and sets can.

6. 6

   Memory 'leaks' in a garbage-collected language are almost always objects you still reference: a growing global list, a cache with no limit, a default argument, a closure holding a big object, or an exception traceback kept alive. Python gives no free. The fix is to find who still points at the object (gc.get_referrers, tracemalloc in Topic 13.7) and drop or weaken that reference.

• ↔

  Reference counting gives prompt, predictable cleanup but costs time. Every assignment updates a count, which is one reason CPython is slower than a tracing collector for some workloads. The cycle collector adds pauses. (A tracing collector, used by Java and Go, skips the counts and instead walks from the live objects to find what is still reachable.)

• ↔

  Weak references avoid leaks but make objects optional. Code that uses one must handle None (the target may be gone), so use them only where 'it may disappear' is a valid state.

• ↔

  **__del__ versus context managers.** Finalisers run at an unpredictable time in cycles and at exit. with blocks give a guaranteed time. Prefer with.

• Done when you can explain how reference counts rise and fall for a small program.

• Done when you can say why a reference cycle is not freed by counting alone and what frees it.

• Done when you can explain what del really does.

• Done when you can use weakref.ref and WeakValueDictionary correctly.

• Done when you can name three ways a Python program leaks memory and how you would find them.