PyStackRef in rustpython_vm::object - Rust
pub struct PyStackRef { /* private fields */ }Expand description
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>).
Source§
Source
Create an owned stack reference, consuming the PyObjectRef.
Refcount is NOT incremented — ownership is transferred.
Source
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.
Source
Whether this is a borrowed (non-owning) reference.
Source
Get a &PyObject reference. Works for both owned and borrowed.
Source
Convert to an owned PyObjectRef.
- If borrowed → increments refcount, forgets self.
- If owned → reconstructs
PyObjectReffrom the raw pointer, forgets self.
Source
Promote a borrowed ref to owned in place (increments refcount, clears the borrow tag). No-op if already owned.
Source
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.
👎Deprecated:
use downcastable instead
Source 👎Deprecated:
use downcast_unchecked_ref instead
👎Deprecated:
use downcast_ref instead
👎Deprecated:
use downcast_ref_if_exact instead
Source
Set the dict field. Returns Err(dict) if this object does not have a dict field
in the first place.
👎Deprecated:
use downcast_ref instead
Source
Check if this object can be downcast to T.
Source
Attempt to downcast this reference to a subclass.
Source
Attempt to downcast this reference to a subclass.
Source
_PyObject_GC_IS_TRACKED
Source
Get the referents (objects directly referenced) of this object. Uses the full traverse including dict and slots.
Source
Call del if present, without triggering object deallocation. Used by GC to call finalizers before breaking cycles. This allows proper resurrection detection. PyObject_CallFinalizerFromDealloc
Source
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
Source
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.
Source
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
Source
Check if this object has clear capability (tp_clear)
Source
PyObject_CallArg series
Source
PyObject_Call
Source
Vectorcall: call with owned positional args + optional kwnames. Falls back to FuncArgs-based call if no vectorcall slot.
Source
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.
Source
Get an attribute by name.
attr_name can be a &str, String, or PyStrRef.
Source
CPython _PyObject_GenericGetAttrWithDict
Source
Real issubclass check without going through subclasscheck This is equivalent to CPython’s _PyObject_RealIsSubclass which just calls recursive_issubclass
Source
Determines if self is a subclass of cls, either directly, indirectly or virtually
via the subclasscheck magic method.
PyObject_IsSubclass/object_issubclass
Source
Determines if self is an instance of cls, either directly, indirectly or virtually via
the instancecheck magic method.
Source
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).