Adding Deep Immutability to 3.12

.gitignore

@@ -156,3 +156,6 @@ Python/frozen_modules/MANIFEST
 # Ignore ./python binary on Unix but still look into ./Python/ directory.
 /python
 !/Python/
+
+# Ignore the build directory.
+build*

Include/Python.h

@@ -105,5 +105,6 @@
 #include "fileutils.h"
 #include "cpython/pyfpe.h"
 #include "tracemalloc.h"
+#include "immutability.h"
 
 #endif /* !Py_PYTHON_H */

Include/cpython/immutability.h

@@ -0,0 +1,8 @@
+#ifndef Py_CPYTHON_IMMUTABLE_H
+#  error "this header file must not be included directly"
+#endif
+
+PyAPI_DATA(PyTypeObject) _PyNotFreezable_Type;
+
+PyAPI_FUNC(int) _PyImmutability_Freeze(PyObject*);
+PyAPI_FUNC(int) _PyImmutability_RegisterFreezable(PyTypeObject*);

Include/cpython/object.h

@@ -273,6 +273,7 @@ typedef struct _heaptypeobject {
 PyAPI_FUNC(const char *) _PyType_Name(PyTypeObject *);
 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *);
 PyAPI_FUNC(PyObject *) _PyType_LookupId(PyTypeObject *, _Py_Identifier *);
+PyAPI_FUNC(int) _PyType_HasExtensionSlots(PyTypeObject *);
 PyAPI_FUNC(PyObject *) _PyObject_LookupSpecialId(PyObject *, _Py_Identifier *);
 #ifndef Py_BUILD_CORE
 // Backward compatibility for 3rd-party extensions

Include/cpython/pylifecycle.h

@@ -51,7 +51,6 @@ Py_DEPRECATED(3.11) PyAPI_FUNC(void) _Py_SetProgramFullPath(const wchar_t *);
 PyAPI_FUNC(const char *) _Py_gitidentifier(void);
 PyAPI_FUNC(const char *) _Py_gitversion(void);
 
-PyAPI_FUNC(int) _Py_IsFinalizing(void);
 PyAPI_FUNC(int) _Py_IsInterpreterFinalizing(PyInterpreterState *interp);
 
 /* Random */

Include/immutability.h

@@ -0,0 +1,19 @@
+#ifndef Py_IMMUTABILITY_H
+#define Py_IMMUTABILITY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+#ifndef Py_LIMITED_API
+#  define Py_CPYTHON_IMMUTABLE_H
+#  include "cpython/immutability.h"
+#  undef Py_CPYTHON_IMMUTABLE_H
+#endif
+
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_IMMUTABILITY_H */

Include/internal/pycore_immutability.h

@@ -0,0 +1,21 @@
+#ifndef Py_INTERNAL_IMMUTABILITY_H
+#define Py_INTERNAL_IMMUTABILITY_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+#  error "Py_BUILD_CORE must be defined to include this header"
+#endif
+
+struct _Py_immutability_state {
+    PyObject *module_locks;
+    PyObject *blocking_on;
+    PyObject *freezable_types;
+    PyObject *destroy_cb;
+};
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_INTERNAL_IMMUTABILITY_H */

Include/internal/pycore_interp.h

