frame

package
v0.12.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Index

Constants

View Source 
const ChunkSize = 32

ChunkSize is the number of frames per chunk. CPython uses 4 KB chunks of byte-packed frame data; we use a fixed slot count because each Frame is fixed-size.

Variables

This section is empty.

Functions

func CellsStart 

func CellsStart(co *objects.Code) int

CellsStart returns the index in LocalsPlus where cell vars begin.

func FreesStart 

func FreesStart(co *objects.Code) int

FreesStart returns the index where free vars begin.

func NCellsOf 

func NCellsOf(co *objects.Code) int

NCellsOf returns the count of cell slots a code object owns.

CPython: Include/internal/pycore_code.h _PyCode_NCELLS

func NFreeOf 

func NFreeOf(co *objects.Code) int

NFreeOf returns the count of free-var slots a code object owns.

CPython: Include/internal/pycore_code.h _PyCode_NFREE

func NLocalsOf 

func NLocalsOf(co *objects.Code) int

NLocalsOf returns the count of fast-local slots a code object owns.

CPython: Include/internal/pycore_code.h _PyCode_NLOCALS

func NLocalsPlusOf 

func NLocalsPlusOf(co *objects.Code) int

NLocalsPlusOf returns the total locals+cells+frees slot count.

CPython: Include/internal/pycore_code.h _PyCode_NLOCALSPLUS

func SizeFor 

func SizeFor(co *objects.Code) int

SizeFor computes the LocalsPlus length needed to run code. Includes both the locals/cells/frees and the value-stack reservation.

CPython: Include/internal/pycore_frame.h _PyFrame_NumSlotsForCodeObject

func StackStart 

func StackStart(co *objects.Code) int

StackStart returns the index where the value stack begins.

Types

type Chunk 

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

Chunk is a single arena slab.

type Frame 

type Frame struct {
	// Code is the running bytecode. nil means a placeholder /
	// torn-down frame.
	Code *objects.Code

	// Globals, Builtins, Locals are the scope dicts. Locals is
	// nil for fast-locals frames (the common case).
	Globals  objects.Object
	Builtins objects.Object
	Locals   objects.Object

	// Func is the function object that produced this call. Held
	// as objects.Object until 1685 lands the typed Function.
	Func objects.Object

	// Previous is the caller frame. nil for thread-root frames.
	Previous *Frame

	// InstrPtr is the index into Code.Code of the next instruction.
	// PrevInstr is the index of the most recently executed
	// instruction (for RESUME after yield, and for traceback).
	InstrPtr  int
	PrevInstr int

	// StackTop is the index into LocalsPlus where the live value
	// stack ends. The stack starts at NLocalsPlus.
	StackTop int

	// LocalsPlus packs fast locals, cell vars, free vars, and the
	// value stack into one slice. Layout:
	//
	//   [ 0          .. nlocals                              )  fast locals
	//   [ nlocals    .. nlocals + ncells                     )  cells
	//   [ ...        .. nlocals + ncells + nfree (= nlocals+) )  frees
	//   [ nlocalsplus .. nlocalsplus + stacktop              )  stack
	LocalsPlus []stackref.Ref

	// Owner discriminates teardown / suspend behavior.
	Owner OwnerKind

	// ReturnOffset is set on a callee frame when the caller wants
	// the eval loop to resume at a non-default offset on return
	// (inline calls reuse this; v0.6 always uses 0).
	ReturnOffset int

	// YieldOffset is set when a generator suspends at YIELD_VALUE
	// so RESUME picks up at the right instruction.
	YieldOffset int

	// TraceLines mirrors PyFrameObject.f_trace_lines. The legacy
	// sys.settrace machinery suppresses the LINE callback when this
	// flag is false; user code sets it via frame.f_trace_lines.
	// Defaults to true to match CPython.
	//
	// CPython: Include/cpython/frameobject.h PyFrameObject.f_trace_lines
	TraceLines bool
	// TraceOpcodes mirrors PyFrameObject.f_trace_opcodes. The legacy
	// trace bridge installs INSTRUMENTED_INSTRUCTION on the running
	// frame's code only when this is true.
	//
	// CPython: Include/cpython/frameobject.h PyFrameObject.f_trace_opcodes
	TraceOpcodes bool
	// Lineno is the line number the legacy trace bridge passes to
	// the user's tracefunc. The bridge stamps it before each call
	// and clears it back to zero on the way out, mirroring
	// CPython's frame->f_lineno protocol.
	//
	// CPython: Include/cpython/frameobject.h PyFrameObject.f_lineno
	Lineno int
}

