python · encukou · May 17, 2025 · May 17, 2025
diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst
@@ -215,21 +215,36 @@ multiple interpreters correctly. If this is not yet the case for your
 module, you can explicitly make your module loadable only once per
 process. For example::

+   // A process-wide flag
   static int loaded = 0;

+   // Mutex to provide thread safety (only needed for free-threaded Python)
+   static PyMutex modinit_mutex = {0};
+
   static int
   exec_module(PyObject* module)
   {
+       PyMutex_Lock(&modinit_mutex);
       if (loaded) {
+           PyMutex_Unlock(&modinit_mutex);
           PyErr_SetString(PyExc_ImportError,
                           "cannot load module more than once per process");
           return -1;
       }
       loaded = 1;
+       PyMutex_Unlock(&modinit_mutex);
       // ... rest of initialization
   }


+If your module's :c:member:`PyModuleDef.m_clear` function is able to prepare
+for future re-initialization, it should clear the ``loaded`` flag.
+In this case, your module won't support multiple instances existing
+*concurrently*, but it will, for example, support being loaded after
+Python runtime shutdown (:c:func:`Py_FinalizeEx`) and re-initialization
+(:c:func:`Py_Initialize`).
+
+
 Module State Access from Functions
 ----------------------------------