@@ -25,6 +25,7 @@ extern "C" {
 #include "pycore_gc.h"            // struct _gc_runtime_state
 #include "pycore_global_objects.h"  // struct _Py_interp_static_objects
 #include "pycore_import.h"        // struct _import_state
+#include "pycore_immutability.h"    // struct _immutability_runtime_state
 #include "pycore_instruments.h"   // _PY_MONITORING_EVENTS
 #include "pycore_list.h"          // struct _Py_list_state
 #include "pycore_object_state.h"   // struct _py_object_state
@@ -176,6 +177,7 @@ struct _is {
     struct _Py_async_gen_state async_gen;
     struct _Py_context_state context;
     struct _Py_exc_state exc_state;
+    struct _Py_immutability_state immutability;
 
     struct ast_state ast;
     struct types_state types;

Include/internal/pycore_object.h

@@ -71,7 +71,7 @@ static inline void _Py_RefcntAdd(PyObject* op, Py_ssize_t n)
 static inline void _Py_SetImmortal(PyObject *op)
 {
     if (op) {
-        op->ob_refcnt = _Py_IMMORTAL_REFCNT;
+        op->ob_refcnt = (op->ob_refcnt & _Py_IMMUTABLE_MASK) | _Py_IMMORTAL_REFCNT;
     }
 }
 #define _Py_SetImmortal(op) _Py_SetImmortal(_PyObject_CAST(op))
@@ -80,7 +80,8 @@ static inline void _Py_SetImmortal(PyObject *op)
 static inline void _Py_ClearImmortal(PyObject *op)
 {
     if (op) {
-        assert(op->ob_refcnt == _Py_IMMORTAL_REFCNT);
+        assert((op->ob_refcnt & _Py_REFCNT_MASK) == _Py_IMMORTAL_REFCNT);
+        // note this also clears the _Py_IMMUTABLE_FLAG, if set
         op->ob_refcnt = 1;
         Py_DECREF(op);
     }
@@ -91,17 +92,33 @@ static inline void _Py_ClearImmortal(PyObject *op)
         op = NULL; \
     } while (0)
 
+static inline void _Py_SetImmutable(PyObject *op)
+{
+    if(op) {
+        op->ob_refcnt |= _Py_IMMUTABLE_FLAG;
+    }
+}
+#define _Py_SetImmutable(op) _Py_SetImmutable(_PyObject_CAST(op))
+
 static inline void
 _Py_DECREF_SPECIALIZED(PyObject *op, const destructor destruct)
 {
-    if (_Py_IsImmortal(op)) {
+    if (_Py_IsImmortalOrImmutable(op)) {
+        if (_Py_IsImmortal(op)) {
+            return;
+        }
+        assert(_Py_IsImmutable(op));
+        if (_Py_DecRef_Immutable(op)) {
+            destruct(op);
+        }
         return;
     }
     _Py_DECREF_STAT_INC();
 #ifdef Py_REF_DEBUG
     _Py_DEC_REFTOTAL(_PyInterpreterState_GET());
 #endif
-    if (--op->ob_refcnt != 0) {
+    op->ob_refcnt -= 1;
+    if ((op->ob_refcnt & _Py_REFCNT_MASK) != 0) {
         assert(op->ob_refcnt > 0);
     }
     else {
@@ -115,7 +132,11 @@ _Py_DECREF_SPECIALIZED(PyObject *op, const destructor destruct)
 static inline void
 _Py_DECREF_NO_DEALLOC(PyObject *op)
 {
-    if (_Py_IsImmortal(op)) {
+    if (_Py_IsImmortalOrImmutable(op)) {
+        if (_Py_IsImmortal(op)) {
+            return;
+        }
+        _Py_DecRef_Immutable(op);
         return;
     }
     _Py_DECREF_STAT_INC();

Include/object.h

@@ -78,6 +78,25 @@ whose size is determined when the object is allocated.
 /* PyObject_HEAD defines the initial segment of every PyObject. */
 #define PyObject_HEAD                   PyObject ob_base;
 
+/*
+Immutability:
+
+Immutability is tracked in the top bit of the reference count. The immutability
+system also uses the second-to-top bit for managing immutable graphs.
+*/
+
+#if SIZEOF_VOID_P > 4
+#define _Py_REFCNT_MASK 0xFFFFFFFF
+#define _Py_IMMUTABLE_FLAG 0x4000000000
+#define _Py_IMMUTABLE_SCC_FLAG 0x8000000000
+#else
+#define _Py_REFCNT_MASK 0x1FFFFFFF
+#define _Py_IMMUTABLE_FLAG 0x20000000
+#define _Py_IMMUTABLE_SCC_FLAG 0x40000000
+#endif
+
+#define _Py_IMMUTABLE_MASK (_Py_IMMUTABLE_SCC_FLAG | _Py_IMMUTABLE_FLAG)
+
 /*
 Immortalization:
 
@@ -112,17 +131,17 @@ be done by checking the bit sign flag in the lower 32 bits.
 #else
 /*
 In 32 bit systems, an object will be marked as immortal by setting all of the
-lower 30 bits of the reference count field, which is equal to: 0x3FFFFFFF
+lower 28 bits of the reference count field, which is equal to: 0x0FFFFFFF.
 
-Using the lower 30 bits makes the value backwards compatible by allowing
+Using the lower 28 bits makes the value backwards compatible by allowing
 C-Extensions without the updated checks in Py_INCREF and Py_DECREF to safely
 increase and decrease the objects reference count. The object would lose its
 immortality, but the execution would still be correct.
 
 Reference count increases and decreases will first go through an immortality
 check by comparing the reference count field to the immortality reference count.
 */
-#define _Py_IMMORTAL_REFCNT (UINT_MAX >> 2)
+#define _Py_IMMORTAL_REFCNT (UINT_MAX >> 4)
 #endif
 
 // Make all internal uses of PyObject_HEAD_INIT immortal while preserving the
@@ -208,7 +227,7 @@ PyAPI_FUNC(int) Py_Is(PyObject *x, PyObject *y);
 
 
 static inline Py_ssize_t Py_REFCNT(PyObject *ob) {
-    return ob->ob_refcnt;
+    return ob->ob_refcnt & _Py_REFCNT_MASK;
 }
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
 #  define Py_REFCNT(ob) Py_REFCNT(_PyObject_CAST(ob))
@@ -242,7 +261,7 @@ static inline Py_ALWAYS_INLINE int _Py_IsImmortal(PyObject *op)
 #if SIZEOF_VOID_P > 4
     return _Py_CAST(PY_INT32_T, op->ob_refcnt) < 0;
 #else
-    return op->ob_refcnt == _Py_IMMORTAL_REFCNT;
+    return (op->ob_refcnt & _Py_REFCNT_MASK) == _Py_IMMORTAL_REFCNT;
 #endif
 }
 #define _Py_IsImmortal(op) _Py_IsImmortal(_PyObject_CAST(op))
@@ -254,16 +273,44 @@ static inline int Py_IS_TYPE(PyObject *ob, PyTypeObject *type) {
 #  define Py_IS_TYPE(ob, type) Py_IS_TYPE(_PyObject_CAST(ob), (type))
 #endif
 
+static inline Py_ALWAYS_INLINE int _Py_IsImmutable(PyObject *op)
+{
+    return (op->ob_refcnt & _Py_IMMUTABLE_MASK) > 0;
+}
+#define _Py_IsImmutable(op) _Py_IsImmutable(_PyObject_CAST(op))
+
+// Check whether an object is writeable.
+// This check will always succeed during runtime finalization.
+#define Py_CHECKWRITE(op) ((op) && (!_Py_IsImmutable(op) || Py_IsFinalizing()))
+#define Py_REQUIREWRITE(op, msg) {if (Py_CHECKWRITE(op)) { _PyObject_ASSERT_FAILED_MSG(op, msg); }}
+
+static inline Py_ALWAYS_INLINE int _Py_IsImmortalOrImmutable(PyObject *op)
+{
+    // TODO(Immutable): Does this work for both 32 and 64bit?
+    return op->ob_refcnt >= _Py_IMMORTAL_REFCNT;
+}
+#define _Py_IsImmortalOrImmutable(op) _Py_IsImmortalOrImmutable(_PyObject_CAST(op))
 
 static inline void Py_SET_REFCNT(PyObject *ob, Py_ssize_t refcnt) {
     // This immortal check is for code that is unaware of immortal objects.
     // The runtime tracks these objects and we should avoid as much
     // as possible having extensions inadvertently change the refcnt
     // of an immortalized object.
-    if (_Py_IsImmortal(ob)) {
+    if (_Py_IsImmortalOrImmutable(ob))
+    {
+        if (_Py_IsImmortal(ob)) {
+            return;
+        }
+        assert(_Py_IsImmutable(ob));
+        // TODO(Immutable): It is dangerous to set the reference count of an
+        // immutable object. The majority of calls appear to be where the rc
+        // has reached 0 and a finalizer is running. This seems a reasonable
+        // place to allow the refcnt to be set to 1, and clear the immutable flag.
+        assert((ob->ob_refcnt & _Py_REFCNT_MASK) == 0);
+        ob->ob_refcnt = refcnt;
         return;
     }
-    ob->ob_refcnt = refcnt;
+    ob->ob_refcnt = (ob->ob_refcnt & _Py_IMMUTABLE_MASK) | (refcnt & _Py_REFCNT_MASK);
 }
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
 #  define Py_SET_REFCNT(ob, refcnt) Py_SET_REFCNT(_PyObject_CAST(ob), (refcnt))
@@ -622,6 +669,8 @@ PyAPI_FUNC(void) Py_DecRef(PyObject *);
 PyAPI_FUNC(void) _Py_IncRef(PyObject *);
 PyAPI_FUNC(void) _Py_DecRef(PyObject *);
 
+PyAPI_FUNC(int) _Py_DecRef_Immutable(PyObject *op);
+
 static inline Py_ALWAYS_INLINE void Py_INCREF(PyObject *op)
 {
 #if defined(Py_LIMITED_API) && (Py_LIMITED_API+0 >= 0x030c0000 || defined(Py_REF_DEBUG))
@@ -682,12 +731,21 @@ static inline void Py_DECREF(const char *filename, int lineno, PyObject *op)
     if (op->ob_refcnt <= 0) {
         _Py_NegativeRefcount(filename, lineno, op);
     }
-    if (_Py_IsImmortal(op)) {
+
+    if (_Py_IsImmortalOrImmutable(op))
+    {
+        if (_Py_IsImmortal(op)) {
+            return;
+        }
+        assert(_Py_IsImmutable(op));
+        if (_Py_DecRef_Immutable(op))
+          _Py_Dealloc(op);
         return;
     }
     _Py_DECREF_STAT_INC();
     _Py_DECREF_DecRefTotal();
-    if (--op->ob_refcnt == 0) {
+    op->ob_refcnt -= 1;
+    if ((op->ob_refcnt & _Py_REFCNT_MASK) == 0) {
         _Py_Dealloc(op);
     }
 }
@@ -698,11 +756,19 @@ static inline Py_ALWAYS_INLINE void Py_DECREF(PyObject *op)
 {
     // Non-limited C API and limited C API for Python 3.9 and older access
     // directly PyObject.ob_refcnt.
-    if (_Py_IsImmortal(op)) {
+    if (_Py_IsImmortalOrImmutable(op))
+    {
+        if (_Py_IsImmortal(op)) {
+            return;
+        }
+        assert(_Py_IsImmutable(op));
+        if (_Py_DecRef_Immutable(op))
+            _Py_Dealloc(op);
         return;
     }
     _Py_DECREF_STAT_INC();
-    if (--op->ob_refcnt == 0) {
+    op->ob_refcnt -= 1;
+    if ((op->ob_refcnt & _Py_REFCNT_MASK) == 0) {
         _Py_Dealloc(op);
     }
 }

Include/pyerrors.h

@@ -168,6 +168,8 @@ PyAPI_DATA(PyObject *) PyExc_ResourceWarning;
 PyAPI_FUNC(int) PyErr_BadArgument(void);
 PyAPI_FUNC(PyObject *) PyErr_NoMemory(void);
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrno(PyObject *);
+PyAPI_FUNC(PyObject *) _PyErr_WriteToImmutable(PyObject *);
+#define PyErr_WriteToImmutable(op) _PyErr_WriteToImmutable(_PyObject_CAST(op))
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilenameObject(
     PyObject *, PyObject *);
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000

Include/pylifecycle.h

@@ -16,6 +16,7 @@ PyAPI_FUNC(void) Py_Finalize(void);
 PyAPI_FUNC(int) Py_FinalizeEx(void);
 #endif
 PyAPI_FUNC(int) Py_IsInitialized(void);
+PyAPI_FUNC(int) Py_IsFinalizing(void);
 
 /* Subinterpreter support */
 PyAPI_FUNC(PyThreadState *) Py_NewInterpreter(void);

Lib/test/test_freeze/__init__.py

@@ -0,0 +1,6 @@
+import os
+from test.support import load_package_tests
+
+
+def load_tests(*args):
+    return load_package_tests(os.path.dirname(__file__), *args)

Lib/test/test_freeze/__main__.py

@@ -0,0 +1,4 @@
+from . import load_tests
+import unittest
+
+unittest.main()

Lib/test/test_freeze/mock.py

@@ -0,0 +1 @@
+a = 1