From b30a7f4a520c358eb71e1378b98e7413c2ea7f81 Mon Sep 17 00:00:00 2001 From: shollyman Date: Fri, 4 Aug 2023 14:22:14 -0700 Subject: [PATCH] docs(bigquery/storage/managedwriter): augment context usage in package docs (#8334) This PR augments existing information about how this package uses context. Out of band feedback from users related to PR 8275 indicates more documentation is warranted about the use and retention of context throughout the package. --- bigquery/storage/managedwriter/client.go | 3 +++ bigquery/storage/managedwriter/doc.go | 13 +++++++++++++ 2 files changed, 16 insertions(+) diff --git a/bigquery/storage/managedwriter/client.go b/bigquery/storage/managedwriter/client.go index 67aefdf80cf4..d75e711a0ef8 100644 --- a/bigquery/storage/managedwriter/client.go +++ b/bigquery/storage/managedwriter/client.go @@ -60,6 +60,9 @@ type Client struct { } // NewClient instantiates a new client. +// +// The context provided here is retained and used for background connection management +// between the client and the BigQuery Storage service. func NewClient(ctx context.Context, projectID string, opts ...option.ClientOption) (c *Client, err error) { // Set a reasonable default for the gRPC connection pool size. numConns := runtime.GOMAXPROCS(0) diff --git a/bigquery/storage/managedwriter/doc.go b/bigquery/storage/managedwriter/doc.go index 67174bf8d07c..e98eaabda38b 100644 --- a/bigquery/storage/managedwriter/doc.go +++ b/bigquery/storage/managedwriter/doc.go @@ -209,6 +209,19 @@ In support of the retry changes, the AppendResult returned as part of an append TotalAttempts(), which returns the number of times that specific append was enqueued to the service. Values larger than 1 are indicative of a specific append being enqueued multiple times. +# Usage of Contexts + +The underlying rpc mechanism used to transmit requests and responses between this client and +the service uses a gRPC bidirectional streaming protocol, and the context provided when invoking +NewClient to instantiate the client is used to maintain those background connections. + +This package also exposes context when instantiating a new writer (NewManagedStream), as well as +allowing a per-request context when invoking the AppendRows function to send a set of rows. If the +context becomes invalid on the writer all subsequent AppendRows requests will be blocked. + +Finally, there is a per-request context supplied as part of the AppendRows call on the ManagedStream +writer itself, useful for bounding individual requests. + # Connection Sharing (Multiplexing) Note: This feature is EXPERIMENTAL and subject to change.