docs: add documentation for mod_gil_not_used and multiple_interpreters

docs/advanced/misc.rst

@@ -153,6 +153,72 @@ following checklist.
   within pybind11 that will throw exceptions on certain GIL handling errors
   (reference counting operations).
 
+Free-threading support
+==================================================================
+
+pybind11 supports the experimental free-threaded Python build.  pybind11's internal data
+structures are thread safe. To enable your modules to be used with free-threading, pass the
+:class:`mod_gil_not_used` tag as the third argument to ``PYBIND11_MODULE``.
+
+For example:
+
+.. code-block:: cpp
+    :emphasize-lines: 1
+    PYBIND11_MODULE(example, m, py::mod_gil_not_used()) {
+        py::class_<Animal> animal(m, "Animal");
+        // etc
+    }
+
+Note, of course, enabling your module to be used in free threading is also your promise that
+your code is thread safe. Modules must still be built against the Python free-threading branch to enable
+free-threading, even if they specify this tag.  Adding this tag does not break compatibility with non-free-threaded
+Python.
+
+Sub-interpreter support
+==================================================================
+
+pybind11 supports isolated sub-interpreters.  Pybind11's internal data structures are
+sub-interpreter safe. To enable your modules to be imported in isolated sub-interpreters, pass the
+:func:`multiple_interpreters::per_interpreter_gil()` tag as the third or later argument to
+``PYBIND11_MODULE``.
+
+For example:
+
+.. code-block:: cpp
+    :emphasize-lines: 1
+    PYBIND11_MODULE(example, m, py::mod_gil_not_used(), py::multiple_interpreters_per_interpreter_gil()) {
+        py::class_<Animal> animal(m, "Animal");
+        // etc
+    }
+
+Sub-interpreter Tips:
+
+- Your initialization function will run for each interpreter that imports your module.
+
+- Never share python objects across different sub-interpreters.
+
+- Keep state it in the interpreter's state dict if necessary. Avoid global/static state
+  whenever possible.
+
+- Avoid trying to "cache" python objects in C++ variables across function calls (this is an easy
+  way to accidentally introduce sub-interpreter bugs).
+
+- While sub-interpreters each have their own GIL, there can now be multiple independent GILs in one
+  program so concurrent calls into a module from two different sub-interpreters are still possible.
+  Therefore, your module still needs to consider thread safety.
+
+pybind11 also supports "legacy" sub-interpreters which shared a single global GIL.  You can enable
+legacy behavior by using the :func:`multiple_interpreters::shared_gil()` tag in
+```PYBIND11_MODULE``.
+
+You can explicitly disable multiple interpreter support in your module by using the
+:func:`multiple_interpreter::not_supported()` tag. This is the default behavior if you do not
+specify a multiple_interpreters tag.
+
+Note: Sub-interpreter support does not imply free-threading support or vice-versa.
+Free-threaded modules can still have global/static state, but multiple interpreter modules cannot.
+Likewise, sub-interpreter modules can still use the GIL, but free-threaded modules cannot.
+
 Binding sequence data types, iterators, the slicing protocol, etc.
 ==================================================================