context

Documentation

Overview

Package context defines the context types, which carry information defined for a specific scope (application, request, ...) A context can be passed across API boundaries and between processes.

Inbound requests to a server should create a Context, and outbound calls to servers should accept a Context. The chain of function calls between must propagate the Context, optionally replacing it with a modified copy.

Programs that use Contexts should follow these rules to keep interfaces consistent across packages and enable static analysis tools to check context propagation

Index

• Variables
• func LegWithContext(ctx context.Context, t Leg) context.Context
• func Shipment(ctx context.Context, key string) interface{}
• func ShipmentRange(ctx context.Context, f func(key string, value interface{}) bool)
• func TransitWithContext(ctx context.Context, t Transit) context.Context
• func WithLogger(ctx context.Context, l log.Logger) context.Context
• func WithShipment(parent context.Context, key string, val interface{}) context.Context
• func WithTracer(ctx context.Context, tr tracing.Tracer) context.Context
• type Context
  • func Background() Context
  • func TODO() Context
  • func WithCancel(parent Context) (Context, context.CancelFunc)
  • func WithDeadline(parent Context, d time.Time) (Context, context.CancelFunc)
  • func WithTimeout(parent Context, timeout time.Duration) (Context, context.CancelFunc)
  • func WithValue(parent Context, key, val interface{}) Context
• type Leg
  • func LegFromContext(ctx context.Context) Leg
• type Step
• type Transit
  • func NewTransitWithContext(ctx context.Context) (context.Context, Transit)
  • func TransitFromContext(ctx context.Context) Transit

Variables

var (

	// ErrInvalidTransitBinary occurs when UnmarshalBinary is called on Transit
	// with an invalid binary representation
	ErrInvalidTransitBinary = errors.New("invalid transit binary representation")

	// ErrInvalidTransitText occurs when UnmarshalText is called on Transit
	// with an invalid textual representation
	ErrInvalidTransitText = errors.New("invalid transit textual representation")
)

var Canceled = context.Canceled

Canceled is the error returned by Context.Err when the context is canceled.

var DeadlineExceeded = context.DeadlineExceeded

DeadlineExceeded is the error returned by Context.Err when the context's deadline passes.

var TransitFactory = func() Transit {
	return &transit{
		ID:      uuid.New().String(),
		Stepper: newStepper(),
	}
}

TransitFactory creates empty Transit instances

Functions

func LegWithContext

func LegWithContext(ctx context.Context, t Leg) context.Context

LegWithContext injects `Leg` to context

func Shipment

func Shipment(ctx context.Context, key string) interface{}

Shipment returns the shipment associated with this context for key, or nil if no value is associated with key. Successive calls to Value with the same key returns the same result.

func ShipmentRange

func ShipmentRange(ctx context.Context, f func(key string, value interface{}) bool)

ShipmentRange calls f sequentially for each shipment in the context stack. If f returns false, range stops the iteration.

func TransitWithContext

func TransitWithContext(ctx context.Context, t Transit) context.Context

TransitWithContext injects `Transit` to context

func WithLogger

func WithLogger(ctx context.Context, l log.Logger) context.Context

WithLogger returns a copy of parent with a contextualised `log.Logger`

func WithShipment

func WithShipment(parent context.Context, key string, val interface{}) context.Context

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

Use context Values only for request-scoped data that transits processes and APIs, not for passing optional parameters to functions.

The provided key must be comparable and should not be of type string or any other built-in type to avoid collisions between packages using context. Users of WithValue should define their own types for keys. To avoid allocating when assigning to an interface{}, context keys often have concrete type struct{}. Alternatively, exported context key variables' static type should be a pointer or interface.

func WithTracer

func WithTracer(ctx context.Context, tr tracing.Tracer) context.Context

WithTracer returns a copy of parent with a contextualised `log.Tracer`

Types

type Context

type Context context.Context

A Context carries a deadline, a cancelation signal, and other values across API boundaries.

Context's methods may be called by multiple goroutines simultaneously.

func Background

func Background() Context

Background returns a non-nil, empty Context. It is never canceled, has no values, and has no deadline. It is typically used by the main function, initialization, and tests, and as the top-level Context for incoming requests.

func TODO

func TODO() Context

TODO returns a non-nil, empty Context. Code should use context.TODO when it's unclear which Context to use or it is not yet available (because the surrounding function has not yet been extended to accept a Context parameter). TODO is recognized by static analysis tools that determine whether Contexts are propagated correctly in a program.

func WithCancel

func WithCancel(parent Context) (Context, context.CancelFunc)

WithCancel returns a copy of parent with a new Done channel. The returned context's Done channel is closed when the returned cancel function is called or when the parent context's Done channel is closed, whichever happens first.

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete.

func WithDeadline

func WithDeadline(parent Context, d time.Time) (Context, context.CancelFunc)

WithDeadline returns a copy of the parent context with the deadline adjusted to be no later than d. If the parent's deadline is already earlier than d, WithDeadline(parent, d) is semantically equivalent to parent. The returned context's Done channel is closed when the deadline expires, when the returned cancel function is called, or when the parent context's Done channel is closed, whichever happens first.

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete.

func WithTimeout

func WithTimeout(parent Context, timeout time.Duration) (Context, context.CancelFunc)

WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete:

func slowOperationWithTimeout(ctx context.Context) (Result, error) {
	ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
	defer cancel()  // releases resources if slowOperation completes before timeout elapses
	return slowOperation(ctx)
}

func WithValue

func WithValue(parent Context, key, val interface{}) Context

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

Use context Values only for request-scoped data that transits processes and APIs, not for passing optional parameters to functions.

The provided key must be comparable and should not be of type string or any other built-in type to avoid collisions between packages using context. Users of WithValue should define their own types for keys. To avoid allocating when assigning to an interface{}, context keys often have concrete type struct{}. Alternatively, exported context key variables' static type should be a pointer or interface.

type Leg

type Leg interface {
	UUID() string
	ShortID() string
	// Tick increments the stepper
	Tick() uint
	// Step returns a string representation of the current step
	Step() Step
}

A Leg is a point-to-point request bounded by a process

func LegFromContext

func LegFromContext(ctx context.Context) Leg

LegFromContext extracts `Leg` from context and returns `nil` when no instance of `Leg` can be found

type Step

type Step interface {
	fmt.Stringer
}

type Transit

type Transit interface {
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
	encoding.TextMarshaler
	encoding.TextUnmarshaler

	Leg

	// Transmit returns a new instance of `Transmit` that can be serialised onto
	// an outbound request.
	Transmit() Transit
}

A Transit is request context that goes beyond a process. It is composed of multiple `Leg`s.

func NewTransitWithContext

func NewTransitWithContext(ctx context.Context) (context.Context, Transit)

NewTransitWithContext injects a new `Transit` to context

func TransitFromContext

func TransitFromContext(ctx context.Context) Transit

TransitFromContext extracts `Transit` from context and returns `nil` when no instance of `Transit` can be found