From 07d97c9e5d674d5d309e789014dbe59cabf7a7dd Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
<31488909+miss-islington@users.noreply.github.com>
Date: Fri, 5 Aug 2022 00:42:49 -0700
Subject: [PATCH] GH-90997: Document CACHEs (GH-95694) (GH-95696)
(cherry picked from commit 5f3c9fda1825737fa7b671b995f84a8ab9a4adb8)
Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
---
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 c303ab9a1ff..f7989ea43da 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -410,6 +410,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 c57f8a0f3e9..0ba88532442 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.
--
GitLab