add comments

Author: kumaraditya303

Include/internal/pycore_typecache.h

@@ -14,22 +14,24 @@ extern "C" {
 #define _Py_TYPECACHE_MINSIZE 8
 
 struct type_cache_entry {
-    PyObject *name;
-    PyObject *value;
+    PyObject *name;     // name of the attribute or method, interned string, NULL if the entry is empty
+    PyObject *value;    // borrowed reference or NULL
 };
 
+// Per-type attribute lookup cache: speed up attribute and method lookups,
+// see _PyTypeCache_Lookup().
 struct type_cache {
-    uint32_t mask;
-    uint32_t version_tag;
-    uint32_t available;
-    uint32_t used;
-    struct type_cache_entry hashtable[1];
+    uint32_t mask;                          // mask for indexing into hashtable, i.e. size of hashtable is mask + 1
+    uint32_t version_tag;                   // initialized from type->tp_version_tag
+    uint32_t available;                     // number of available entries in hashtable
+    uint32_t used;                          // number of used entries in hashtable
+    struct type_cache_entry hashtable[1];   // hashtable entries, the total size is always power of 2 and at least _Py_TYPECACHE_MINSIZE
 };
 
 struct _PyTypeCacheLookupResult {
-    _PyStackRef value;
-    int cache_hit;
-    uint32_t version_tag;
+    _PyStackRef value;      // value is a stack reference to the cached attribute or method, or NULL if not found
+    int cache_hit;          // 1 if the cache entry is valid and matches the type's version tag, 0 otherwise
+    uint32_t version_tag;   // version tag of the type when the value was cached
 };
 
 

Python/typecache.c

@@ -155,18 +155,20 @@ cache_resize(PyTypeObject *type, struct type_cache *cache)
     if (new_cache == NULL) {
         return -1;
     }
-    FT_ATOMIC_STORE_UINT_RELAXED(cache->version_tag, FT_ATOMIC_LOAD_UINT_RELAXED(type->tp_version_tag));
     for (uint32_t i = 0; i < old_size; i++) {
         if (cache->hashtable[i].name != NULL) {
             cache_insert(new_cache, cache->hashtable[i].name,
                               cache->hashtable[i].value);
         }
     }
+    new_cache->version_tag = cache->version_tag;
     cache_set(type, new_cache);
     cache_free_delayed(cache);
     return 0;
 }
 
+// Insert a new entry to the type cache. If the cache is full, resize it before inserting the new entry.
+// The TYPE_LOCK should be held while calling this function.
 void
 _PyTypeCache_Insert(PyTypeObject *type, PyObject *name, PyObject *value)
 {
@@ -185,6 +187,10 @@ _PyTypeCache_Insert(PyTypeObject *type, PyObject *name, PyObject *value)
     FT_ATOMIC_STORE_UINT_RELAXED(cache->version_tag, FT_ATOMIC_LOAD_UINT_RELAXED(type->tp_version_tag));
 }
 
+
+// Lookup the given name in the type cache.
+// The cache is lock-free so it is possible that cache becomes stale during the lookup,
+// to prevent returning stale cache entry, the cache version is compared with the type version tag.
 struct _PyTypeCacheLookupResult
 _PyTypeCache_Lookup(PyTypeObject *type, PyObject *name)
 {
@@ -225,12 +231,13 @@ _PyTypeCache_Lookup(PyTypeObject *type, PyObject *name)
     return (struct _PyTypeCacheLookupResult){out_ref, 1, cache_version};
 }
 
-
+// Invalidate the type cache of the type.
+// The cache is set to the empty cache and the old cache is freed with QSBR.
+// The TYPE_LOCK should be held while calling this function.
 void
 _PyTypeCache_Invalidate(PyTypeObject *type)
 {
     struct type_cache *cache = cache_get(type);
-    // if the type was modified, the cache is set to the empty cache and the old cache is freed after a delay.
     cache_set(type, &empty_cache);
     cache_free_delayed(cache);
 }