pre_go17.go

Documentation: golang.org/x/net/context

     1  // Copyright 2014 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:build !go1.7
     6  
     7  package context
     8  
     9  import (
    10  	"errors"
    11  	"fmt"
    12  	"sync"
    13  	"time"
    14  )
    15  
    16  // An emptyCtx is never canceled, has no values, and has no deadline. It is not
    17  // struct{}, since vars of this type must have distinct addresses.
    18  type emptyCtx int
    19  
    20  func (*emptyCtx) Deadline() (deadline time.Time, ok bool) {
    21  	return
    22  }
    23  
    24  func (*emptyCtx) Done() <-chan struct{} {
    25  	return nil
    26  }
    27  
    28  func (*emptyCtx) Err() error {
    29  	return nil
    30  }
    31  
    32  func (*emptyCtx) Value(key interface{}) interface{} {
    33  	return nil
    34  }
    35  
    36  func (e *emptyCtx) String() string {
    37  	switch e {
    38  	case background:
    39  		return "context.Background"
    40  	case todo:
    41  		return "context.TODO"
    42  	}
    43  	return "unknown empty Context"
    44  }
    45  
    46  var (
    47  	background = new(emptyCtx)
    48  	todo       = new(emptyCtx)
    49  )
    50  
    51  // Canceled is the error returned by Context.Err when the context is canceled.
    52  var Canceled = errors.New("context canceled")
    53  
    54  // DeadlineExceeded is the error returned by Context.Err when the context's
    55  // deadline passes.
    56  var DeadlineExceeded = errors.New("context deadline exceeded")
    57  
    58  // WithCancel returns a copy of parent with a new Done channel. The returned
    59  // context's Done channel is closed when the returned cancel function is called
    60  // or when the parent context's Done channel is closed, whichever happens first.
    61  //
    62  // Canceling this context releases resources associated with it, so code should
    63  // call cancel as soon as the operations running in this Context complete.
    64  func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
    65  	c := newCancelCtx(parent)
    66  	propagateCancel(parent, c)
    67  	return c, func() { c.cancel(true, Canceled) }
    68  }
    69  
    70  // newCancelCtx returns an initialized cancelCtx.
    71  func newCancelCtx(parent Context) *cancelCtx {
    72  	return &cancelCtx{
    73  		Context: parent,
    74  		done:    make(chan struct{}),
    75  	}
    76  }
    77  
    78  // propagateCancel arranges for child to be canceled when parent is.
    79  func propagateCancel(parent Context, child canceler) {
    80  	if parent.Done() == nil {
    81  		return // parent is never canceled
    82  	}
    83  	if p, ok := parentCancelCtx(parent); ok {
    84  		p.mu.Lock()
    85  		if p.err != nil {
    86  			// parent has already been canceled
    87  			child.cancel(false, p.err)
    88  		} else {
    89  			if p.children == nil {
    90  				p.children = make(map[canceler]bool)
    91  			}
    92  			p.children[child] = true
    93  		}
    94  		p.mu.Unlock()
    95  	} else {
    96  		go func() {
    97  			select {
    98  			case <-parent.Done():
    99  				child.cancel(false, parent.Err())
   100  			case <-child.Done():
   101  			}
   102  		}()
   103  	}
   104  }
   105  
   106  // parentCancelCtx follows a chain of parent references until it finds a
   107  // *cancelCtx. This function understands how each of the concrete types in this
   108  // package represents its parent.
   109  func parentCancelCtx(parent Context) (*cancelCtx, bool) {
   110  	for {
   111  		switch c := parent.(type) {
   112  		case *cancelCtx:
   113  			return c, true
   114  		case *timerCtx:
   115  			return c.cancelCtx, true
   116  		case *valueCtx:
   117  			parent = c.Context
   118  		default:
   119  			return nil, false
   120  		}
   121  	}
   122  }
   123  
   124  // removeChild removes a context from its parent.
   125  func removeChild(parent Context, child canceler) {
   126  	p, ok := parentCancelCtx(parent)
   127  	if !ok {
   128  		return
   129  	}
   130  	p.mu.Lock()
   131  	if p.children != nil {
   132  		delete(p.children, child)
   133  	}
   134  	p.mu.Unlock()
   135  }
   136  
   137  // A canceler is a context type that can be canceled directly. The
   138  // implementations are *cancelCtx and *timerCtx.
   139  type canceler interface {
   140  	cancel(removeFromParent bool, err error)
   141  	Done() <-chan struct{}
   142  }
   143  
   144  // A cancelCtx can be canceled. When canceled, it also cancels any children
   145  // that implement canceler.
   146  type cancelCtx struct {
   147  	Context
   148  
   149  	done chan struct{} // closed by the first cancel call.
   150  
   151  	mu       sync.Mutex
   152  	children map[canceler]bool // set to nil by the first cancel call
   153  	err      error             // set to non-nil by the first cancel call
   154  }
   155  
   156  func (c *cancelCtx) Done() <-chan struct{} {
   157  	return c.done
   158  }
   159  
   160  func (c *cancelCtx) Err() error {
   161  	c.mu.Lock()
   162  	defer c.mu.Unlock()
   163  	return c.err
   164  }
   165  
   166  func (c *cancelCtx) String() string {
   167  	return fmt.Sprintf("%v.WithCancel", c.Context)
   168  }
   169  
   170  // cancel closes c.done, cancels each of c's children, and, if
   171  // removeFromParent is true, removes c from its parent's children.
   172  func (c *cancelCtx) cancel(removeFromParent bool, err error) {
   173  	if err == nil {
   174  		panic("context: internal error: missing cancel error")
   175  	}
   176  	c.mu.Lock()
   177  	if c.err != nil {
   178  		c.mu.Unlock()
   179  		return // already canceled
   180  	}
   181  	c.err = err
   182  	close(c.done)
   183  	for child := range c.children {
   184  		// NOTE: acquiring the child's lock while holding parent's lock.
   185  		child.cancel(false, err)
   186  	}
   187  	c.children = nil
   188  	c.mu.Unlock()
   189  
   190  	if removeFromParent {
   191  		removeChild(c.Context, c)
   192  	}
   193  }
   194  
   195  // WithDeadline returns a copy of the parent context with the deadline adjusted
   196  // to be no later than d. If the parent's deadline is already earlier than d,
   197  // WithDeadline(parent, d) is semantically equivalent to parent. The returned
   198  // context's Done channel is closed when the deadline expires, when the returned
   199  // cancel function is called, or when the parent context's Done channel is
   200  // closed, whichever happens first.
   201  //
   202  // Canceling this context releases resources associated with it, so code should
   203  // call cancel as soon as the operations running in this Context complete.
   204  func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc) {
   205  	if cur, ok := parent.Deadline(); ok && cur.Before(deadline) {
   206  		// The current deadline is already sooner than the new one.
   207  		return WithCancel(parent)
   208  	}
   209  	c := &timerCtx{
   210  		cancelCtx: newCancelCtx(parent),
   211  		deadline:  deadline,
   212  	}
   213  	propagateCancel(parent, c)
   214  	d := deadline.Sub(time.Now())
   215  	if d <= 0 {
   216  		c.cancel(true, DeadlineExceeded) // deadline has already passed
   217  		return c, func() { c.cancel(true, Canceled) }
   218  	}
   219  	c.mu.Lock()
   220  	defer c.mu.Unlock()
   221  	if c.err == nil {
   222  		c.timer = time.AfterFunc(d, func() {
   223  			c.cancel(true, DeadlineExceeded)
   224  		})
   225  	}
   226  	return c, func() { c.cancel(true, Canceled) }
   227  }
   228  
   229  // A timerCtx carries a timer and a deadline. It embeds a cancelCtx to
   230  // implement Done and Err. It implements cancel by stopping its timer then
   231  // delegating to cancelCtx.cancel.
   232  type timerCtx struct {
   233  	*cancelCtx
   234  	timer *time.Timer // Under cancelCtx.mu.
   235  
   236  	deadline time.Time
   237  }
   238  
   239  func (c *timerCtx) Deadline() (deadline time.Time, ok bool) {
   240  	return c.deadline, true
   241  }
   242  
   243  func (c *timerCtx) String() string {
   244  	return fmt.Sprintf("%v.WithDeadline(%s [%s])", c.cancelCtx.Context, c.deadline, c.deadline.Sub(time.Now()))
   245  }
   246  
   247  func (c *timerCtx) cancel(removeFromParent bool, err error) {
   248  	c.cancelCtx.cancel(false, err)
   249  	if removeFromParent {
   250  		// Remove this timerCtx from its parent cancelCtx's children.
   251  		removeChild(c.cancelCtx.Context, c)
   252  	}
   253  	c.mu.Lock()
   254  	if c.timer != nil {
   255  		c.timer.Stop()
   256  		c.timer = nil
   257  	}
   258  	c.mu.Unlock()
   259  }
   260  
   261  // WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).
   262  //
   263  // Canceling this context releases resources associated with it, so code should
   264  // call cancel as soon as the operations running in this Context complete:
   265  //
   266  //	func slowOperationWithTimeout(ctx context.Context) (Result, error) {
   267  //		ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
   268  //		defer cancel()  // releases resources if slowOperation completes before timeout elapses
   269  //		return slowOperation(ctx)
   270  //	}
   271  func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
   272  	return WithDeadline(parent, time.Now().Add(timeout))
   273  }
   274  
   275  // WithValue returns a copy of parent in which the value associated with key is
   276  // val.
   277  //
   278  // Use context Values only for request-scoped data that transits processes and
   279  // APIs, not for passing optional parameters to functions.
   280  func WithValue(parent Context, key interface{}, val interface{}) Context {
   281  	return &valueCtx{parent, key, val}
   282  }
   283  
   284  // A valueCtx carries a key-value pair. It implements Value for that key and
   285  // delegates all other calls to the embedded Context.
   286  type valueCtx struct {
   287  	Context
   288  	key, val interface{}
   289  }
   290  
   291  func (c *valueCtx) String() string {
   292  	return fmt.Sprintf("%v.WithValue(%#v, %#v)", c.Context, c.key, c.val)
   293  }
   294  
   295  func (c *valueCtx) Value(key interface{}) interface{} {
   296  	if c.key == key {
   297  		return c.val
   298  	}
   299  	return c.Context.Value(key)
   300  }
   301
View as plain text