context: add examples

Add function level examples to the package.

Partially addresses #16360

Change-Id: I7162aed4e4a969743c19b79c9ffaf9217d2c1c08
Reviewed-on: https://go-review.googlesource.com/26930
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/context/example_test.go b/src/context/example_test.go
new file mode 100644 (file)
index 0000000..4b99da6
--- /dev/null
+++ b/src/context/example_test.go
@@ -0,0 +1,109 @@
+// Copyright 2016 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package context_test
+
+import (
+       "context"
+       "fmt"
+       "time"
+)
+
+// This example demonstrate the use of a cancelable context preventing a
+// goroutine leak. By the end of the example func's execution, the "count"
+// goroutine is canceled.
+func ExampleWithCancel() {
+       count := func(ctx context.Context, dst chan<- int) {
+               n := 1
+               for {
+                       select {
+                       case dst <- n:
+                               n++
+                       case <-ctx.Done():
+                               return
+                       }
+               }
+       }
+
+       ctx, cancel := context.WithCancel(context.Background())
+       defer cancel()
+
+       ints := make(chan int)
+       go count(ctx, ints)
+       for n := range ints {
+               fmt.Println(n)
+               if n == 5 {
+                       return
+               }
+       }
+       // Output:
+       // 1
+       // 2
+       // 3
+       // 4
+       // 5
+}
+
+// This example passes a context with a arbitrary deadline to tell a blocking
+// function that it should abandon its work as soon as it gets to it.
+func ExampleWithDeadline() {
+       d := time.Now().Add(50 * time.Millisecond)
+       ctx, cancel := context.WithDeadline(context.Background(), d)
+
+       // Even though ctx will be expired, it is good practice to call its
+       // cancelation function in any case. Failure to do so may keep the
+       // context and its parent alive longer than necessary.
+       defer cancel()
+
+       select {
+       case <-time.After(1 * time.Second):
+               fmt.Println("overslept")
+       case <-ctx.Done():
+               fmt.Println(ctx.Err())
+       }
+
+       // Output:
+       // context deadline exceeded
+}
+
+// This example passes a context with a timeout to tell a blocking function that
+// it should abandon its work after the timeout elapses.
+func ExampleWithTimeout() {
+       // Pass a context with a timeout to tell a blocking function that it
+       // should abandon its work after the timeout elapses.
+       ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+       defer cancel()
+
+       select {
+       case <-time.After(1 * time.Second):
+               fmt.Println("overslept")
+       case <-ctx.Done():
+               fmt.Println(ctx.Err()) // prints "context deadline exceeded"
+       }
+
+       // Output:
+       // context deadline exceeded
+}
+
+func ExampleWithValue() {
+       type favContextKey string
+
+       f := func(ctx context.Context, k favContextKey) {
+               if v := ctx.Value(k); v != nil {
+                       fmt.Println("found value:", v)
+                       return
+               }
+               fmt.Println("key not found:", k)
+       }
+
+       k := favContextKey("language")
+       ctx := context.WithValue(context.Background(), k, "Go")
+
+       f(ctx, k)
+       f(ctx, favContextKey("color"))
+
+       // Output:
+       // found value: Go
+       // key not found: color
+}

diff --git a/src/context/withtimeout_test.go b/src/context/withtimeout_test.go
deleted file mode 100644 (file)
index a3e8979..0000000
--- a/src/context/withtimeout_test.go
+++ /dev/null
@@ -1,33 +0,0 @@
-// Copyright 2014 The Go Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-package context_test
-
-import (
-       "context"
-       "fmt"
-       "time"
-)
-
-func ExampleWithTimeout() {
-       // Pass a context with a timeout to tell a blocking function that it
-       // should abandon its work after the timeout elapses.
-       ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
-
-       select {
-       case <-time.After(1 * time.Second):
-               fmt.Println("overslept")
-       case <-ctx.Done():
-               fmt.Println(ctx.Err()) // prints "context deadline exceeded"
-       }
-
-       // Even though ctx should have expired already, it is good
-       // practice to call its cancelation function in any case.
-       // Failure to do so may keep the context and its parent alive
-       // longer than necessary.
-       cancel()
-
-       // Output:
-       // context deadline exceeded
-}