state

Documentation

Overview

Package state ports the skeleton of cpython/Python/pystate.c. v0.3 ships only the structs and the exception slot needed by the errors package; the lifecycle (Initialize/Finalize/NewInterpreter) lands in v0.7.

Index

• type Exception
• type Interpreter
  • func (i *Interpreter) AttachThread() *Thread
  • func (i *Interpreter) Runtime() *Runtime
  • func (i *Interpreter) Threads() []*Thread
• type Runtime
  • func NewRuntime() *Runtime
  • func (r *Runtime) DropInterpreters()
  • func (r *Runtime) Interpreters() []*Interpreter
  • func (r *Runtime) NewInterpreter() *Interpreter
• type Thread
  • func NewThread() *Thread
  • func (t *Thread) Context() any
  • func (t *Thread) ContextVersion() uint64
  • func (t *Thread) CurrentException() Exception
  • func (t *Thread) HandledException() Exception
  • func (t *Thread) ID() uint64
  • func (t *Thread) Interp() *Interpreter
  • func (t *Thread) SetContext(ctx any)
  • func (t *Thread) SetException(exc Exception)
  • func (t *Thread) SetHandledException(exc Exception)
  • func (t *Thread) SwapException(exc Exception) Exception

Types

type Exception

type Exception interface {
	// IsException is a marker so unrelated types cannot satisfy this
	// interface by accident.
	IsException()
}

Exception is the interface state stores in the per-thread exception slot. The concrete type lives in the errors package; state knows only the marker method so the dependency graph is errors to state, not the reverse.

CPython: Include/cpython/pyerrors.h:L11 PyBaseExceptionObject

type Interpreter

type Interpreter struct {
	Config any

	Finalizing int

	// Monitors is the per-interpreter PEP 669 monitoring state. Lazy-
	// allocated by NewInterpreter so unused interpreters do not pay
	// the (small) cost of the callable / version tables.
	//
	// CPython: Include/internal/pycore_interp_structs.h:948 monitors
	Monitors *monitor.InterpState

	// Optimizer is the per-interpreter Tier-2 executor list and
	// pending-deletion bookkeeping. Stored as any so package state
	// stays independent of optimizer; the optimizer package owns the
	// concrete *optimizer.InterpState type and asserts it back at
	// use sites.
	//
	// CPython: Include/internal/pycore_interp_structs.h executor_list_head /
	// executor_deletion_list_head / executor_deletion_list_remaining_capacity
	Optimizer any

	// Watchers is the per-interpreter dict / type watcher registry the
	// Tier-2 optimizer hangs invalidation callbacks on. Stored as any
	// so package state stays independent of optimizer; the optimizer
	// package owns the concrete *optimizer.WatcherTable type.
	//
	// CPython: Include/internal/pycore_interp_structs.h dict_state.watchers /
	// type_watchers
	Watchers any

	// Builtins is the canonical builtins dict. The Tier-2 globals
	// folder bails when a frame's f_builtins points elsewhere (i.e. a
	// non-default builtins dict). Stored as any so package state stays
	// independent of objects; the optimizer asserts it back to *Dict
	// at use sites.
	//
	// CPython: Include/internal/pycore_interp.h PyInterpreterState.builtins
	Builtins any

	// BuiltinDictMutations counts how many times the builtins dict has
	// been replaced wholesale (the rare event CPython tracks under
	// rare_events.builtin_dict). The Tier-2 folder stops specializing
	// _LOAD_GLOBAL_BUILTINS once this exceeds the cap.
	//
	// CPython: Include/internal/pycore_interp_structs.h rare_events.builtin_dict
	BuiltinDictMutations int
	// contains filtered or unexported fields
}

Interpreter is the per-interpreter state. v0.7 fills in the dict of builtins, sys module, import locks, and so on.

Config is the *initconfig.PyConfig the lifecycle stamps in during pyinit_core. Stored as any so package state stays independent of initconfig; the lifecycle layer is the sole reader and re-asserts the concrete type at use sites.

Finalizing is the bool flag the lifecycle flips during Py_Finalize before clearing modules; it stays at 1 until the interpreter is dropped from the runtime.

CPython: Include/internal/pycore_interp.h:L113 PyInterpreterState

func (*Interpreter) AttachThread

func (i *Interpreter) AttachThread() *Thread

AttachThread builds a thread state bound to i and registers it. Mirrors PyThreadState_New for the simple case where the thread is being attached fresh (no detached predecessor).

CPython: Python/pystate.c:L915 PyThreadState_New

func (*Interpreter) Runtime

func (i *Interpreter) Runtime() *Runtime

Runtime returns the runtime that owns i.

CPython: Python/pystate.c:_PyInterpreterState_GetRuntime

func (*Interpreter) Threads

func (i *Interpreter) Threads() []*Thread

Threads returns the threads attached to i in attach order. The slice aliases internal state; treat it as read-only.

type Runtime

type Runtime struct {
	Preinitialized  int
	CoreInitialized int
	Initialized     int
	// contains filtered or unexported fields
}

Runtime is the process-wide runtime state. Mirrors _PyRuntimeState.