Frame is the activation record. Field order roughly mirrors _PyInterpreterFrame so the layout reads the same as CPython's; alignment is left to Go's compiler.

CPython: Include/internal/pycore_frame.h _PyInterpreterFrame

func (*Frame) Clear 

func (f *Frame) Clear()

Clear closes every live stackref (locals, cells, frees, stack) and resets Code/Globals/Builtins/Locals to nil. Used both on normal frame teardown (eval loop unwinding the call) and on the path that detaches a frame to a Generator object before resume.

CPython: Python/frame.c _PyFrame_ClearExceptCode + _PyFrame_Clear

func (*Frame) FrameBack added in v0.10.1 

func (f *Frame) FrameBack() objects.InterpreterFrame

FrameBack returns the caller's activation record, or nil at the thread root. The explicit nil return avoids handing back a typed nil wrapped in a non-nil interface.

func (*Frame) FrameBuiltins added in v0.10.1 

func (f *Frame) FrameBuiltins() objects.Object

FrameBuiltins returns f_builtins.

func (*Frame) FrameCellLocal added in v0.10.1 

func (f *Frame) FrameCellLocal(i int) objects.Object

FrameCellLocal returns the cell var at index i, or nil if unbound.

func (*Frame) FrameCode added in v0.10.1 

func (f *Frame) FrameCode() *objects.Code

FrameCode returns the running Code object.

func (*Frame) FrameFastLocal added in v0.10.1 

func (f *Frame) FrameFastLocal(i int) objects.Object

FrameFastLocal returns the fast local at index i, or nil if the slot is unbound.

func (*Frame) FrameFreeLocal added in v0.10.1 

func (f *Frame) FrameFreeLocal(i int) objects.Object

FrameFreeLocal returns the free var at index i, or nil if unbound.

func (*Frame) FrameFunc added in v0.12.0 

func (f *Frame) FrameFunc() objects.Object

FrameFunc returns the Function that produced this call, or nil for frames that were not created from a function (module init, exec).

CPython: Python/optimizer_analysis.c:156 _PyFrame_GetFunction

func (*Frame) FrameGlobals added in v0.10.1 

func (f *Frame) FrameGlobals() objects.Object

FrameGlobals returns f_globals.

func (*Frame) FrameLasti added in v0.10.1 

func (f *Frame) FrameLasti() int

FrameLasti returns the offset of the next instruction.

func (*Frame) FrameLocals added in v0.10.1 

func (f *Frame) FrameLocals() objects.Object

FrameLocals returns f_locals (nil for fast-locals frames).

func (*Frame) FrameNumCells added in v0.10.1 

func (f *Frame) FrameNumCells() int

FrameNumCells returns the count of cell slots.

func (*Frame) FrameNumFrees added in v0.10.1 

func (f *Frame) FrameNumFrees() int

FrameNumFrees returns the count of free-var slots.

func (*Frame) FrameNumLocals added in v0.10.1 

func (f *Frame) FrameNumLocals() int

FrameNumLocals returns the count of fast-local slots.

func (*Frame) Init 

func (f *Frame) Init(co *objects.Code, globals, builtins objects.Object, fn objects.Object, prev *Frame)

Init wires a freshly allocated frame to a code object. Resets the instruction pointer and stack top, and sizes LocalsPlus.

