contextual

package module
v0.1.8 Latest Latest
Warning

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

 Go to latest Published: Nov 15, 2024 License: MIT Imports: 10 Imported by: 0

README

go-context

Golang Context tools

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CancelCauseWrap 

func CancelCauseWrap(cancel context.CancelFunc) context.CancelCauseFunc

func CommonLabels added in v0.1.7 

func CommonLabels(name, description string) pprof.LabelSet

func Go added in v0.1.2 

func Go[T errgroupFuncs](ctx Context, f T)

func GoLabelled added in v0.1.7 

func GoLabelled[T errgroupFuncs](ctx Context, name, description string, f T)

func Labels added in v0.1.7 

func Labels(args ...string) pprof.LabelSet

func SetLabelsFromContext added in v0.1.5 

func SetLabelsFromContext(ctx Context)

Types

type Cancellable 

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

func NewCancellable 

func NewCancellable(ctx context.Context, opts ...OptionFunc) *Cancellable

func (*Cancellable) AddValue added in v0.1.3 

func (c *Cancellable) AddValue(key any, value any)

func (*Cancellable) AsContext added in v0.1.4 

func (c *Cancellable) AsContext() context.Context

AsContext returns the contextual.Context as context.Context.

func (*Cancellable) Cancel 

func (c *Cancellable) Cancel()

Cancel calls the context.CancelFunc. A CancelFunc tells an operation to abandon its work. A CancelFunc does not wait for the work to stop. A CancelFunc may be called by multiple goroutines simultaneously. After the first call, subsequent calls to a CancelFunc do nothing.

func (*Cancellable) CancelWithCause 

func (c *Cancellable) CancelWithCause(err error)

CancelWithCause behaves like [Cancel] but additionally sets the cancellation cause. This cause can be retrieved by calling [Cause] on the canceled Context or on any of its derived Contexts.

If the context has already been canceled, CancelCauseFunc does not set the cause. For example, if childContext is derived from parentContext:

  • if parentContext is canceled with cause1 before childContext is canceled with cause2, then Cause(parentContext) == Cause(childContext) == cause1
  • if childContext is canceled with cause2 before parentContext is canceled with cause1, then Cause(parentContext) == cause1 and Cause(childContext) == cause2

func (*Cancellable) CloneWithNewContext 

func (c *Cancellable) CloneWithNewContext(ctx context.Context, cancel context.CancelCauseFunc) Context

func (*Cancellable) Deadline 

func (c *Cancellable) Deadline() (time.Time, bool)

func (*Cancellable) Done 

func (c *Cancellable) Done() <-chan struct{}

Done returns a channel that's closed when work done on behalf of this context should be canceled. Done may return nil if this context can never be canceled. Successive calls to Done return the same value. The close of the Done channel may happen asynchronously, after the cancel function returns.

func (*Cancellable) Err 

func (c *Cancellable) Err() error

Err returns the context error. If Done is not yet closed, Err returns nil. If Done is closed, Err returns a non-nil error explaining why: Canceled if the context was canceled or DeadlineExceeded if the context's deadline passed. After Err returns a non-nil error, successive calls to Err return the same error.

func (*Cancellable) Get added in v0.1.3 

func (c *Cancellable) Get(key any) any

func (*Cancellable) GetE added in v0.1.3 

func (c *Cancellable) GetE(key any) (any, bool)

func (*Cancellable) GetInt added in v0.1.3 

func (c *Cancellable) GetInt(key any) int

func (*Cancellable) GetString added in v0.1.3 

func (c *Cancellable) GetString(key any) string

func (*Cancellable) Go 

func (c *Cancellable) Go(f func() error)

Go calls the given function in a new goroutine.

The first call to return a non-nil error cancels the group; its error will be returned by Wait.

func (*Cancellable) GoLabelled added in v0.1.7 

func (c *Cancellable) GoLabelled(labelSet pprof.LabelSet, f func() error)

Go calls the given function in a new goroutine.

The first call to return a non-nil error cancels the group; its error will be returned by Wait.

func (*Cancellable) PushCancelCauseFunc added in v0.1.8 

func (c *Cancellable) PushCancelCauseFunc(f context.CancelCauseFunc)

func (*Cancellable) PushCancelFunc added in v0.1.8 

func (c *Cancellable) PushCancelFunc(f context.CancelFunc)

func (*Cancellable) ReplaceContext 

func (c *Cancellable) ReplaceContext(cb func(context.Context) context.Context)

func (*Cancellable) RunIf added in v0.1.5 

func (c *Cancellable) RunIf(key ContextKeyBool, f func())

func (*Cancellable) SetContextKey added in v0.1.5 

func (c *Cancellable) SetContextKey(key ContextKeyBool, value bool)

func (*Cancellable) Value 

func (c *Cancellable) Value(key any) any

