From 4afdc6bf8e0df209e6426b6dce0a576451a7a2d3 Mon Sep 17 00:00:00 2001 From: Seth Hollyman Date: Thu, 27 Jul 2023 15:49:38 +0000 Subject: [PATCH 1/2] docs(bigquery/storage/managedwriter): augment context usage in package docs 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/doc.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) 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. From f584ce4e908cd04dac9a6eeae12d9c5a11928f42 Mon Sep 17 00:00:00 2001 From: Seth Hollyman Date: Thu, 27 Jul 2023 15:54:08 +0000 Subject: [PATCH 2/2] add mention to NewClient --- bigquery/storage/managedwriter/client.go | 3 +++ 1 file changed, 3 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)