From 2d59af0cb37fb29e5b7980a15088938778f117c7 Mon Sep 17 00:00:00 2001
From: Jonathan Amsterdam <jba@google.com>
Date: Wed, 11 Apr 2018 13:42:18 -0400
Subject: [PATCH] cloud: document context timeout and cancellation

Fixes #946.

Change-Id: Iadd6c57f2b393c6693219538e2aab9e20e1f78dd
Reviewed-on: https://code-review.googlesource.com/26310
Reviewed-by: Chris Broadfoot <cbro@google.com>
---
 cloud.go         | 20 ++++++++++++++--
 examples_test.go | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+), 2 deletions(-)
 create mode 100644 examples_test.go

diff --git a/cloud.go b/cloud.go
index 0be0df33f987..537184e899e0 100644
--- a/cloud.go
+++ b/cloud.go
@@ -17,8 +17,24 @@ Package cloud is the root of the packages used to access Google Cloud
 Services. See https://godoc.org/cloud.google.com/go for a full list
 of sub-packages.
 
-Examples in this package show ways to authorize and authenticate the
-sub packages.
+
+Authentication and Authorization
+
+All the clients in sub-packages support authentication via Google Application Default Credentials,
+or by providing credentials in JSON form. See the authentication examples in this package for details.
+
+
+Timeouts and Cancellation
+
+By default, all RPCs made by the clients in sub-packages will run indefinitely, retrying on
+temporary errors when correctness allows. To set timeouts or arrange for cancellation, use contexts.
+See the examples for details.
+
+Do not attempt to control the initial connection (dialing) of a service by setting a
+timeout on the context passed to NewClient. Dialing is non-blocking, so timeouts
+would be ineffective and would only interfere with credential refreshing, which uses
+the same context.
+
 
 Connection Pooling
 
diff --git a/examples_test.go b/examples_test.go
new file mode 100644
index 000000000000..8d1dea36d7e3
--- /dev/null
+++ b/examples_test.go
@@ -0,0 +1,60 @@
+// Copyright 2018 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloud_test
+
+import (
+	"time"
+
+	"cloud.google.com/go/bigquery"
+	"golang.org/x/net/context"
+)
+
+// To set a timeout for an RPC, use context.WithTimeout.
+func Example_timeout() {
+	ctx := context.Background()
+	// Do not set a timeout on the context passed to NewClient: dialing happens
+	// asynchronously, and the context is used to refresh credentials in the
+	// background.
+	client, err := bigquery.NewClient(ctx, "project-id")
+	if err != nil {
+		// TODO: handle error.
+	}
+	// Time out if it takes more than 10 seconds to create a dataset.
+	tctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel() // Always call cancel.
+
+	if err := client.Dataset("new-dataset").Create(tctx, nil); err != nil {
+		// TODO: handle error.
+	}
+}
+
+// To arrange for an RPC to be canceled, use context.WithCancel.
+func Example_cancellation() {
+	ctx := context.Background()
+	// Do not cancel the context passed to NewClient: dialing happens asynchronously,
+	// and the context is used to refresh credentials in the background.
+	client, err := bigquery.NewClient(ctx, "project-id")
+	if err != nil {
+		// TODO: handle error.
+	}
+	cctx, cancel := context.WithCancel(ctx)
+	defer cancel() // Always call cancel.
+
+	// TODO: Make the cancel function available to whatever might want to cancel the
+	// call--perhaps a GUI button.
+	if err := client.Dataset("new-dataset").Create(cctx, nil); err != nil {
+		// TODO: handle error.
+	}
+}