contextvar

Documentation

Index

• Variables
• type Context
  • func CopyCurrent(ts *state.Thread) *Context
  • func NewContext() *Context
  • func (c *Context) Copy() *Context
  • func (c *Context) Enter(ts *state.Thread) error
  • func (c *Context) Eq(other *Context) (bool, error)
  • func (c *Context) Exit(ts *state.Thread) error
  • func (c *Context) Get(cv *ContextVar) (objects.Object, bool, error)
  • func (c *Context) Len() int
  • func (c *Context) Run(ts *state.Thread, fn func() (objects.Object, error)) (objects.Object, error)
• type ContextVar
  • func NewContextVar(name string, defaultVal objects.Object, hasDefault bool) *ContextVar
  • func (cv *ContextVar) Default() (objects.Object, bool)
  • func (cv *ContextVar) Get(ts *state.Thread) (objects.Object, error)
  • func (cv *ContextVar) GetWithDefault(ts *state.Thread, def objects.Object) (objects.Object, error)
  • func (cv *ContextVar) Name() string
  • func (cv *ContextVar) Reset(ts *state.Thread, tok *Token) error
  • func (cv *ContextVar) Set(ts *state.Thread, val objects.Object) (*Token, error)
• type Token
  • func (t *Token) OldValue() objects.Object
  • func (t *Token) Used() bool
  • func (t *Token) Var() *ContextVar

Variables

var (
	ContextType    = objects.NewType("Context", []*objects.Type{objects.ObjectType()})
	ContextVarType = objects.NewType("ContextVar", []*objects.Type{objects.ObjectType()})
	TokenType      = objects.NewType("Token", []*objects.Type{objects.ObjectType()})
)

ContextType, ContextVarType, TokenType are the runtime types for the three classes the _contextvars module exposes.

var Missing objects.Object = newTokenMissing()

Missing is the public Token.MISSING sentinel. Two pointers compare equal only when they reference this singleton.

CPython: Python/context.c:1338 _Py_SINGLETON(context_token_missing)

Types

type Context

type Context struct {
	objects.Header
	// contains filtered or unexported fields
}

Context is the immutable PEP 567 mapping from ContextVar to value. vars is the persistent HAMT; prev links the pre-Run context the thread was running in, so Exit can restore it. entered guards against double-entry, matching ctx_entered in CPython.

CPython: Python/context.c:408 PyContext

func CopyCurrent

func CopyCurrent(ts *state.Thread) *Context

CopyCurrent snapshots the thread's current context. If the thread has no context yet, a fresh empty one is installed first, matching context_get's lazy initialisation.

CPython: Python/context.c:91 PyContext_CopyCurrent

func NewContext

func NewContext() *Context

NewContext returns a fresh empty Context.

CPython: Python/context.c:439 context_new_empty

func (*Context) Copy

func (c *Context) Copy() *Context

Copy returns a shallow snapshot of c. The new Context shares the HAMT with c (the HAMT is immutable, so sharing is safe) but starts with prev=nil and entered=false.

CPython: Python/context.c:84 PyContext_Copy

func (*Context) Enter

func (c *Context) Enter(ts *state.Thread) error

Enter pushes c onto the thread's context stack. Returns an error (RuntimeError) if c is already entered.

CPython: Python/context.c:194 _PyContext_Enter

func (*Context) Eq

func (c *Context) Eq(other *Context) (bool, error)

Eq reports whether two contexts hold the same bindings. Defers to hamt.Eq.

CPython: Python/context.c:550 context_tp_richcompare

func (*Context) Exit

func (c *Context) Exit(ts *state.Thread) error

Exit pops c from the thread's context stack. Returns an error if c has not been entered or if the thread state currently references a different context.

CPython: Python/context.c:223 _PyContext_Exit

func (*Context) Get

func (c *Context) Get(cv *ContextVar) (objects.Object, bool, error)

Get reads cv from c without going through any cache. found==false means the variable is not bound in this context.

CPython: Python/context.c:584 context_tp_subscript (lookup half)