Value returns the value 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 (*Cancellable) Wait 

func (c *Cancellable) Wait() error

Wait blocks until all function calls from the Go method have returned, then returns the first non-nil error (if any) from them.

type Context 

type Context interface {
	context.Context

	Cancel()
	CancelWithCause(err error)
	CloneWithNewContext(ctx context.Context, cancel context.CancelCauseFunc) Context
	Go(f func() error)
	GoLabelled(labelSet pprof.LabelSet, f func() error)
	Wait() error
	// Health() health.Health
	ReplaceContext(cb func(context.Context) context.Context)
	AsContext() context.Context
}

func Background added in v0.1.1 

func Background() Context

func New added in v0.1.6 

func New(ctx context.Context, opts ...OptionFunc) Context

func WithCancel 

func WithCancel(ctx 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 WithCancelCause 

func WithCancelCause(ctx Context) (Context, context.CancelCauseFunc)

WithCancelCause behaves like WithCancel but returns a [CancelCauseFunc] instead of a [CancelFunc]. Calling cancel with a non-nil error (the "cause") records that error in ctx; it can then be retrieved using Cause(ctx). Calling cancel with nil sets the cause to Canceled.

Example use: 

ctx, cancel := context.WithCancelCause(parent)
cancel(myError)
ctx.Err() // returns context.Canceled
context.Cause(ctx) // returns myError

func WithDeadline 

func WithDeadline(parent context.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.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 WithDeadlineCause 

func WithDeadlineCause(parent context.Context, d time.Time, cause error) (Context, context.CancelFunc)

WithDeadlineCause behaves like WithDeadline but also sets the cause of the returned Context when the deadline is exceeded. The returned [CancelFunc] does not set the cause.

func WithSignalCancel 

func WithSignalCancel(ctx Context) (Context, context.CancelFunc)

NotifyContext returns a copy of the parent context that is marked done (its Done channel is closed) when one of the listed signals arrives, when the returned stop function is called, or when the parent context's Done channel is closed, whichever happens first.

The stop function unregisters the signal behavior, which, like signal.Reset, may restore the default behavior for a given signal. For example, the default behavior of a Go program receiving os.Interrupt is to exit. Calling NotifyContext(parent, os.Interrupt) will change the behavior to cancel the returned context. Future interrupts received will not trigger the default (exit) behavior until the returned stop function is called.

The stop function releases resources associated with it, so code should call stop as soon as the operations running in this Context complete and signals no longer need to be diverted to the context.

func WithTimeout 

func WithTimeout(parent context.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 WithTimeoutCause 

func WithTimeoutCause(parent context.Context, timeout time.Duration, cause error) (Context, context.CancelFunc)

WithTimeoutCause behaves like WithTimeout but also sets the cause of the returned Context when the timeout expires. The returned [CancelFunc] does not set the cause.

type ContextCancelMod added in v0.1.8 

type ContextCancelMod interface {
	PushCancelCauseFunc(f context.CancelCauseFunc)
	PushCancelFunc(f context.CancelFunc)
}

type ContextConditionalRunner added in v0.1.5 

type ContextConditionalRunner interface {
	SetContextKey(key ContextKeyBool, value bool)
	RunIf(key ContextKeyBool, f func())
}

type ContextKV added in v0.1.3 

type ContextKV struct {
	Key   any
	Value any
}

type ContextKeyBool added in v0.1.5 

type ContextKeyBool string

type ContextValueStore added in v0.1.3 

type ContextValueStore interface {
	AddValue(key any, value any)
	GetE(key any) (any, bool)
	Get(key any) any
	GetString(key any) string
	GetInt(key any) int
}

type CtxErrFunc added in v0.1.2 

type CtxErrFunc func(context.Context) error

type CtxualErrFunc added in v0.1.2 

type CtxualErrFunc func(Context) error

type FuncErr added in v0.1.2 

type FuncErr func() error

type OptionFunc added in v0.1.1 

type OptionFunc func(Context) Context

func WithCustomCancelCauseFunc added in v0.1.8 

func WithCustomCancelCauseFunc(f context.CancelCauseFunc) OptionFunc

func WithCustomCancelFunc added in v0.1.8 

func WithCustomCancelFunc(f context.CancelFunc) OptionFunc

func WithDeadlineOption added in v0.1.1 

func WithDeadlineOption(deadline time.Time) OptionFunc

func WithPProfLabels added in v0.1.5 

func WithPProfLabels(labelSet pprof.LabelSet) OptionFunc

func WithSignalCancelOption added in v0.1.1 

func WithSignalCancelOption(signals ...os.Signal) OptionFunc

func WithTimeoutOption added in v0.1.1 

func WithTimeoutOption(timeout time.Duration) OptionFunc

func WithValues added in v0.1.3 

func WithValues(args []ContextKV) OptionFunc

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.