add PyOnceLock type (#5223)

* add `PyOnceLock` type

---------

Co-authored-by: Nathan Goldbaum <nathan.goldbaum@gmail.com>

* Apply suggestions from code review

Co-authored-by: Icxolu <10486322+Icxolu@users.noreply.github.com>

* Update src/impl_/exceptions.rs

Co-authored-by: Nathan Goldbaum <nathan.goldbaum@gmail.com>

---------

Co-authored-by: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Co-authored-by: Icxolu <10486322+Icxolu@users.noreply.github.com>

Author: 3 people

Cargo.toml

@@ -27,6 +27,7 @@ rust-version.workspace = true
 [dependencies]
 libc = "0.2.62"
 memoffset = "0.9"
+once_cell = "1.21"
 
 # ffi bindings to the python interpreter, split into a separate crate so they can be used independently
 pyo3-ffi = { path = "pyo3-ffi", version = "=0.25.1" }
@@ -129,6 +130,7 @@ auto-initialize = []
 # Enables `Clone`ing references to Python objects `Py<T>` which panics if the GIL is not held.
 py-clone = []
 
+# Adds `OnceExt` and `MutexExt` implementations to the `parking_lot` types
 parking_lot = ["dep:parking_lot", "lock_api"]
 arc_lock = ["lock_api", "lock_api/arc_lock", "parking_lot?/arc_lock"]
 

guide/src/faq.md

@@ -4,18 +4,18 @@ Sorry that you're having trouble using PyO3. If you can't find the answer to you
 
 ## I'm experiencing deadlocks using PyO3 with `std::sync::OnceLock`, `std::sync::LazyLock`, `lazy_static`, and `once_cell`!
 
-`OnceLock`, `LazyLock`, and their thirdparty predecessors use blocking to ensure only one thread ever initializes them. Because the Python GIL is an additional lock this can lead to deadlocks in the following way:
+`OnceLock`, `LazyLock`, and their thirdparty predecessors use blocking to ensure only one thread ever initializes them. Because the Python interpreter can introduce additional locks (the Python GIL and GC can both require all other threads to pause) this can lead to deadlocks in the following way:
 
-1. A thread (thread A) which has acquired the Python GIL starts initialization of a `OnceLock` value.
-2. The initialization code calls some Python API which temporarily releases the GIL e.g. `Python::import`.
-3. Another thread (thread B) acquires the Python GIL and attempts to access the same `OnceLock` value.
+1. A thread (thread A) which is attached to the Python interpreter starts initialization of a `OnceLock` value.
+2. The initialization code calls some Python API which temporarily detaches from the interpreter e.g. `Python::import`.
+3. Another thread (thread B) attaches to the Python interpreter and attempts to access the same `OnceLock` value.
 4. Thread B is blocked, because it waits for `OnceLock`'s initialization to lock to release.
-5. Thread A is blocked, because it waits to re-acquire the GIL which thread B still holds.
+5. On non-free-threaded Python, thread A is now also blocked, because it waits to re-attach to the interpreter (by taking the GIL which thread B still holds).
 6. Deadlock.
 
-PyO3 provides a struct [`GILOnceCell`] which implements a single-initialization API based on these types that relies on the GIL for locking. If the GIL is released or there is no GIL, then this type allows the initialization function to race but ensures that the data is only ever initialized once. If you need to ensure that the initialization function is called once and only once, you can make use of the [`OnceExt`] and [`OnceLockExt`] extension traits that enable using the standard library types for this purpose but provide new methods for these types that 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.
+PyO3 provides a struct [`PyOnceLock`] which implements a single-initialization API based on these types that avoids deadlocks. You can also make use of the [`OnceExt`] and [`OnceLockExt`] extension traits that enable using the standard library types for this purpose by providing new methods for these types that avoid the risk of deadlocking with the Python interpreter. This means they can be used in place of other choices when you are experiencing the deadlock described above. See the documentation for [`PyOnceLock`] and [`OnceExt`] for further details and an example how to use them.
 
-[`GILOnceCell`]: {{#PYO3_DOCS_URL}}/pyo3/sync/struct.GILOnceCell.html
+[`PyOnceLock`]: {{#PYO3_DOCS_URL}}/pyo3/sync/struct.PyOnceLock.html
 [`OnceExt`]: {{#PYO3_DOCS_URL}}/pyo3/sync/trait.OnceExt.html
 [`OnceLockExt`]: {{#PYO3_DOCS_URL}}/pyo3/sync/trait.OnceLockExt.html
 

guide/src/free-threading.md

@@ -285,31 +285,39 @@ the free-threaded build.
 
 ### 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
-race to initialize the cell. While the cell will only ever be initialized
-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`] or [`OnceLockExt`] traits into scope. The [`OnceExt`] trait adds
+To initialize data exactly once, use the [`PyOnceLock`] type, which is a close equivalent
+to [`std::sync::OnceLock`][`OnceLock`] that also helps avoid deadlocks by detaching from
+the Python interpreter when threads are blocking waiting for another thread to
+complete intialization. If already using [`OnceLock`] and it is impractical
+to replace with a [`PyOnceLock`], there is the [`OnceLockExt`] extension trait
+which adds [`OnceLockExt::get_or_init_py_attached`] to detach from the interpreter
+when blocking in the same fashion as [`PyOnceLock`]. Here is an example using
+[`PyOnceLock`] to single-initialize a runtime cache holding a `Py<PyDict>`:
+
+```rust
+# use pyo3::prelude::*;
+use pyo3::sync::PyOnceLock;
+use pyo3::types::PyDict;
+
+let cache: PyOnceLock<Py<PyDict>> = PyOnceLock::new();
+
+Python::attach(|py| {
+    // guaranteed to be called once and only once
+    cache.get_or_init(py, || PyDict::new(py).unbind())
+});
+```
+
+In cases where a function must run exactly once, you can bring
+the [`OnceExt`] trait into scope. The [`OnceExt`] 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. Similarly, [`OnceLockExt`] adds
-[`OnceLockExt::get_or_init_py_attached`]. These functions are analogous to
-[`Once::call_once`], [`Once::call_once_force`], and [`OnceLock::get_or_init`] except
-they accept a [`Python<'py>`] token in addition to an `FnOnce`. All of these
-functions release the GIL and re-acquire it before executing the function,
-avoiding deadlocks with the GIL that are possible without using the PyO3
-extension traits. Here is an example of how to use [`OnceExt`] to
-enable single-initialization of a runtime cache holding a `Py<PyDict>`.
+where the thread is attached to the Python interpreter. These functions are analogous to
+[`Once::call_once`], [`Once::call_once_force`] except they accept a [`Python<'py>`]
+token in addition to an `FnOnce`. All of these functions detach from the
+interpreter before blocking and re-attach before executing the function,
+avoiding deadlocks that are possible without using the PyO3
+extension traits. Here the same example as above built using a [`Once`] instead of a
+[`PyOnceLock`]:
 
 ```rust
 # use pyo3::prelude::*;
@@ -411,4 +419,5 @@ interpreter.
 [`Python::detach`]: {{#PYO3_DOCS_URL}}/pyo3/marker/struct.Python.html#method.detach
 [`Python::attach`]: {{#PYO3_DOCS_URL}}/pyo3/marker/struct.Python.html#method.attach
 [`Python<'py>`]: {{#PYO3_DOCS_URL}}/pyo3/marker/struct.Python.html
+[`PyOnceLock`]: {{#PYO3_DOCS_URL}}/pyo3/sync/struct.PyOnceLock.html
 [`threading`]: https://docs.python.org/3/library/threading.html

guide/src/migration.md

@@ -21,7 +21,46 @@ For this reason we chose to rename these to more modern terminology introduced i
 <summary><small>Click to expand</small></summary>
 
 The type alias `PyObject` (aka `Py<PyAny>`) is often confused with the identically named FFI definition `pyo3::ffi::PyObject`. For this reason we are deprecating its usage. To migrate simply replace its usage by the target type `Py<PyAny>`.
+</details>
+
+### Replacement of `GILOnceCell` with `PyOnceLock`
+<details open>
+<summary><small>Click to expand</small></summary>
+
+Similar to the above renaming of `Python::with_gil` and related APIs, the `GILOnceCell` type was designed for a Python interpreter which was limited by the GIL. Aside from its name, it allowed for the "once" initialization to race because the racing was mediated by the GIL and was extremely unlikely to manifest in practice.
+
+With the introduction of free-threaded Python the racy initialization behavior is more likely to be problematic and so a new type `PyOnceLock` has been introduced which performs true single-initialization correctly while attached to the Python interpreter. It exposes the same API as `GILOnceCell`, so should be a drop-in replacement with the notable exception that if the racy initialization of `GILOnceCell` was inadvertently relied on (e.g. due to circular references) then the stronger once-ever guarantee of `PyOnceLock` may lead to deadlocking which requires refactoring.
+
+Before:
 
+```rust
+# #![allow(deprecated)]
+# use pyo3::prelude::*;
+# use pyo3::sync::GILOnceCell;
+# use pyo3::types::PyType;
+# fn main() -> PyResult<()> {
+# Python::attach(|py| {
+static DECIMAL_TYPE: GILOnceCell<Py<PyType>> = GILOnceCell::new();
+DECIMAL_TYPE.import(py, "decimal", "Decimal")?;
+# Ok(())
+# })
+# }
+```
+
+After:
+
+```rust
+# use pyo3::prelude::*;
+# use pyo3::sync::PyOnceLock;
+# use pyo3::types::PyType;
+# fn main() -> PyResult<()> {
+# Python::attach(|py| {
+static DECIMAL_TYPE: PyOnceLock<Py<PyType>> = PyOnceLock::new();
+DECIMAL_TYPE.import(py, "decimal", "Decimal")?;
+# Ok(())
+# })
+# }
+```
 </details>
 
 ### Deprecation of `GILProtected`
@@ -64,7 +103,7 @@ Python::attach(|py| {
 # })
 # }
 ```
-</summary>
+</details>
 
 ### `PyMemoryError` now maps to `io::ErrorKind::OutOfMemory` when converted to `io::Error`
 <details>

newsfragments/5171.packaging.md

@@ -1,2 +1 @@
 Update MSRV to 1.74.
-Drop `once_cell` dependency.

newsfragments/5223.added.md

@@ -0,0 +1 @@
+Add `PyOnceLock` type for thread-safe single-initialization.

newsfragments/5223.changed.md

@@ -0,0 +1 @@
+Deprecate `GILOnceCell` type in favour of `PyOnceLock`.

pyo3-macros-backend/src/pyclass.rs

@@ -2468,12 +2468,8 @@ impl<'a> PyClassImplsBuilder<'a> {
                 impl #pyo3_path::impl_::pyclass::PyClassWithFreeList for #cls {
                     #[inline]
                     fn get_free_list(py: #pyo3_path::Python<'_>) -> &'static ::std::sync::Mutex<#pyo3_path::impl_::freelist::PyObjectFreeList> {
-                        static FREELIST: #pyo3_path::sync::GILOnceCell<::std::sync::Mutex<#pyo3_path::impl_::freelist::PyObjectFreeList>> = #pyo3_path::sync::GILOnceCell::new();
-                        // If there's a race to fill the cell, the object created
-                        // by the losing thread will be deallocated via RAII
-                        &FREELIST.get_or_init(py, || {
-                            ::std::sync::Mutex::new(#pyo3_path::impl_::freelist::PyObjectFreeList::with_capacity(#freelist))
-                        })
+                        static FREELIST: #pyo3_path::sync::PyOnceLock<::std::sync::Mutex<#pyo3_path::impl_::freelist::PyObjectFreeList>> = #pyo3_path::sync::PyOnceLock::new();
+                        &FREELIST.get_or_init(py, || ::std::sync::Mutex::new(#pyo3_path::impl_::freelist::PyObjectFreeList::with_capacity(#freelist)))
                     }
                 }
             }

src/conversions/bigdecimal.rs

@@ -54,20 +54,20 @@ use std::str::FromStr;
 use crate::types::PyTuple;
 use crate::{
     exceptions::PyValueError,
-    sync::GILOnceCell,
+    sync::PyOnceLock,
     types::{PyAnyMethods, PyStringMethods, PyType},
     Bound, FromPyObject, IntoPyObject, Py, PyAny, PyErr, PyResult, Python,
 };
 use bigdecimal::BigDecimal;
 use num_bigint::Sign;
 
 fn get_decimal_cls(py: Python<'_>) -> PyResult<&Bound<'_, PyType>> {
-    static DECIMAL_CLS: GILOnceCell<Py<PyType>> = GILOnceCell::new();
+    static DECIMAL_CLS: PyOnceLock<Py<PyType>> = PyOnceLock::new();
     DECIMAL_CLS.import(py, "decimal", "Decimal")
 }
 
 fn get_invalid_operation_error_cls(py: Python<'_>) -> PyResult<&Bound<'_, PyType>> {
-    static INVALID_OPERATION_CLS: GILOnceCell<Py<PyType>> = GILOnceCell::new();
+    static INVALID_OPERATION_CLS: PyOnceLock<Py<PyType>> = PyOnceLock::new();
     INVALID_OPERATION_CLS.import(py, "decimal", "InvalidOperation")
 }
 

src/conversions/chrono.rs

@@ -52,7 +52,7 @@ use crate::types::{PyDateAccess, PyDeltaAccess, PyTimeAccess};
 #[cfg(feature = "chrono-local")]
 use crate::{
     exceptions::PyRuntimeError,
-    sync::GILOnceCell,
+    sync::PyOnceLock,
     types::{PyString, PyStringMethods},
     Py,
 };
@@ -449,7 +449,7 @@ impl<'py> IntoPyObject<'py> for Local {
     type Error = PyErr;
 
     fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
-        static LOCAL_TZ: GILOnceCell<Py<PyTzInfo>> = GILOnceCell::new();
+        static LOCAL_TZ: PyOnceLock<Py<PyTzInfo>> = PyOnceLock::new();
         let tz = LOCAL_TZ
             .get_or_try_init(py, || {
                 let iana_name = iana_time_zone::get_timezone().map_err(|e| {