CPython: Python/frame.c _PyFrame_Initialize

func (*Frame) LocalAt 

func (f *Frame) LocalAt(i int) stackref.Ref

LocalAt returns the fast local at index i.

func (*Frame) PeekStack 

func (f *Frame) PeekStack(depth int) stackref.Ref

PeekStack returns the value at depth from the top (0 = top).

CPython: Python/ceval.c PEEK macro

func (*Frame) PopStack 

func (f *Frame) PopStack() stackref.Ref

PopStack removes and returns the top stack value.

CPython: Python/ceval.c POP macro

func (*Frame) PushStack 

func (f *Frame) PushStack(r stackref.Ref)

PushStack adds r to the top of the value stack.

CPython: Python/ceval.c PUSH macro

func (*Frame) Resume 

func (f *Frame) Resume()

Resume re-marks a generator-owned frame as eval-owned and restores the instruction pointer to YieldOffset so the next dispatch tick picks up after the suspending YIELD_VALUE.

CPython: Python/ceval.c SEND / SEND_GEN handler

func (*Frame) SetLocal 

func (f *Frame) SetLocal(i int, r stackref.Ref)

SetLocal stores r at fast-local slot i.

func (*Frame) Suspend 

func (f *Frame) Suspend(yieldOffset int)

Suspend prepares the frame for ownership transfer to a Generator object on YIELD_VALUE. Marks the owner so a subsequent FrameStack.Pop knows not to zero the slot, and records the offset where Resume should pick up. The caller is responsible for splicing the frame out of the chunk arena and into the generator.

CPython: Python/ceval.c YIELD_VALUE handler

type FrameStack 

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

FrameStack is a per-Thread chain of chunks.

CPython: Include/internal/pycore_pystate.h datastack_chunk

func New 

func New() *FrameStack

New returns an empty frame stack.

func (*FrameStack) Depth 

func (s *FrameStack) Depth() int

Depth returns the number of live frames.

func (*FrameStack) Detach 

func (s *FrameStack) Detach() *Frame

Detach removes the top frame from the chunk arena and returns it. Caller takes ownership. Used by Generator on first YIELD_VALUE so the suspended state survives past the eval loop's natural unwind.

CPython: Python/ceval.c YIELD_VALUE -> _PyFrame_MakeAndSetFrameObject

func (*FrameStack) Pop 

func (s *FrameStack) Pop()

Pop releases the top frame. It is an error to Pop more than was pushed; Pop on an empty stack is a no-op.

CPython: Python/frame.c _PyThreadState_PopFrame

func (*FrameStack) Push 

func (s *FrameStack) Push(co *objects.Code, globals, builtins, fn objects.Object, prev *Frame) *Frame

Push allocates a frame, initializes it for co, and links it as the new top of the call chain. Caller's previous top frame is passed as prev so the frame chain stays intact.

CPython: Python/frame.c _PyThreadState_PushFrame

func (*FrameStack) Top added in v0.10.1 

func (s *FrameStack) Top() *Frame

Top returns the most recently pushed frame, or nil if the stack is empty. Mirrors PyThreadState_GetFrame: the thread's view of its own activation chain. Mutating the returned frame mutates the live activation record, so callers should treat it as read-only.

CPython: Python/pystate.c:2099 PyThreadState_GetFrame

type OwnerKind 

type OwnerKind uint8

OwnerKind tracks which subsystem holds the canonical pointer to a frame. Mirrors _PyFrameOwner from pycore_frame.h.

CPython: Include/internal/pycore_frame.h _PyFrameOwner 

const (
	OwnedByEval      OwnerKind = iota // top-of-stack, owned by the eval loop
	OwnedByGenerator                  // copied to a generator object on suspend
	OwnedByThread                     // root frame for a thread
	OwnedByFrameObj                   // a Python frame object holds it
	OwnedByCstack                     // C-stack-allocated, do not free
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.