context

Documentation

Overview

Package context defines an internal context type.

The given Context conforms to the standard Go context, but mandates additional methods that are specific to the kernel internals. Note however, that the Context described by this package carries additional constraints regarding concurrent access and retaining beyond the scope of a call.

See the Context type for complete details.

Index

• type Blocker
• type Context
  • func Background() Context
  • func WithValue(parent Context, key, val any) Context
• type NoTask
  • func (nt *NoTask) Block(C <-chan struct{}) error
  • func (nt *NoTask) BlockOn(w waiter.Waitable, mask waiter.EventMask) bool
  • func (nt *NoTask) BlockWithTimeoutOn(w waiter.Waitable, mask waiter.EventMask, duration time.Duration) (time.Duration, bool)
  • func (nt *NoTask) Interrupt()
  • func (nt *NoTask) Interrupted() bool
  • func (*NoTask) UninterruptibleSleepFinish(bool)
  • func (*NoTask) UninterruptibleSleepStart(bool)

Types

type Blocker

type Blocker interface {
	// Interrupt interrupts any Block operations.
	Interrupt()

	// Interrupted notes whether this context is Interrupted.
	Interrupted() bool

	// BlockOn blocks until one of the previously registered events occurs,
	// or some external interrupt (cancellation).
	//
	// The return value should indicate whether the wake-up occurred as a
	// result of the requested event (versus an external interrupt).
	BlockOn(waiter.Waitable, waiter.EventMask) bool

	// Block blocks until an event is received from C, or some external
	// interrupt. It returns nil if an event is received from C and an err if t
	// is interrupted.
	Block(C <-chan struct{}) error

	// BlockWithTimeoutOn blocks until either the conditions of Block are
	// satisfied, or the timeout is hit. Note that deadlines are not supported
	// since the notion of "with respect to what clock" is not resolved.
	//
	// The return value is per BlockOn.
	BlockWithTimeoutOn(waiter.Waitable, waiter.EventMask, time.Duration) (time.Duration, bool)

	// UninterruptibleSleepStart indicates the beginning of an uninterruptible
	// sleep state (equivalent to Linux's TASK_UNINTERRUPTIBLE). If deactivate
	// is true and the Context represents a Task, the Task's AddressSpace is
	// deactivated.
	UninterruptibleSleepStart(deactivate bool)

	// UninterruptibleSleepFinish indicates the end of an uninterruptible sleep
	// state that was begun by a previous call to UninterruptibleSleepStart. If
	// activate is true and the Context represents a Task, the Task's
	// AddressSpace is activated. Normally activate is the same value as the
	// deactivate parameter passed to UninterruptibleSleepStart.
	UninterruptibleSleepFinish(activate bool)
}

Blocker represents an object with control flow hooks.

These may be used to perform blocking operations, sleep or otherwise wait, since there may be asynchronous events that require processing.

type Context

type Context interface {
	context.Context
	log.Logger
	Blocker
}

Context represents a thread of execution (hereafter "goroutine" to reflect Go idiosyncrasy). It carries state associated with the goroutine across API boundaries.

While Context exists for essentially the same reasons as Go's standard context.Context, the standard type represents the state of an operation rather than that of a goroutine. This is a critical distinction:

• Unlike context.Context, which "may be passed to functions running in different goroutines", it is *not safe* to use the same Context in multiple concurrent goroutines.

• It is *not safe* to retain a Context passed to a function beyond the scope of that function call.

In both cases, values extracted from the Context should be used instead.

func Background

func Background() Context

Background returns an empty context using the default logger. Generally, one should use the Task as their context when available, or avoid having to use a context in places where a Task is unavailable.

Using a Background context for tests is fine, as long as no values are needed from the context in the tested code paths.

The global log.SetTarget() must be called before context.Background()

func WithValue

func WithValue(parent Context, key, val any) Context

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

type NoTask

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

NoTask is an implementation of Blocker that does not block.

func (*NoTask) Block

func (nt *NoTask) Block(C <-chan struct{}) error

Block implements Blocker.Block.

func (*NoTask) BlockOn

func (nt *NoTask) BlockOn(w waiter.Waitable, mask waiter.EventMask) bool

BlockOn implements Blocker.BlockOn.

func (*NoTask) BlockWithTimeoutOn

func (nt *NoTask) BlockWithTimeoutOn(w waiter.Waitable, mask waiter.EventMask, duration time.Duration) (time.Duration, bool)

BlockWithTimeoutOn implements Blocker.BlockWithTimeoutOn.

func (*NoTask) Interrupt

func (nt *NoTask) Interrupt()

Interrupt implements Blocker.Interrupt.

func (*NoTask) Interrupted

func (nt *NoTask) Interrupted() bool

Interrupted implements Blocker.Interrupted.

func (*NoTask) UninterruptibleSleepFinish

func (*NoTask) UninterruptibleSleepFinish(bool)

UninterruptibleSleepFinish implmenents Blocker.UninterruptibleSleepFinish.

func (*NoTask) UninterruptibleSleepStart

func (*NoTask) UninterruptibleSleepStart(bool)

UninterruptibleSleepStart implmenents Blocker.UninterruptedSleepStart.