stackref

Documentation

Overview

Package stackref is the tagged stack-value representation the bytecode interpreter operates on. A Ref wraps an objects.Object with the same vocabulary CPython uses (FromObject, AsObject, Dup, Steal, Null, None/True/False sentinels), so the eval loop matches CPython's stackref calls one-for-one.

In the GIL build, Ref is structurally a pointer with no tag bits. The wrapper exists so v0.14 can swap in the biased-refcount representation without touching dispatch arms.

CPython: Include/internal/pycore_stackref.h _PyStackRef CPython: Python/stackrefs.c

Index

• Variables
• type Ref
  • func FromObject(o objects.Object) Ref
  • func FromObjectImmortal(o objects.Object) Ref
  • func FromObjectNew(o objects.Object) Ref
  • func (r Ref) AsObject() objects.Object
  • func (r Ref) AsObjectSteal() objects.Object
  • func (r Ref) Close()
  • func (r Ref) Dup() Ref
  • func (r Ref) IsNull() bool

Variables

var False = Ref{/* contains filtered or unexported fields */}

False wraps the False singleton.

CPython: Include/internal/pycore_stackref.h PyStackRef_False

var None = Ref{/* contains filtered or unexported fields */}

None wraps the None singleton.

CPython: Include/internal/pycore_stackref.h PyStackRef_None

var Null = Ref{}

Null is the sentinel for absent values: unbound fast locals, cleared stack slots after a pop.

CPython: Include/internal/pycore_stackref.h PyStackRef_NULL

var True = Ref{/* contains filtered or unexported fields */}

True wraps the True singleton.

CPython: Include/internal/pycore_stackref.h PyStackRef_True

Types

type Ref

type Ref struct {
	// contains filtered or unexported fields
}

Ref is a tagged stack value. In the GIL build it is just an objects.Object wrapper; v0.14 will pack a deferred-refcount tag bit alongside the pointer for the free-threaded build.

CPython: Include/internal/pycore_stackref.h _PyStackRef

func FromObject

func FromObject(o objects.Object) Ref

FromObject wraps a strong reference. The caller transfers ownership of the reference to the returned stackref.

CPython: Include/internal/pycore_stackref.h PyStackRef_FromPyObjectSteal

func FromObjectImmortal

func FromObjectImmortal(o objects.Object) Ref

FromObjectImmortal wraps an immortal singleton. In CPython this avoids touching the refcount at all; in gopy it is an alias for FromObject because Go's GC handles immortality differently.

CPython: Include/internal/pycore_stackref.h PyStackRef_FromPyObjectImmortal

func FromObjectNew

func FromObjectNew(o objects.Object) Ref

FromObjectNew wraps a new strong reference. CPython bumps the refcount; gopy relies on Go's GC, so this is structurally the same as FromObject. The separate name keeps the eval loop readable and matches CPython's PyStackRef_FromPyObjectNew sites.

CPython: Include/internal/pycore_stackref.h PyStackRef_FromPyObjectNew

func (Ref) AsObject

func (r Ref) AsObject() objects.Object

AsObject extracts the underlying object as a borrowed reference. The caller must not retain the result past the lifetime of the stackref.

CPython: Include/internal/pycore_stackref.h PyStackRef_AsPyObjectBorrow

func (Ref) AsObjectSteal

func (r Ref) AsObjectSteal() objects.Object

AsObjectSteal extracts the underlying object and consumes the stackref. The caller takes ownership of the reference.

CPython: Include/internal/pycore_stackref.h PyStackRef_AsPyObjectSteal

func (Ref) Close

func (r Ref) Close()

Close releases a stackref. Pairs with FromObject. In the GIL build this is a no-op (Go's GC reclaims the underlying object once the last reference drops); the call site exists so v0.14 can plug in deferred-refcount drops.

CPython: Include/internal/pycore_stackref.h PyStackRef_CLOSE

func (Ref) Dup

func (r Ref) Dup() Ref

Dup returns a duplicate strong reference to the same object.

CPython: Include/internal/pycore_stackref.h PyStackRef_DUP

func (Ref) IsNull

func (r Ref) IsNull() bool

IsNull reports whether the ref is the sentinel null.

CPython: Include/internal/pycore_stackref.h PyStackRef_IsNull