From 68596461837fd6676bd582a4d0ca97373228e791 Mon Sep 17 00:00:00 2001 From: manish Date: Wed, 26 Sep 2018 08:16:02 +0530 Subject: [PATCH 1/2] Documenting instance id, name and cluster id length limits and cost of creating admin and clients objects --- google/cloud/bigtable/admin_client.h | 8 ++++++++ google/cloud/bigtable/data_client.h | 8 ++++++++ google/cloud/bigtable/instance_admin.h | 10 +++++++++- google/cloud/bigtable/instance_admin_client.h | 8 ++++++++ google/cloud/bigtable/table.h | 5 +++++ google/cloud/bigtable/table_admin.h | 5 +++++ 6 files changed, 43 insertions(+), 1 deletion(-) diff --git a/google/cloud/bigtable/admin_client.h b/google/cloud/bigtable/admin_client.h index 5389bc76ccd17..d383036dd76b4 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..c65cdc2ce0677 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..17c462680df65 100644 --- a/google/cloud/bigtable/instance_admin.h +++ b/google/cloud/bigtable/instance_admin.h @@ -29,6 +29,11 @@ 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 +89,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 : instance_id must be between 6 and 33 characters. + * - display_name : 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 +112,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..4c338cf8ac62a 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..a811cfc4c59de 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..00d66eb06e0dd 100644 --- a/google/cloud/bigtable/table_admin.h +++ b/google/cloud/bigtable/table_admin.h @@ -39,6 +39,11 @@ 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)) {} From 4026edc96b5794de033c9d50b96ff737ab27cc26 Mon Sep 17 00:00:00 2001 From: manish Date: Fri, 28 Sep 2018 04:58:35 +0530 Subject: [PATCH 2/2] fixing formatting nits --- google/cloud/bigtable/admin_client.h | 10 +++++----- google/cloud/bigtable/data_client.h | 10 +++++----- google/cloud/bigtable/instance_admin.h | 11 ++++++----- google/cloud/bigtable/instance_admin_client.h | 4 ++-- google/cloud/bigtable/table.h | 6 +++--- google/cloud/bigtable/table_admin.h | 7 ++++--- 6 files changed, 25 insertions(+), 23 deletions(-) diff --git a/google/cloud/bigtable/admin_client.h b/google/cloud/bigtable/admin_client.h index d383036dd76b4..0d8a080fd0b71 100644 --- a/google/cloud/bigtable/admin_client.h +++ b/google/cloud/bigtable/admin_client.h @@ -43,11 +43,11 @@ class TableAdmin; * * @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. + * `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 c65cdc2ce0677..c9a8c475fa921 100644 --- a/google/cloud/bigtable/data_client.h +++ b/google/cloud/bigtable/data_client.h @@ -43,11 +43,11 @@ class BulkMutator; * * @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. + * `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 17c462680df65..410757d294020 100644 --- a/google/cloud/bigtable/instance_admin.h +++ b/google/cloud/bigtable/instance_admin.h @@ -31,9 +31,10 @@ 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. + * 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: @@ -90,8 +91,8 @@ class InstanceAdmin { * * @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 : instance_id must be between 6 and 33 characters. - * - display_name : display_name must be between 4 and 30 characters. + * - 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 diff --git a/google/cloud/bigtable/instance_admin_client.h b/google/cloud/bigtable/instance_admin_client.h index 4c338cf8ac62a..987b51243fa2e 100644 --- a/google/cloud/bigtable/instance_admin_client.h +++ b/google/cloud/bigtable/instance_admin_client.h @@ -43,11 +43,11 @@ class InstanceAdmin; * * @par Cost * Applications should avoid unnecessarily creating new objects of type - * InstanceAdminClient. Creating a new object of this type typically requires + * `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. + * `InstanceAdminClient` instances when possible. */ class InstanceAdminClient { public: diff --git a/google/cloud/bigtable/table.h b/google/cloud/bigtable/table.h index a811cfc4c59de..c2b3e856a8db0 100644 --- a/google/cloud/bigtable/table.h +++ b/google/cloud/bigtable/table.h @@ -37,9 +37,9 @@ inline namespace BIGTABLE_CLIENT_NS { * 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. + * 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 00d66eb06e0dd..24a8460e9891d 100644 --- a/google/cloud/bigtable/table_admin.h +++ b/google/cloud/bigtable/table_admin.h @@ -41,9 +41,10 @@ class TableAdmin { * 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. + * 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)) {}