func (*Context) Len

func (c *Context) Len() int

Len reports the number of bound variables.

CPython: Python/context.c:577 context_tp_len

func (*Context) Run

func (c *Context) Run(ts *state.Thread, fn func() (objects.Object, error)) (objects.Object, error)

Run enters c, calls fn(args...), and exits c, even if fn raises. Mirrors PyContext.run from the Python side.

CPython: Python/context.c:706 context_run

type ContextVar

type ContextVar struct {
	objects.Header
	// contains filtered or unexported fields
}

ContextVar is the Python-level context variable. The cache fields match CPython's var_cached / var_cached_tsid / var_cached_tsver. hasDefault distinguishes "no default" from "default=None"; CPython uses NULL on the C side for the same purpose. cacheMu guards the cache slot: CPython relies on the GIL to serialize writes, but gopy runs goroutines truly in parallel so we need an explicit lock.

CPython: Python/context.c:861 contextvar_new

func NewContextVar

func NewContextVar(name string, defaultVal objects.Object, hasDefault bool) *ContextVar

NewContextVar creates a ContextVar named name with an optional default. Pass hasDefault=false to create a variable with no default; in that case Get raises LookupError when the variable is unset.

CPython: Python/context.c:861 contextvar_new / 261 PyContextVar_New

func (*ContextVar) Default

func (cv *ContextVar) Default() (objects.Object, bool)

Default returns the (defaultVal, hasDefault) pair the variable was constructed with.

func (*ContextVar) Get

func (cv *ContextVar) Get(ts *state.Thread) (objects.Object, error)

Get returns the value bound to cv in the thread's current context. If the variable is not bound, returns the default the ContextVar was constructed with. Raises LookupError when there is no default. The (cachedTSID, cachedVer) cache short-circuits the HAMT walk on repeat lookups.

CPython: Python/context.c:274 PyContextVar_Get

func (*ContextVar) GetWithDefault

func (cv *ContextVar) GetWithDefault(ts *state.Thread, def objects.Object) (objects.Object, error)

GetWithDefault matches PyContextVar_Get's `def != NULL` branch: the supplied default overrides the ContextVar's stored default and suppresses the LookupError path.

CPython: Python/context.c:325 PyContextVar_Get (def != NULL branch)

func (*ContextVar) Name

func (cv *ContextVar) Name() string

Name returns the variable's name as a Go string.

func (*ContextVar) Reset

func (cv *ContextVar) Reset(ts *state.Thread, tok *Token) error

Reset undoes the cv.Set call that produced tok. The token must be from the same context and must not have been used before.

CPython: Python/context.c:371 PyContextVar_Reset

func (*ContextVar) Set

func (cv *ContextVar) Set(ts *state.Thread, val objects.Object) (*Token, error)

Set binds cv to val in the thread's current context (allocating an empty context first if the thread has none) and returns a Token that Reset can use to restore the prior binding.

CPython: Python/context.c:340 PyContextVar_Set / 776 contextvar_set

type Token

type Token struct {
	objects.Header
	// contains filtered or unexported fields
}

Token is the return value of ContextVar.Set; it carries enough state for ContextVar.Reset to undo the set. hadOld is the CPython-side `tok_oldval == NULL` distinction made explicit: hadOld==false means the variable was unset before, so Reset must delete the key rather than rebind it.

CPython: Python/context.c:1115 PyContextToken

func (*Token) OldValue

func (t *Token) OldValue() objects.Object

OldValue returns the prior value of the variable, or the Token.MISSING singleton when the variable was previously unset.

CPython: Python/context.c:1204 token_get_old_value

func (*Token) Used

func (t *Token) Used() bool

Used reports whether Reset has consumed t. CPython exposes the same flag indirectly via the "<Token used ...>" repr.

CPython: Python/context.c:1296 tok->tok_used

func (*Token) Var

func (t *Token) Var() *ContextVar

Var returns the ContextVar this token was minted by.

CPython: Python/context.c:1198 token_get_var