Add docs for single-initialization

guide/src/faq.md

@@ -13,9 +13,11 @@ Sorry that you're having trouble using PyO3. If you can't find the answer to you
 5. Thread A is blocked, because it waits to re-acquire the GIL which thread B still holds.
 6. Deadlock.
 
-PyO3 provides a struct [`GILOnceCell`] which works similarly to these types but avoids risk of deadlocking with the Python GIL. This means it can be used in place of other choices when you are experiencing the deadlock described above. See the documentation for [`GILOnceCell`] for further details and an example how to use it.
+PyO3 provides a struct [`GILOnceCell`] and an extension trait [`OnceExt`] that
+enable functionality similar to these types but avoid the risk of deadlocking with the Python GIL. This means they can be used in place of other choices when you are experiencing the deadlock described above. See the documentation for [`GILOnceCell`] and [`OnceExt`] for further details and an example how to use them.
 
 [`GILOnceCell`]: {{#PYO3_DOCS_URL}}/pyo3/sync/struct.GILOnceCell.html
+[`OnceExt`]: {{#PYO3_DOCS_URL}}/pyo3/sync/trait.OnceExt.html
 
 ## I can't run `cargo test`; or I can't build in a Cargo workspace: I'm having linker issues like "Symbol not found" or "Undefined reference to _PyExc_SystemError"!
 

guide/src/free-threading.md

@@ -152,6 +152,58 @@ We plan to allow user-selectable semantics for mutable pyclass definitions in
 PyO3 0.24, allowing some form of opt-in locking to emulate the GIL if that is
 needed.
 
+## Thread-safe single initialization
+
+Until version 0.23, PyO3 provided only `GILOnceCell` to enable deadlock-free
+single initialization of data in contexts that might execute arbitrary Python
+code. While we have updated `GILOnceCell` to avoid thread safety issues
+triggered only under the free-threaded build, the design of `GILOnceCell` is
+inherently thread-unsafe, in a manner that can be problematic even in the
+GIL-enabled build.
+
+If, for example, the function executed by `GILOnceCell` releases the GIL or
+calls code that releases the GIL, then it is possible for multiple threads to
+try to race to initialize the cell. While the cell will only ever be intialized
+once, it can be problematic in some contexts that `GILOnceCell` does not block
+like the standard library `OnceLock`.
+
+In cases where the initialization function must run exactly once, you can bring
+the `OnceExt` trait into scope. This trait adds `OnceExt::call_once_py_attached`
+and `OnceExt::call_once_force_py_attached` functions to the api of
+`std::sync::Once`, enabling use of `Once` in contexts where the GIL is
+held. These functions are analogous to `Once::call_once` and
+`Once::call_once_force` except they both accept a `Python<'py>` token in
+addition to an `FnOnce`. Both functions release the GIL and re-acquire it before
+executing the function, avoiding deadlocks with the GIL that are possible
+without using these functions. Here is an example of how to use this function to
+enable single-initialization of a runtime cache:
+
+```rust
+# fn main() {
+# use pyo3::prelude::*;
+use std::sync::Once;
+use pyo3::sync::OnceExt;
+use pyo3::types::PyDict;
+
+struct RuntimeCache {
+    once: Once,
+    cache: Option<Py<PyDict>>
+}
+
+let mut cache = RuntimeCache {
+    once: Once::new(),
+    cache: None
+};
+
+Python::with_gil(|py| {
+    // guaranteed to be called once and only once
+    cache.once.call_once_py_attached(py, || {
+        cache.cache = Some(PyDict::new(py).unbind());
+    });
+});
+# }
+```
+
 ## `GILProtected` is not exposed
 
 `GILProtected` is a PyO3 type that allows mutable access to static data by

guide/src/migration.md

@@ -230,7 +230,12 @@ PyO3 0.23 introduces preliminary support for the new free-threaded build of
 CPython 3.13. PyO3 features that implicitly assumed the existence of the GIL are
 not exposed in the free-threaded build, since they are no longer safe.  Other
 features, such as `GILOnceCell`, have been internally rewritten to be threadsafe
-without the GIL.
+without the GIL, although note that `GILOnceCell` is inherently racey. You can
+also use `OnceExt::call_once_py_attached` or
+`OnceExt::call_once_force_py_attached` to enable use of `std::sync::Once` in
+code that has the GIL acquired without risking a dealock with the GIL. We plan
+We plan to expose more extension traits in the future that make it easier to
+write code for the GIL-enabled and free-threaded builds of Python.
 
 If you make use of these features then you will need to account for the
 unavailability of this API in the free-threaded build. One way to handle it is