gh-153410: Add PyDict_AsFrozenDictAndClear C-API

Author: sobolevn

Doc/c-api/dict.rst

@@ -507,6 +507,20 @@ Dictionary objects
       modified by another thread.
 
 
+.. c:function:: PyObject* PyDict_AsFrozenDictAndClear(PyObject *dict)
+
+   Return a new :class:`frozendict` created
+   from the existing :c:type:`PyDictObject` instance.
+   Expects *dict* to be an exact :class:`dict` instance.
+
+   Transfers all keys and values from *dict*
+   to the newly allocated :c:type:`PyFrozenDict` with O(1) complexity.
+   Clears the input *dict* on success.
+   Returns ``NULL`` with the exception set on error.
+
+   .. versionadded:: next
+
+
 .. c:function:: int PyDict_AddWatcher(PyDict_WatchCallback callback)
 
    Register *callback* as a dictionary watcher. Return a non-negative integer

Doc/whatsnew/3.16.rst

@@ -668,7 +668,9 @@ C API changes
 New features
 ------------
 
-* TODO
+* Add a new way to efficitly create :class:`frozendict` instance
+  from existing :class:`dict` instances: :c:func:`PyDict_AsFrozenDictAndClear`.
+
 
 Porting to Python 3.16
 ----------------------

Include/cpython/dictobject.h

@@ -106,3 +106,7 @@ PyAPI_FUNC(int) PyDict_Unwatch(int watcher_id, PyObject* dict);
 
 // Create a frozendict. Create an empty dictionary if iterable is NULL.
 PyAPI_FUNC(PyObject*) PyFrozenDict_New(PyObject *iterable);
+
+// Create a frozendict from existing `PyDictObject`.
+// Transfers existing keys and values.
+PyAPI_FUNC(PyObject*) PyDict_AsFrozenDictAndClear(PyObject *dict);

Lib/test/test_capi/test_dict.py

@@ -609,6 +609,26 @@ def test_dict_popstring(self):
         # CRASHES dict_popstring({}, NULL)
         # CRASHES dict_popstring({"a": 1}, NULL)
 
+    def test_dict_as_frozendict_and_clear(self):
+        # Test PyDict_AsFrozenDictAndClear()
+        check = _testcapi.dict_as_frozendict_and_clear
+        d = {1: 2, 'a': 'b'}
+        f = check(d)
+        self.assertIs(type(f), frozendict)
+        self.assertEqual(f, {1: 2, 'a': 'b'})
+        self.assertIs(type(d), dict)
+        self.assertEqual(d, {})
+
+        d = {}
+        f = check(d)
+        self.assertIs(type(f), frozendict)
+        self.assertEqual(f, {})
+        self.assertIs(type(d), dict)
+        self.assertEqual(d, {})
+        # CRASHES check([])
+        # CRASHES check(frozendict())
+        # CRASHES check(NULL)
+
     def test_frozendict_check(self):
         # Test PyFrozenDict_Check()
         check = _testcapi.frozendict_check

Misc/NEWS.d/next/C_API/2026-07-09-13-52-17.gh-issue-153410.neaDgY.rst

@@ -0,0 +1,3 @@
+Add :c:func:`PyDict_AsFrozenDictAndClear` C-API function to create
+:class:`frozendict` from existing :class:`dict` object and clear the input
+dict instance.

Modules/_testcapi/dict.c

@@ -257,6 +257,13 @@ test_dict_iteration(PyObject* self, PyObject *Py_UNUSED(ignored))
     Py_RETURN_NONE;
 }
 
+static PyObject *
+dict_as_frozendict_and_clear(PyObject *self, PyObject *obj)
+{
+    NULLABLE(obj);
+    return PyDict_AsFrozenDictAndClear(obj);
+}
+
 
 static PyObject *
 frozendict_check(PyObject *self, PyObject *obj)
