Struct cpython::UnsafePyLeaked

pub struct UnsafePyLeaked<T: ?Sized> { /* fields omitted */ }

An immutable reference to PySharedRefCell value, not bound to lifetime.

The reference will be invalidated once the original value is mutably borrowed.

Safety

Even though UnsafePyLeaked tries to enforce the real lifetime of the underlying object, the object having the artificial 'static lifetime may be exposed to your Rust code. You must be careful to not make a bare reference outlive the actual object lifetime.

let outer;
unsafe { leaked.map(py, |o| { outer = o }) };  // Bad

let outer;
let mut leaked_iter = leaked.map(py, |o| o.iter());
{
    let mut iter = unsafe { leaked_iter.try_borrow_mut(py) };
    let inner = iter.next();  // Good, in borrow scope
    outer = inner;            // Bad, &'static T may outlive
}

Implementations

impl<T: ?Sized> UnsafePyLeaked<T>

pub unsafe fn try_borrow<'a>(
    &'a self,
    py: Python<'a>
) -> PyResult<PyLeakedRef<'a, T>>

Immutably borrows the wrapped value.

Borrowing fails if the underlying reference has been invalidated.

Safety

The lifetime of the innermost object is artificial. Do not obtain and copy it out of the borrow scope.

pub unsafe fn try_borrow_mut<'a>(
    &'a mut self,
    py: Python<'a>
) -> PyResult<PyLeakedRefMut<'a, T>>

Mutably borrows the wrapped value.

Borrowing fails if the underlying reference has been invalidated.

Typically T is an iterator. If T is an immutable reference, get_mut() is useless since the inner value can't be mutated.

Safety

The lifetime of the innermost object is artificial. Do not obtain and copy it out of the borrow scope.

impl<T> UnsafePyLeaked<T>

pub unsafe fn map<U>(
    self,
    py: Python<'_>,
    f: impl FnOnce(T) -> U
) -> UnsafePyLeaked<U>

Converts the inner value by the given function.

Typically T is a static reference to a collection, and U is an iterator of that collection.

Panics

Panics if the underlying reference has been invalidated.

This is typically called immediately after the UnsafePyLeaked is obtained. At this time, the reference must be valid and no panic would occur.

Safety

The lifetime of the object passed in to the function f is artificial. It's typically a static reference, but is valid only while the corresponding UnsafePyLeaked is alive. Do not copy it out of the function call.