Struct PyStackRef 

pub struct PyStackRef { /* private fields */ }

A tagged stack reference to a Python object.

Uses the lowest bit of the pointer to distinguish owned vs borrowed:

• bit 0 = 0 → owned: refcount was incremented; Drop will decrement.
• bit 0 = 1 → borrowed: no refcount change; Drop is a no-op.

Same size as PyObjectRef (one pointer-width). PyObject is at least 8-byte aligned, so the low bit is always available for tagging.

Uses NonZeroUsize so that Option<PyStackRef> has the same size as PyStackRef via niche optimization (matching Option<PyObjectRef>).

Implementations

impl PyStackRef

pub fn new_owned(obj: PyObjectRef) -> Self

Create an owned stack reference, consuming the PyObjectRef. Refcount is NOT incremented — ownership is transferred.

pub unsafe fn new_borrowed(obj: &PyObject) -> Self

Create a borrowed stack reference from a &PyObject.

Safety

The caller must guarantee that the pointed-to object lives at least as long as this PyStackRef. In practice the compiler guarantees that borrowed refs are consumed within the same basic block, before any STORE_FAST/DELETE_FAST could overwrite the source slot.

pub fn is_borrowed(&self) -> bool

Whether this is a borrowed (non-owning) reference.

pub fn as_object(&self) -> &PyObject

Get a &PyObject reference. Works for both owned and borrowed.

pub fn to_pyobj(self) -> PyObjectRef

Convert to an owned PyObjectRef.

• If borrowed → increments refcount, forgets self.
• If owned → reconstructs PyObjectRef from the raw pointer, forgets self.

pub fn promote(&mut self)

Promote a borrowed ref to owned in place (increments refcount, clears the borrow tag). No-op if already owned.

Methods from Deref<Target = PyObject>

pub fn try_to_value<'a, T>(&'a self, vm: &VirtualMachine) -> PyResult<T>

where T: 'a + TryFromBorrowedObject<'a>,

pub fn try_to_ref<'a, T>(&'a self, vm: &VirtualMachine) -> PyResult<&'a Py<T>>

where T: 'a + PyPayload,

pub fn try_value_with<T, F, R>(&self, f: F, vm: &VirtualMachine) -> PyResult<R>

where T: PyPayload, F: Fn(&T) -> PyResult<R>,

pub fn try_bytes_like<R>( &self, vm: &VirtualMachine, f: impl FnOnce(&[u8]) -> R, ) -> PyResult<R>

pub fn try_rw_bytes_like<R>( &self, vm: &VirtualMachine, f: impl FnOnce(&mut [u8]) -> R, ) -> PyResult<R>

pub fn as_interned_str( &self, vm: &VirtualMachine, ) -> Option<&'static PyStrInterned>

pub fn try_to_owned(&self) -> Option<PyObjectRef>

Atomically try to create a strong reference. Returns None if the strong count is already 0 (object being destroyed). Uses CAS to prevent the TOCTOU race between checking strong_count and incrementing it.

pub fn downgrade( &self, callback: Option<PyObjectRef>, vm: &VirtualMachine, ) -> PyResult<PyRef<PyWeak>>

pub fn get_weak_references(&self) -> Option<Vec<PyRef<PyWeak>>>

pub fn payload_is<T: PyPayload>(&self) -> bool

👎Deprecated:

use downcastable instead

pub unsafe fn payload_unchecked<T: PyPayload>(&self) -> &T

👎Deprecated:

use downcast_unchecked_ref instead

Force to return payload as T.

Safety

The actual payload type must be T.

pub fn payload<T: PyPayload>(&self) -> Option<&T>

👎Deprecated:

use downcast_ref instead

pub fn class(&self) -> &Py<PyType>

pub fn set_class(&self, typ: PyTypeRef, vm: &VirtualMachine)

pub fn payload_if_exact<T: PyPayload>(&self, vm: &VirtualMachine) -> Option<&T>

👎Deprecated:

use downcast_ref_if_exact instead

pub fn dict(&self) -> Option<PyDictRef>

pub fn set_dict(&self, dict: PyDictRef) -> Result<(), PyDictRef>

Set the dict field. Returns Err(dict) if this object does not have a dict field in the first place.

pub fn payload_if_subclass<T: PyPayload>( &self, vm: &VirtualMachine, ) -> Option<&T>

👎Deprecated:

use downcast_ref instead

pub fn downcastable<T: PyPayload>(&self) -> bool

Check if this object can be downcast to T.

pub fn try_downcast_ref<'a, T: PyPayload>( &'a self, vm: &VirtualMachine, ) -> PyResult<&'a Py<T>>

Attempt to downcast this reference to a subclass.

pub fn downcast_ref<T: PyPayload>(&self) -> Option<&Py<T>>

Attempt to downcast this reference to a subclass.

pub fn downcast_ref_if_exact<T: PyPayload>( &self, vm: &VirtualMachine, ) -> Option<&Py<T>>

pub unsafe fn downcast_unchecked_ref<T: PyPayload>(&self) -> &Py<T>

Safety

T must be the exact payload type

pub fn strong_count(&self) -> usize

pub fn weak_count(&self) -> Option<usize>

pub fn as_raw(&self) -> *const Self

pub fn is_gc_tracked(&self) -> bool

_PyObject_GC_IS_TRACKED

pub fn gc_get_referents(&self) -> Vec<PyObjectRef>

Get the referents (objects directly referenced) of this object. Uses the full traverse including dict and slots.

pub fn try_call_finalizer(&self)

Call del if present, without triggering object deallocation. Used by GC to call finalizers before breaking cycles. This allows proper resurrection detection. PyObject_CallFinalizerFromDealloc

pub fn gc_clear_weakrefs_collect_callbacks( &self, ) -> Vec<(PyRef<PyWeak>, PyObjectRef)>

Clear weakrefs but collect callbacks instead of calling them. This is used by GC to ensure ALL weakrefs are cleared BEFORE any callbacks run. Returns collected callbacks as (PyRef, callback) pairs.

pub unsafe fn gc_get_referent_ptrs(&self) -> Vec<NonNull<PyObject>>

Get raw pointers to referents without incrementing reference counts. This is used during GC to avoid reference count manipulation. tp_traverse visits objects without incref

Safety

The returned pointers are only valid as long as the object is alive and its contents haven’t been modified.

pub unsafe fn gc_clear(&self) -> Vec<PyObjectRef>

Clear this object for cycle breaking (tp_clear). This version takes &self but should only be called during GC when exclusive access is guaranteed.

Safety

• The caller must guarantee exclusive access (no other references exist)
• This is only safe during GC when the object is unreachable

pub fn gc_has_clear(&self) -> bool

Check if this object has clear capability (tp_clear)

pub fn to_callable(&self) -> Option<PyCallable<'_>>

pub fn is_callable(&self) -> bool

pub fn call(&self, args: impl IntoFuncArgs, vm: &VirtualMachine) -> PyResult

PyObject_CallArg series

pub fn call_with_args(&self, args: FuncArgs, vm: &VirtualMachine) -> PyResult

PyObject_Call

pub fn vectorcall( &self, args: Vec<PyObjectRef>, nargs: usize, kwnames: Option<&[PyObjectRef]>, vm: &VirtualMachine, ) -> PyResult

Vectorcall: call with owned positional args + optional kwnames. Falls back to FuncArgs-based call if no vectorcall slot.

pub fn mapping_unchecked(&self) -> PyMapping<'_>

pub fn try_mapping(&self, vm: &VirtualMachine) -> PyResult<PyMapping<'_>>

pub fn number(&self) -> PyNumber<'_>

pub fn try_index_opt(&self, vm: &VirtualMachine) -> Option<PyResult<PyIntRef>>

pub fn try_index(&self, vm: &VirtualMachine) -> PyResult<PyIntRef>

pub fn try_int(&self, vm: &VirtualMachine) -> PyResult<PyIntRef>

pub fn try_float_opt( &self, vm: &VirtualMachine, ) -> Option<PyResult<PyRef<PyFloat>>>

pub fn try_float(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyFloat>>

pub fn get_iter(&self, vm: &VirtualMachine) -> PyResult<PyIter>

Takes an object and returns an iterator for it. This is typically a new iterator but if the argument is an iterator, this returns itself.

pub fn get_aiter(&self, vm: &VirtualMachine) -> PyResult

pub fn has_attr<'a>( &self, attr_name: impl AsPyStr<'a>, vm: &VirtualMachine, ) -> PyResult<bool>

pub fn get_attr<'a>( &self, attr_name: impl AsPyStr<'a>, vm: &VirtualMachine, ) -> PyResult

Get an attribute by name. attr_name can be a &str, String, or PyStrRef.

pub fn call_set_attr( &self, vm: &VirtualMachine, attr_name: &Py<PyStr>, attr_value: PySetterValue, ) -> PyResult<()>

pub fn set_attr<'a>( &self, attr_name: impl AsPyStr<'a>, attr_value: impl Into<PyObjectRef>, vm: &VirtualMachine, ) -> PyResult<()>

pub fn generic_setattr( &self, attr_name: &Py<PyStr>, value: PySetterValue, vm: &VirtualMachine, ) -> PyResult<()>

pub fn generic_getattr(&self, name: &Py<PyStr>, vm: &VirtualMachine) -> PyResult

pub fn generic_getattr_opt( &self, name_str: &Py<PyStr>, dict: Option<PyDictRef>, vm: &VirtualMachine, ) -> PyResult<Option<PyObjectRef>>

CPython _PyObject_GenericGetAttrWithDict

pub fn del_attr<'a>( &self, attr_name: impl AsPyStr<'a>, vm: &VirtualMachine, ) -> PyResult<()>

pub fn rich_compare_bool( &self, other: &Self, op_id: PyComparisonOp, vm: &VirtualMachine, ) -> PyResult<bool>

pub fn repr_utf8(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyUtf8Str>>

pub fn repr(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyStr>>

pub fn ascii(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyStr>>

pub fn str_utf8(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyUtf8Str>>

pub fn str(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyStr>>

pub fn real_is_subclass( &self, cls: &Self, vm: &VirtualMachine, ) -> PyResult<bool>

Real issubclass check without going through subclasscheck This is equivalent to CPython’s _PyObject_RealIsSubclass which just calls recursive_issubclass

pub fn is_subclass(&self, cls: &Self, vm: &VirtualMachine) -> PyResult<bool>

Determines if self is a subclass of cls, either directly, indirectly or virtually via the subclasscheck magic method. PyObject_IsSubclass/object_issubclass

pub fn is_instance(&self, cls: &Self, vm: &VirtualMachine) -> PyResult<bool>

Determines if self is an instance of cls, either directly, indirectly or virtually via the instancecheck magic method.

pub fn hash(&self, vm: &VirtualMachine) -> PyResult<PyHash>

pub fn obj_type(&self) -> PyObjectRef

pub fn type_check(&self, typ: &Py<PyType>) -> bool

pub fn length_opt(&self, vm: &VirtualMachine) -> Option<PyResult<usize>>

pub fn length(&self, vm: &VirtualMachine) -> PyResult<usize>

pub fn get_item<K: DictKey + ?Sized>( &self, needle: &K, vm: &VirtualMachine, ) -> PyResult

pub fn set_item<K: DictKey + ?Sized>( &self, needle: &K, value: PyObjectRef, vm: &VirtualMachine, ) -> PyResult<()>

pub fn del_item<K: DictKey + ?Sized>( &self, needle: &K, vm: &VirtualMachine, ) -> PyResult<()>

pub fn lookup_special( &self, attr: &Py<PyStr>, vm: &VirtualMachine, ) -> Option<PyObjectRef>

Equivalent to CPython’s _PyObject_LookupSpecial Looks up a special method in the type’s MRO without checking instance dict. Returns None if not found (masking AttributeError like CPython).

pub fn sequence_unchecked(&self) -> PySequence<'_>

pub fn try_sequence(&self, vm: &VirtualMachine) -> PyResult<PySequence<'_>>

Trait Implementations

impl Clone for PyStackRef

fn clone(&self) -> Self

Cloning always produces an owned reference (increments refcount).

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PyStackRef

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for PyStackRef

type Target = PyObject

The resulting type after dereferencing.

fn deref(&self) -> &PyObject

Dereferences the value.

impl Drop for PyStackRef

fn drop(&mut self)

Executes the destructor for this type.

impl Traverse for PyStackRef

fn traverse(&self, traverse_fn: &mut TraverseFn<'_>)

impl traverse() with caution! Following those guideline so traverse doesn’t cause memory error!:

fn clear(&mut self, _out: &mut Vec<PyObjectRef>)

Extract all owned child PyObjectRefs for circular reference resolution (tp_clear). Called just before object deallocation to break circular references. Default implementation does nothing.