ctxkey

package
v1.60.0 Latest Latest
Warning

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

Go to latest
Published: Feb 15, 2024 License: BSD-3-Clause Imports: 3 Imported by: 6

Documentation

Overview

ctxkey provides type-safe key-value pairs for use with context.Context.

Example usage:

// Create a context key.
var TimeoutKey = ctxkey.New("mapreduce.Timeout", 5*time.Second)

// Store a context value.
ctx = mapreduce.TimeoutKey.WithValue(ctx, 10*time.Second)

// Load a context value.
timeout := mapreduce.TimeoutKey.Value(ctx)
... // use timeout of type time.Duration

This is inspired by https://go.dev/issue/49189.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Key

type Key[Value any] struct {
	// contains filtered or unexported fields
}

Key is a generic key type associated with a specific value type.

A zero Key is valid where the Value type itself is used as the context key. This pattern should only be used with locally declared Go types, otherwise different packages risk producing key conflicts.

Example usage:

type peerInfo struct { ... }           // peerInfo is a locally declared type
var peerInfoKey ctxkey.Key[peerInfo]
ctx = peerInfoKey.WithValue(ctx, info) // store a context value
info = peerInfoKey.Value(ctx)          // load a context value

func New

func New[Value any](name string, defaultValue Value) Key[Value]

New constructs a new context key with an associated value type where the default value for an unpopulated value is the provided value.

The provided name is an arbitrary name only used for human debugging. As a convention, it is recommended that the name be the dot-delimited combination of the package name of the caller with the variable name. If the name is not provided, then the name of the Value type is used. Every key is unique, even if provided the same name.

Example usage:

package mapreduce
var NumWorkersKey = ctxkey.New("mapreduce.NumWorkers", runtime.NumCPU())

func (Key[Value]) Has

func (key Key[Value]) Has(ctx context.Context) (ok bool)

Has reports whether the context has a value for this key.

func (Key[Value]) String

func (key Key[Value]) String() string

String returns the name of the key.

func (Key[Value]) Value

func (key Key[Value]) Value(ctx context.Context) (v Value)

Value returns the value in the context associated with this key. If the value is not present, it returns the default value.

func (Key[Value]) ValueOk

func (key Key[Value]) ValueOk(ctx context.Context) (v Value, ok bool)

ValueOk returns the value in the context associated with this key and also reports whether it was present. If the value is not present, it returns the default value.

func (Key[Value]) WithValue

func (key Key[Value]) WithValue(parent context.Context, val Value) context.Context

WithValue returns a copy of parent in which the value associated with key is val.

It is a type-safe equivalent of context.WithValue.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL