libcontext

Documentation

Index

• func BackgroundContextWithCancellationDelayer() context.Context
• func CleanupCancellationDelayer(ctx context.Context) error
• func EnableDelayedCancellationWithGracePeriod(ctx context.Context, timeout time.Duration) error
• func NewContextReplayable(ctx context.Context, change CtxReplayFunc) context.Context
• func NewContextWithCancellationDelayer(ctx context.Context) (newCtx context.Context, err error)
• func NewContextWithReplayFrom(ctx context.Context) (context.Context, error)
• type ContextAlreadyHasCancellationDelayerError
  • func (e ContextAlreadyHasCancellationDelayerError) Error() string
• type CtxCancellationDelayerKeyType
• type CtxNotReplayableError
  • func (e CtxNotReplayableError) Error() string
• type CtxReplayFunc
• type CtxReplayKeyType
• type NoCancellationDelayerError
  • func (e NoCancellationDelayerError) Error() string

Functions

func BackgroundContextWithCancellationDelayer

func BackgroundContextWithCancellationDelayer() context.Context

BackgroundContextWithCancellationDelayer generate a "Background" context that is cancellation delayable

func CleanupCancellationDelayer

func CleanupCancellationDelayer(ctx context.Context) error

CleanupCancellationDelayer cleans up a context (ctx) that is cancellation delayable and makes the go routine spawned in NewContextWithCancellationDelayer exit. As part of the cleanup, this also causes the cancellation delayable context to be canceled, no matter whether the timeout passed into the EnableDelayedCancellationWithGracePeriod has passed or not.

Ideally, the parent ctx's cancelFunc is always called upon completion of handling a request, in which case this wouldn't be necessary.

func EnableDelayedCancellationWithGracePeriod

func EnableDelayedCancellationWithGracePeriod(ctx context.Context, timeout time.Duration) error

EnableDelayedCancellationWithGracePeriod can be called on a "cancellation delayable" context produced by NewContextWithCancellationDelayer, to enable delayed cancellation for ctx. This is useful to indicate that the operation(s) associated with the context has entered a critical state, and it should not be canceled until after timeout or CleanupCancellationDelayer is called.

Note that if EnableDelayedCancellationWithGracePeriod is called for the second time, and the grace period has started due to a cancellation, the grace period would not be extended (i.e. timeout has no effect in this case). Although in this case, no error is returned, since the delayed cancellation is already enabled.

func NewContextReplayable

func NewContextReplayable(
	ctx context.Context, change CtxReplayFunc) context.Context

NewContextReplayable creates a new context from ctx, with change applied. It also makes this change replayable by NewContextWithReplayFrom. When replayed, the resulting context is replayable as well.

It is important that all WithValue-ish mutations on ctx is done "replayably" (with NewContextReplayable) if any delayed cancellation is used, e.g. through EnableDelayedCancellationWithGracePeriod,

func NewContextWithCancellationDelayer

func NewContextWithCancellationDelayer(
	ctx context.Context) (newCtx context.Context, err error)

NewContextWithCancellationDelayer creates a new context out of ctx. All replay functions attached to ctx are run on the new context. In addition, the new context is made "cancellation delayable". That is, it disconnects the cancelFunc from ctx, and watch for the cancellation. When cancellation happens, it checks if delayed cancellation is enabled for the associated context. If so, it waits until it's disabled before cancelling the new context. This provides a hacky way to allow finer control over cancellation.

Note that, it's important to call context.WithCancel (or its friends) before this function if those cancellations need to be controllable ("cancellation delayable"). Otherwise, the new cancelFunc is inherently NOT ("cancellation delayable").

If this function is called, it is caller's responsibility to either 1) cancel ctx (the context passed in); or 2) call CleanupCancellationDelayer; when operations associated with the context is done. Otherwise it leaks go routines!

func NewContextWithReplayFrom

func NewContextWithReplayFrom(ctx context.Context) (context.Context, error)

NewContextWithReplayFrom constructs a new context out of ctx by calling all attached replay functions. This disconnects any existing context.CancelFunc.

Types

type ContextAlreadyHasCancellationDelayerError

type ContextAlreadyHasCancellationDelayerError struct{}

ContextAlreadyHasCancellationDelayerError is returned when NewContextWithCancellationDelayer is called for the second time on the same ctx, which is not supported yet.

func (ContextAlreadyHasCancellationDelayerError) Error

func (e ContextAlreadyHasCancellationDelayerError) Error() string

type CtxCancellationDelayerKeyType

type CtxCancellationDelayerKeyType int

CtxCancellationDelayerKeyType is a type for the context key for using cancellationDelayer

const (
	// CtxCancellationDelayerKey is a context key for using cancellationDelayer
	CtxCancellationDelayerKey CtxCancellationDelayerKeyType = iota
)

type CtxNotReplayableError

type CtxNotReplayableError struct{}

CtxNotReplayableError is returned when NewContextWithReplayFrom is called on a ctx with no replay func.

func (CtxNotReplayableError) Error

func (e CtxNotReplayableError) Error() string

type CtxReplayFunc

type CtxReplayFunc func(ctx context.Context) context.Context

CtxReplayFunc is a function for replaying a series of changes done on a context.

type CtxReplayKeyType

type CtxReplayKeyType int

CtxReplayKeyType is a type for the context key for CtxReplayFunc

const (
	// CtxReplayKey is a context key for CtxReplayFunc
	CtxReplayKey CtxReplayKeyType = iota
)

type NoCancellationDelayerError

type NoCancellationDelayerError struct{}

NoCancellationDelayerError is returned when EnableDelayedCancellationWithGracePeriod or ExitCritical are called on a ctx without Critical Awareness

func (NoCancellationDelayerError) Error

func (e NoCancellationDelayerError) Error() string