Namespace: go.std.context

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the context package.

Package context defines the Context type, which carries deadlines,
cancellation signals, and other request-scoped values across API boundaries
and between processes.

Incoming requests to a server should create a Context, and outgoing
calls to servers should accept a Context. The chain of function
calls between them must propagate the Context, optionally replacing
it with a derived Context created using WithCancel, WithDeadline,
WithTimeout, or WithValue. When a Context is canceled, all
Contexts derived from it are also canceled.

The WithCancel, WithDeadline, and WithTimeout functions take a
Context (the parent) and return a derived Context (the child) and a
CancelFunc. Calling the CancelFunc cancels the child and its
children, removes the parent's reference to the child, and stops
any associated timers. Failing to call the CancelFunc leaks the
child and its children until the parent is canceled or the timer
fires. The go vet tool checks that CancelFuncs are used on all
control-flow paths.

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

Do not store Contexts inside a struct type; instead, pass a Context
explicitly to each function that needs it. The Context should be the first
parameter, typically named ctx:

func DoSomething(ctx context.Context, arg Arg) error {
// ... use ctx ...
}

Do not pass a nil Context, even if a function permits it. Pass context.TODO
if you are unsure about which Context to use.

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

The same Context may be passed to functions running in different goroutines;
Contexts are safe for simultaneous use by multiple goroutines.

See https://blog.golang.org/context for example code for a server that uses
Contexts.

Index

• *CancelFunc
• Background
• CancelFunc
• Canceled
• Context
• DeadlineExceeded
• TODO
• WithCancel
• WithDeadline
• WithTimeout
• WithValue
• arrayOfCancelFunc
• arrayOfContext

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

• Canceled

  Var v1.0

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

• DeadlineExceeded

  Var v1.0

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

Functions, Macros, and Special Forms

• Background

  Function v1.0

  (Background)
  

  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.
  
  Go returns: Context
  
  Joker input arguments: []
  
  Joker returns: ^Context

• TODO

  Function v1.0

  (TODO)
  

  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).
  
  Go returns: Context
  
  Joker input arguments: []
  
  Joker returns: ^Context

• WithCancel

  Function v1.0

  (WithCancel parent)
  

  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.
  
  Go input arguments: (parent Context)
  
  Go returns: (ctx Context, cancel CancelFunc)
  
  Joker input arguments: [^Context parent]
  
  Joker returns: [^Context ctx, ^CancelFunc cancel]

• WithDeadline

  Function v1.0

  (WithDeadline parent d)
  

  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.
  
  Go input arguments: (parent Context, d time.Time)
  
  Go returns: (Context, CancelFunc)
  
  Joker input arguments: [^Context parent, ^go.std.time/Time d]
  
  Joker returns: [^Context, ^CancelFunc]

• WithTimeout

  Function v1.0

  (WithTimeout parent timeout)
  

  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)
  }
  
  Go input arguments: (parent Context, timeout time.Duration)
  
  Go returns: (Context, CancelFunc)
  
  Joker input arguments: [^Context parent, ^go.std.time/Duration timeout]
  
  Joker returns: [^Context, ^CancelFunc]

• WithValue

  Function v1.0

  (WithValue parent key val)
  

  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.
  
  Go input arguments: (parent Context, key any, val any)
  
  Go returns: Context
  
  Joker input arguments: [^Context parent, ^GoObject key, ^GoObject val]
  
  Joker returns: ^Context

Types

• *CancelFunc

  Concrete Type v1.0

  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.
  

• CancelFunc

  Concrete Type v1.0

  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.
  

• Context

  Abstract Type v1.0

  A Context carries a deadline, a cancellation signal, and other values across
  API boundaries.
  
  Context's methods may be called by multiple goroutines simultaneously.
  

• Deadline

  Method for Context v1.0

  ([])
  

• Done

  Method for Context v1.0

  ([])
  

• Err

  Method for Context v1.0

  ([])
  

• Value

  Method for Context v1.0

  ([key])
  

• arrayOfCancelFunc

  Concrete Type v1.0

  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.
  

• arrayOfContext

  Concrete Type v1.0

  A Context carries a deadline, a cancellation signal, and other values across
  API boundaries.
  
  Context's methods may be called by multiple goroutines simultaneously.