Preinitialized, CoreInitialized, and Initialized are the staged init flags the lifecycle layer flips as it walks pre-init / core init / main init. They are exported so the lifecycle and finalize paths in package lifecycle can read and set them without an accessor sprawl.

CPython: Include/internal/pycore_runtime_structs.h:171 preinitialized

func NewRuntime

func NewRuntime() *Runtime

NewRuntime allocates a fresh process-wide runtime. The lifecycle layer calls this on its way through pyinit_core; tests poke at it directly to build a runtime without going through the full init staging.

CPython: Python/pystate.c:_PyRuntime_Initialize

func (*Runtime) DropInterpreters

func (r *Runtime) DropInterpreters()

DropInterpreters detaches every interpreter from r. Used by lifecycle.Finalize to reset the runtime so a subsequent Initialize starts from a clean slate. Each detached interpreter has its runtime backpointer cleared so dangling references stop sharing state.

CPython: Python/pylifecycle.c:_PyInterpreterState_DeleteAll

func (*Runtime) Interpreters

func (r *Runtime) Interpreters() []*Interpreter

Interpreters returns the interpreters owned by r in registration order. The slice aliases internal state; treat it as read-only.

func (*Runtime) NewInterpreter

func (r *Runtime) NewInterpreter() *Interpreter

NewInterpreter allocates an interpreter owned by r and registers it in r.interpreters. The first call returns the main interpreter; later calls (sub-interpreters) land in v0.13.

CPython: Python/pystate.c:_PyInterpreterState_Enable

type Thread

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

Thread is the per-goroutine state. v0.3 carries the current exception pointer; v0.6 adds the frame stack and v0.7 adds the dict/globals slots.

id is the per-thread identifier the contextvars cache compares against (matches PyThreadState.id). ctx holds the current *contextvar.Context as an untyped any so package state stays free of a contextvar import. ctxVersion is bumped on every Enter / Exit so the ContextVar tsid+version cache invalidates correctly.

CPython: Include/cpython/pystate.h:L75 PyThreadState

func NewThread

func NewThread() *Thread

NewThread builds a thread state owned by an implicit default interpreter. v0.3 has no real lifecycle; tests use this to obtain a Thread value to pass to errors.Set*.

CPython: Python/pystate.c:L915 PyThreadState_New

func (*Thread) Context

func (t *Thread) Context() any

Context returns the current context, stored as any to avoid importing contextvar. The contextvar package re-asserts the concrete *Context type at use sites. nil signals "no context yet"; the contextvar layer lazily allocates an empty one on first use, matching CPython's context_get.

CPython: Include/cpython/pystate.h PyThreadState.context

func (*Thread) ContextVersion

func (t *Thread) ContextVersion() uint64

ContextVersion returns the version counter that increments on every context switch. The ContextVar cache stamps this value into the entry on every set / get so a switch invalidates stale reads.

CPython: Include/cpython/pystate.h PyThreadState.context_ver

func (*Thread) CurrentException

func (t *Thread) CurrentException() Exception

CurrentException returns the current exception or nil. Mirrors _PyErr_Occurred.

CPython: Python/errors.c:L138 _PyErr_Occurred

func (*Thread) HandledException

func (t *Thread) HandledException() Exception

HandledException returns the currently-handled exception (the one a running except handler is processing), or nil. Mirrors the exc_info->exc_value slot in CPython's _PyErr_StackItem chain. The raised-exception slot (CurrentException) is cleared on handler entry; this slot persists for sys.exc_info() to read.

CPython: Include/internal/pycore_runtime.h _PyErr_StackItem

func (*Thread) ID

func (t *Thread) ID() uint64

ID returns the per-thread identifier. Used by the ContextVar cache.

CPython: Include/cpython/pystate.h PyThreadState.id

func (*Thread) Interp

func (t *Thread) Interp() *Interpreter

Interp returns the interpreter that owns t. Mirrors PyThreadState_GetInterpreter.

CPython: Python/pystate.c:L2114 PyThreadState_GetInterpreter

func (*Thread) SetContext

func (t *Thread) SetContext(ctx any)

SetContext installs a new current context. The contextvar layer passes a *contextvar.Context (or nil to clear). Each call bumps ContextVersion so the per-ContextVar cache invalidates.

CPython: Python/context.c:L184 context_switched

func (*Thread) SetException

func (t *Thread) SetException(exc Exception)

SetException installs exc as the current exception. exc may be nil to clear.

CPython: Python/errors.c:L83 _PyErr_SetObject (excerpt)

func (*Thread) SetHandledException

func (t *Thread) SetHandledException(exc Exception)

SetHandledException replaces the handled-exception slot. Passing nil clears it. CPython: bytecodes.c POP_EXCEPT / PUSH_EXC_INFO maintain the exc_info stack; this method is the equivalent setter.

func (*Thread) SwapException

func (t *Thread) SwapException(exc Exception) Exception

SwapException atomically replaces the current exception and returns the old value. Used by errors.Fetch.

CPython: Python/errors.c:L460 _PyErr_Fetch