@@ -306,6 +313,7 @@ static PyMethodDef test_methods[] = {
     {"dict_popstring", dict_popstring, METH_VARARGS},
     {"dict_popstring_null", dict_popstring_null, METH_VARARGS},
     {"test_dict_iteration",     test_dict_iteration,             METH_NOARGS},
+    {"dict_as_frozendict_and_clear", dict_as_frozendict_and_clear, METH_O},
     {"frozendict_check", frozendict_check, METH_O},
     {"frozendict_checkexact", frozendict_checkexact, METH_O},
     {"anydict_check", anydict_check, METH_O},

Objects/dictobject.c

@@ -3120,6 +3120,18 @@ clear_embedded_values(PyDictValues *values, Py_ssize_t nentries)
     }
 }
 
+// This function is used in both `PyDict_Clear`
+// and `PyDict_AsFrozenDictAndClear`, place all the common parts here.
+static void
+clear_common(PyDictObject *mp)
+{
+    /* Empty the dict... */
+    _PyDict_NotifyEvent(PyDict_EVENT_CLEARED, mp, NULL, NULL);
+    // We don't inc ref empty keys because they're immortal
+    ensure_shared_on_resize(mp);
+    STORE_USED(mp, 0);
+}
+
 static void
 clear_lock_held(PyObject *op)
 {
@@ -3138,11 +3150,7 @@ clear_lock_held(PyObject *op)
     if (oldkeys == Py_EMPTY_KEYS) {
         return;
     }
-    /* Empty the dict... */
-    _PyDict_NotifyEvent(PyDict_EVENT_CLEARED, mp, NULL, NULL);
-    // We don't inc ref empty keys because they're immortal
-    ensure_shared_on_resize(mp);
-    STORE_USED(mp, 0);
+    clear_common(mp);
     if (oldvalues == NULL) {
         set_keys(mp, Py_EMPTY_KEYS);
         assert(oldkeys->dk_refcnt == 1);
@@ -8521,6 +8529,50 @@ frozendict_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
     return d;
 }
 
+static void
+transfer_keys_and_values_lock_held(PyObject *res, PyObject *dict)
+{
+
+    PyDictObject *new = (PyDictObject *)res;
+    PyDictObject *old = (PyDictObject *)dict;
+    // Fast path: do nothing on an empty dict:
+    if (old->ma_keys == Py_EMPTY_KEYS) {
+        return;
+    }
+
+    // Transfer keys and values from dict to res:
+    STORE_USED(new, old->ma_used);
+    set_keys(new, old->ma_keys);
+    set_values(new, old->ma_values);
+    ASSERT_CONSISTENT(new);
+
+    // Now, clear the old dict keys and values, but do not decref them:
+    clear_common((PyDictObject *)dict);
+    set_keys(old, Py_EMPTY_KEYS);
+    set_values(old, NULL);
+    ASSERT_CONSISTENT(dict);
+}
+
+PyObject *
+PyDict_AsFrozenDictAndClear(PyObject *dict)
+{
+    assert(dict != NULL);
+    assert(PyDict_CheckExact(dict));
+    assert(can_modify_dict((PyDictObject *)dict));
+    PyObject *res = frozendict_new_untracked(&PyFrozenDict_Type);
+    if (res == NULL) {
+        return NULL;
+    }
+
+    Py_BEGIN_CRITICAL_SECTION(dict);
+    transfer_keys_and_values_lock_held(res, dict);
+    Py_END_CRITICAL_SECTION();
+
+    _PyObject_GC_TRACK(res);
+    assert(_PyFrozenDictObject_CAST(res)->ma_hash == -1);
+    return res;
+}
+
 
 PyObject*
 PyFrozenDict_New(PyObject *iterable)

Python/marshal.c

@@ -1501,7 +1501,7 @@ r_object(RFILE *p)
             Py_CLEAR(v);
         }
         if (type == TYPE_FROZENDICT && v != NULL) {
-            Py_SETREF(v, PyFrozenDict_New(v));
+            Py_SETREF(v, PyDict_AsFrozenDictAndClear(v));
         }
         retval = v;
         break;