PEP 509: document the type version tag

pep-0509.txt

@@ -346,6 +346,39 @@ Other issues:
 Prior Art
 =========
 
+Method cache and type version tag
+---------------------------------
+
+In 2007, Armin Rigo wrote a patch to to implement a cache of methods. It
+was merged into Python 2.6.  The patch adds a "type attribute cache
+version tag" (``tp_version_tag``) and a "valid version tag" flag to
+types (the ``PyTypeObject`` structure).
+
+The type version tag is not available at the Python level.
+
+The version tag has the C type ``unsigned int``. The cache is a global
+hash table of 4096 entries, shared by all types. The cache is global to
+"make it fast, have a deterministic and low memory footprint, and be
+easy to invalidate". Each cache entry has a version tag. A global
+version tag is used to create the next version tag, it also has the C
+type ``unsigned int``.
+
+By default, a type has its "valid version tag" flag cleared to indicate
+that the version tag is invalid. When the first method of the type is
+cached, the version tag and the "valid version tag" flag are set. When a
+type is modified, the "valid version tag" flag of the type and its
+subclasses is cleared. Later, when a cache entry of these types is used,
+the entry is removed because its version tag is outdated.
+
+On integer overflow, the whole cache is cleared and the global version
+tag is reset to ``0``.
+
+See also `issue #1685986: Method cache
+<https://bugs.python.org/issue1685986>`_ and `issue #1700288: Armin's
+method cache optimization updated for Python 2.6
+<https://bugs.python.org/issue1700288>`_.
+
+
 Guard against changing dict during iteration
 --------------------------------------------