diff --git a/google/cloud/bigtable/data_connection.h b/google/cloud/bigtable/data_connection.h index 04ba5bf51cf32..1031186b42082 100644 --- a/google/cloud/bigtable/data_connection.h +++ b/google/cloud/bigtable/data_connection.h @@ -45,6 +45,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * To create a concrete instance, see `MakeDataConnection()`. * * For mocking, see `bigtable_mocks::MockDataConnection`. + * + * @par Connection Pool + * This class opens a number of [gRPC Channels] upon its construction. These + * channels each initiate a connection to the Cloud Bigtable service. This is a + * relatively slow operation that can take milliseconds, so applications are + * advised to reuse `DataConnection` objects when possible. + * + * The exact number of channels can be configured with the + * `google::cloud::GrpcNumChannelsOption`. If this option is not set, the class + * creates between 1 and 64 channels. The specific algorithm and number of + * channels is an implementation detail, and subject to change without notice. + * + * Each request sent from the client library cycles through the channels in the + * connection pool in a round robin fashion. + * + * Unused gRPC channels can enter an idle state. Refreshing them during a + * request may incur additional latency. To avoid this, the client library keeps + * connections open by refreshing the channels in a background thread. Advanced + * users can configure the frequency of the refreshes, or disable this feature, + * by using `bigtable::MinConnectionRefreshOption` and + * `bigtable::MaxConnectionRefreshOption`. + * + * [gRPC Channels]: https://grpc.io/docs/what-is-grpc/core-concepts/#channels */ class DataConnection { public: