From 5f3c9fda1825737fa7b671b995f84a8ab9a4adb8 Mon Sep 17 00:00:00 2001
From: Brandt Bucher <brandtbucher@gmail.com>
Date: Thu, 4 Aug 2022 22:45:05 -0700
Subject: [PATCH] GH-90997: Document CACHEs (GH-95694)

---
 Doc/library/dis.rst   | 18 ++++++++++++++++++
 Doc/whatsnew/3.11.rst |  7 +++++++
 2 files changed, 25 insertions(+)

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 68c3d1c0a4b24b..63b064e7b444ec 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -408,6 +408,24 @@ The Python compiler currently generates the following bytecode instructions.
    .. versionadded:: 3.11
 
 
+.. opcode:: CACHE
+
+   Rather than being an actual instruction, this opcode is used to mark extra
+   space for the interpreter to cache useful data directly in the bytecode
+   itself. It is automatically hidden by all ``dis`` utilities, but can be
+   viewed with ``show_caches=True``.
+
+   Logically, this space is part of the preceding instruction. Many opcodes
+   expect to be followed by an exact number of caches, and will instruct the
+   interpreter to skip over them at runtime.
+
+   Populated caches can look like arbitrary instructions, so great care should
+   be taken when reading or modifying raw, adaptive bytecode containing
+   quickened data.
+
+   .. versionadded:: 3.11
+
+
 **Unary operations**
 
 Unary operations take the top of the stack, apply the operation, and push the
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index c976eddb08ba08..f5d5d5f2be06a0 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -1165,6 +1165,13 @@ contributors are volunteers from the community.
 CPython bytecode changes
 ========================
 
+* The bytecode now contains inline cache entries, which take the form of
+  :opcode:`CACHE` instructions. Many opcodes expect to be followed by an exact
+  number of caches, and instruct the interpreter to skip over them at runtime.
+  Populated caches can look like arbitrary instructions, so great care should be
+  taken when reading or modifying raw, adaptive bytecode containing quickened
+  data.
+
 * Replaced all numeric ``BINARY_*`` and ``INPLACE_*`` instructions with a single
   :opcode:`BINARY_OP` implementation.