example_test.go

     1  // Copyright 2016 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  package context_test
     6  
     7  import (
     8  	"context"
     9  	"errors"
    10  	"fmt"
    11  	"net"
    12  	"sync"
    13  	"time"
    14  )
    15  
    16  var neverReady = make(chan struct{}) // never closed
    17  
    18  // This example demonstrates the use of a cancelable context to prevent a
    19  // goroutine leak. By the end of the example function, the goroutine started
    20  // by gen will return without leaking.
    21  func ExampleWithCancel() {
    22  	// gen generates integers in a separate goroutine and
    23  	// sends them to the returned channel.
    24  	// The callers of gen need to cancel the context once
    25  	// they are done consuming generated integers not to leak
    26  	// the internal goroutine started by gen.
    27  	gen := func(ctx context.Context) <-chan int {
    28  		dst := make(chan int)
    29  		n := 1
    30  		go func() {
    31  			for {
    32  				select {
    33  				case <-ctx.Done():
    34  					return // returning not to leak the goroutine
    35  				case dst <- n:
    36  					n++
    37  				}
    38  			}
    39  		}()
    40  		return dst
    41  	}
    42  
    43  	ctx, cancel := context.WithCancel(context.Background())
    44  	defer cancel() // cancel when we are finished consuming integers
    45  
    46  	for n := range gen(ctx) {
    47  		fmt.Println(n)
    48  		if n == 5 {
    49  			break
    50  		}
    51  	}
    52  	// Output:
    53  	// 1
    54  	// 2
    55  	// 3
    56  	// 4
    57  	// 5
    58  }
    59  
    60  // This example passes a context with an arbitrary deadline to tell a blocking
    61  // function that it should abandon its work as soon as it gets to it.
    62  func ExampleWithDeadline() {
    63  	d := time.Now().Add(shortDuration)
    64  	ctx, cancel := context.WithDeadline(context.Background(), d)
    65  
    66  	// Even though ctx will be expired, it is good practice to call its
    67  	// cancellation function in any case. Failure to do so may keep the
    68  	// context and its parent alive longer than necessary.
    69  	defer cancel()
    70  
    71  	select {
    72  	case <-neverReady:
    73  		fmt.Println("ready")
    74  	case <-ctx.Done():
    75  		fmt.Println(ctx.Err())
    76  	}
    77  
    78  	// Output:
    79  	// context deadline exceeded
    80  }
    81  
    82  // This example passes a context with a timeout to tell a blocking function that
    83  // it should abandon its work after the timeout elapses.
    84  func ExampleWithTimeout() {
    85  	// Pass a context with a timeout to tell a blocking function that it
    86  	// should abandon its work after the timeout elapses.
    87  	ctx, cancel := context.WithTimeout(context.Background(), shortDuration)
    88  	defer cancel()
    89  
    90  	select {
    91  	case <-neverReady:
    92  		fmt.Println("ready")
    93  	case <-ctx.Done():
    94  		fmt.Println(ctx.Err()) // prints "context deadline exceeded"
    95  	}
    96  
    97  	// Output:
    98  	// context deadline exceeded
    99  }
   100  
   101  // This example demonstrates how a value can be passed to the context
   102  // and also how to retrieve it if it exists.
   103  func ExampleWithValue() {
   104  	type favContextKey string
   105  
   106  	f := func(ctx context.Context, k favContextKey) {
   107  		if v := ctx.Value(k); v != nil {
   108  			fmt.Println("found value:", v)
   109  			return
   110  		}
   111  		fmt.Println("key not found:", k)
   112  	}
   113  
   114  	k := favContextKey("language")
   115  	ctx := context.WithValue(context.Background(), k, "Go")
   116  
   117  	f(ctx, k)
   118  	f(ctx, favContextKey("color"))
   119  
   120  	// Output:
   121  	// found value: Go
   122  	// key not found: color
   123  }
   124  
   125  // This example uses AfterFunc to define a function which waits on a sync.Cond,
   126  // stopping the wait when a context is canceled.
   127  func ExampleAfterFunc_cond() {
   128  	waitOnCond := func(ctx context.Context, cond *sync.Cond, conditionMet func() bool) error {
   129  		stopf := context.AfterFunc(ctx, func() {
   130  			// We need to acquire cond.L here to be sure that the Broadcast
   131  			// below won't occur before the call to Wait, which would result
   132  			// in a missed signal (and deadlock).
   133  			cond.L.Lock()
   134  			defer cond.L.Unlock()
   135  
   136  			// If multiple goroutines are waiting on cond simultaneously,
   137  			// we need to make sure we wake up exactly this one.
   138  			// That means that we need to Broadcast to all of the goroutines,
   139  			// which will wake them all up.
   140  			//
   141  			// If there are N concurrent calls to waitOnCond, each of the goroutines
   142  			// will spuriously wake up O(N) other goroutines that aren't ready yet,
   143  			// so this will cause the overall CPU cost to be O(N²).
   144  			cond.Broadcast()
   145  		})
   146  		defer stopf()
   147  
   148  		// Since the wakeups are using Broadcast instead of Signal, this call to
   149  		// Wait may unblock due to some other goroutine's context being canceled,
   150  		// so to be sure that ctx is actually canceled we need to check it in a loop.
   151  		for !conditionMet() {
   152  			cond.Wait()
   153  			if ctx.Err() != nil {
   154  				return ctx.Err()
   155  			}
   156  		}
   157  
   158  		return nil
   159  	}
   160  
   161  	cond := sync.NewCond(new(sync.Mutex))
   162  
   163  	var wg sync.WaitGroup
   164  	for range 4 {
   165  		wg.Go(func() {
   166  			ctx, cancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
   167  			defer cancel()
   168  
   169  			cond.L.Lock()
   170  			defer cond.L.Unlock()
   171  
   172  			err := waitOnCond(ctx, cond, func() bool { return false })
   173  			fmt.Println(err)
   174  		})
   175  	}
   176  	wg.Wait()
   177  
   178  	// Output:
   179  	// context deadline exceeded
   180  	// context deadline exceeded
   181  	// context deadline exceeded
   182  	// context deadline exceeded
   183  }
   184  
   185  // This example uses AfterFunc to define a function which reads from a net.Conn,
   186  // stopping the read when a context is canceled.
   187  func ExampleAfterFunc_connection() {
   188  	readFromConn := func(ctx context.Context, conn net.Conn, b []byte) (n int, err error) {
   189  		stopc := make(chan struct{})
   190  		stop := context.AfterFunc(ctx, func() {
   191  			conn.SetReadDeadline(time.Now())
   192  			close(stopc)
   193  		})
   194  		n, err = conn.Read(b)
   195  		if !stop() {
   196  			// The AfterFunc was started.
   197  			// Wait for it to complete, and reset the Conn's deadline.
   198  			<-stopc
   199  			conn.SetReadDeadline(time.Time{})
   200  			return n, ctx.Err()
   201  		}
   202  		return n, err
   203  	}
   204  
   205  	listener, err := net.Listen("tcp", "localhost:0")
   206  	if err != nil {
   207  		fmt.Println(err)
   208  		return
   209  	}
   210  	defer listener.Close()
   211  
   212  	conn, err := net.Dial(listener.Addr().Network(), listener.Addr().String())
   213  	if err != nil {
   214  		fmt.Println(err)
   215  		return
   216  	}
   217  	defer conn.Close()
   218  
   219  	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
   220  	defer cancel()
   221  
   222  	b := make([]byte, 1024)
   223  	_, err = readFromConn(ctx, conn, b)
   224  	fmt.Println(err)
   225  
   226  	// Output:
   227  	// context deadline exceeded
   228  }
   229  
   230  // This example uses AfterFunc to define a function which combines
   231  // the cancellation signals of two Contexts.
   232  func ExampleAfterFunc_merge() {
   233  	// mergeCancel returns a context that contains the values of ctx,
   234  	// and which is canceled when either ctx or cancelCtx is canceled.
   235  	mergeCancel := func(ctx, cancelCtx context.Context) (context.Context, context.CancelFunc) {
   236  		ctx, cancel := context.WithCancelCause(ctx)
   237  		stop := context.AfterFunc(cancelCtx, func() {
   238  			cancel(context.Cause(cancelCtx))
   239  		})
   240  		return ctx, func() {
   241  			stop()
   242  			cancel(context.Canceled)
   243  		}
   244  	}
   245  
   246  	ctx1, cancel1 := context.WithCancelCause(context.Background())
   247  	defer cancel1(errors.New("ctx1 canceled"))
   248  
   249  	ctx2, cancel2 := context.WithCancelCause(context.Background())
   250  
   251  	mergedCtx, mergedCancel := mergeCancel(ctx1, ctx2)
   252  	defer mergedCancel()
   253  
   254  	cancel2(errors.New("ctx2 canceled"))
   255  	<-mergedCtx.Done()
   256  	fmt.Println(context.Cause(mergedCtx))
   257  
   258  	// Output:
   259  	// ctx2 canceled
   260  }
   261
View as plain text