Struct pyo3::sync::GILOnceCell

pub struct GILOnceCell<T>(/* private fields */);

A write-once cell similar to once_cell::OnceCell.

Unlike once_cell::sync which blocks threads to achieve thread safety, this implementation uses the Python GIL to mediate concurrent access. This helps in cases where once_cell or lazy_static’s synchronization strategy can lead to deadlocks when interacting with the Python GIL. For an example, see the FAQ section of the guide.

Note that:

1. get_or_init and get_or_try_init do not protect against infinite recursion from reentrant initialization.
2. If the initialization function f provided to get_or_init (or get_or_try_init) temporarily releases the GIL (e.g. by calling Python::import) then it is possible for a second thread to also begin initializing the GITOnceCell. Even when this happens GILOnceCell guarantees that only one write to the cell ever occurs
   • this is treated as a race, other threads will discard the value they compute and return the result of the first complete computation.

Examples

The following example shows how to use GILOnceCell to share a reference to a Python list between threads:

use pyo3::sync::GILOnceCell;
use pyo3::prelude::*;
use pyo3::types::PyList;

static LIST_CELL: GILOnceCell<Py<PyList>> = GILOnceCell::new();

pub fn get_shared_list(py: Python<'_>) -> &Bound<'_, PyList> {
    LIST_CELL
        .get_or_init(py, || PyList::empty_bound(py).unbind())
        .bind(py)
}

Implementations

impl<T> GILOnceCell<T>

pub const fn new() -> Self

Create a GILOnceCell which does not yet contain a value.

pub fn get(&self, _py: Python<'_>) -> Option<&T>

Get a reference to the contained value, or None if the cell has not yet been written.

pub fn get_or_init<F>(&self, py: Python<'_>, f: F) -> &T

where F: FnOnce() -> T,

Get a reference to the contained value, initializing it if needed using the provided closure.

See the type-level documentation for detail on re-entrancy and concurrent initialization.

pub fn get_or_try_init<F, E>(&self, py: Python<'_>, f: F) -> Result<&T, E>

where F: FnOnce() -> Result<T, E>,

Like get_or_init, but accepts a fallible initialization function. If it fails, the cell is left uninitialized.

See the type-level documentation for detail on re-entrancy and concurrent initialization.

pub fn get_mut(&mut self) -> Option<&mut T>

Get the contents of the cell mutably. This is only possible if the reference to the cell is unique.

pub fn set(&self, _py: Python<'_>, value: T) -> Result<(), T>

Set the value in the cell.

If the cell has already been written, Err(value) will be returned containing the new value which was not written.

pub fn take(&mut self) -> Option<T>

Takes the value out of the cell, moving it back to an uninitialized state.

Has no effect and returns None if the cell has not yet been written.

pub fn into_inner(self) -> Option<T>

Consumes the cell, returning the wrapped value.

Returns None if the cell has not yet been written.

Trait Implementations

impl<T: Default> Default for GILOnceCell<T>

fn default() -> GILOnceCell<T>

Returns the “default value” for a type.

impl<T: Send> Send for GILOnceCell<T>

impl<T: Send + Sync> Sync for GILOnceCell<T>