diff --git a/google/cloud/bigtable/admin_client.h b/google/cloud/bigtable/admin_client.h index 5389bc76ccd17..0d8a080fd0b71 100644 --- a/google/cloud/bigtable/admin_client.h +++ b/google/cloud/bigtable/admin_client.h @@ -40,6 +40,14 @@ class TableAdmin; * endpoints, default timeouts, and other gRPC configuration options. This is an * interface class because it is also used as a dependency injection point in * some of the tests. + * + * @par Cost + * Applications should avoid unnecessarily creating new objects of type + * `AdminClient`. Creating a new object of this type typically requires + * connecting to the Cloud Bigtable servers, and performing the authentication + * workflows with Google Cloud Platform. These operations can take many + * milliseconds, therefore applications should try to reuse the same + * `AdminClient` instances when possible. */ class AdminClient { public: diff --git a/google/cloud/bigtable/data_client.h b/google/cloud/bigtable/data_client.h index 2e167ca4aba20..c9a8c475fa921 100644 --- a/google/cloud/bigtable/data_client.h +++ b/google/cloud/bigtable/data_client.h @@ -40,6 +40,14 @@ class BulkMutator; * time, this configuration includes the credentials, access endpoints, default * timeouts, and other gRPC configuration options. This is an interface class * because it is also used as a dependency injection point in some of the tests. + * + * @par Cost + * Applications should avoid unnecessarily creating new objects of type + * `DataClient`. Creating a new object of this type typically requires + * connecting to the Cloud Bigtable servers, and performing the authentication + * workflows with Google Cloud Platform. These operations can take many + * milliseconds, therefore applications should try to reuse the same + * `DataClient` instances when possible. */ class DataClient { public: diff --git a/google/cloud/bigtable/instance_admin.h b/google/cloud/bigtable/instance_admin.h index 41e4882f78cd0..410757d294020 100644 --- a/google/cloud/bigtable/instance_admin.h +++ b/google/cloud/bigtable/instance_admin.h @@ -29,6 +29,12 @@ namespace bigtable { inline namespace BIGTABLE_CLIENT_NS { /** * Implements the APIs to administer Cloud Bigtable instances. + * + * @par Cost + * Creating a new object of type `InstanceAdmin` is comparable to creating a few + * objects of type `std::string` or a few objects of type + * `std::shared_ptr`. The class represents a shallow handle to a remote + * object. */ class InstanceAdmin { public: @@ -84,6 +90,9 @@ class InstanceAdmin { * for this operation. * * @param instance_config a description of the new instance to be created. + * instance_id and a display_name parameters must be set in instance_config, + * - instance_id : must be between 6 and 33 characters. + * - display_name : must be between 4 and 30 characters. * @return a future that becomes satisfied when (a) the operation has * completed successfully, in which case it returns a proto with the * Instance details, (b) the operation has failed, in which case the future @@ -104,7 +113,7 @@ class InstanceAdmin { * @param cluster_config a description of the new cluster to be created. * @param instance_id the id of the instance in the project * @param cluster_id the id of the cluster in the project that needs to be - * created + * created. It must be between 6 and 30 characters. * * @par Example * @snippet bigtable_samples_instance_admin.cc create cluster diff --git a/google/cloud/bigtable/instance_admin_client.h b/google/cloud/bigtable/instance_admin_client.h index 9fdc06095168d..987b51243fa2e 100644 --- a/google/cloud/bigtable/instance_admin_client.h +++ b/google/cloud/bigtable/instance_admin_client.h @@ -40,6 +40,14 @@ class InstanceAdmin; * access endpoints, default timeouts, and other gRPC configuration options. * This is an interface class because it is also used as a dependency injection * point in some of the tests. + * + * @par Cost + * Applications should avoid unnecessarily creating new objects of type + * `InstanceAdminClient`. Creating a new object of this type typically requires + * connecting to the Cloud Bigtable servers, and performing the authentication + * workflows with Google Cloud Platform. These operations can take many + * milliseconds, therefore applications should try to reuse the same + * `InstanceAdminClient` instances when possible. */ class InstanceAdminClient { public: diff --git a/google/cloud/bigtable/table.h b/google/cloud/bigtable/table.h index cf5c5fda50875..c2b3e856a8db0 100644 --- a/google/cloud/bigtable/table.h +++ b/google/cloud/bigtable/table.h @@ -35,6 +35,11 @@ inline namespace BIGTABLE_CLIENT_NS { * The class deals with the most common transient failures, and retries the * underlying RPC calls subject to the policies configured by the application. * These policies are documented in`Table::Table()`. + * + * @par Cost + * Creating a new object of type `Table` is comparable to creating a few objects + * of type `std::string` or a few objects of type `std::shared_ptr`. The + * class represents a shallow handle to a remote object. */ class Table { public: diff --git a/google/cloud/bigtable/table_admin.h b/google/cloud/bigtable/table_admin.h index 4cc4bcc8ff312..24a8460e9891d 100644 --- a/google/cloud/bigtable/table_admin.h +++ b/google/cloud/bigtable/table_admin.h @@ -39,6 +39,12 @@ class TableAdmin { * @param instance_id the id of the instance, e.g., "my-instance", the full * name (e.g. '/projects/my-project/instances/my-instance') is built using * the project id in the @p client parameter. + * + * @par Cost + * Creating a new object of type `TableAdmin` is comparable to creating a few + * objects of type `std::string` or a few objects of type + * `std::shared_ptr`. The class represents a shallow handle to a remote + * object. */ TableAdmin(std::shared_ptr client, std::string instance_id) : impl_(std::move(client), std::move(instance_id)) {}