Update docstrings and comments

Author: JukkaL

mypyc/codegen/emitclass.py

@@ -189,7 +189,18 @@ def generate_class_type_decl(
 def generate_class_reuse(
     cl: ClassIR, c_emitter: Emitter, external_emitter: Emitter, emitter: Emitter
 ) -> None:
+    """Generate a definition of a single-object per-class free "list".
+
+    This speeds up object allocation and freeing when there are many short-lived
+    objects.
+
+    TODO: Generalize to support a free list with up to N objects.
+    """
     assert cl.reuse_freed_instance
+
+    # The free list implementation doesn't support class hierarchies
+    assert cl.is_final_class or cl.children == []
+
     context = c_emitter.context
     name = cl.name_prefix(c_emitter.names) + "_free_instance"
     struct_name = cl.struct_name(c_emitter.names)
@@ -838,10 +849,16 @@ def generate_dealloc_for_class(
 
 
 def emit_reuse_dealloc(cl: ClassIR, emitter: Emitter) -> None:
+    """Emit code to deallocate object by putting it to per-type free list.
+
+    The free "list" currently can have up to one object.
+    """
     prefix = cl.name_prefix(emitter.names)
     emitter.emit_line(f"if ({prefix}_free_instance == NULL) {{")
     emitter.emit_line(f"{prefix}_free_instance = self;")
 
+    # Clear attributes and free referenced objects.
+
     emit_clear_bitmaps(cl, emitter)
 
     for base in reversed(cl.base_mro):

mypyc/ir/class_ir.py

@@ -206,7 +206,8 @@ def __init__(
 
         # If True, keep one freed, cleared instance available for immediate reuse to
         # speed up allocations. This helps if many objects are freed quickly, before
-        # other instances of the same class are allocated.
+        # other instances of the same class are allocated. This is effectively a
+        # per-type free "list" of up to length 1.
         self.reuse_freed_instance = False
 
     def __repr__(self) -> str:

mypyc/lib-rt/mypyc_util.h

@@ -38,7 +38,7 @@
 #elif defined(_MSC_VER)
 #define CPyThreadLocal __declspec(thread)
 
-// 3.  GNU thread local storage for GCC/Clang targets that still need it
+// 3. GNU thread local storage for GCC/Clang targets that still need it
 #elif defined(__GNUC__) || defined(__clang__)
 #define CPyThreadLocal __thread