From b92933ba81c2e497e7daf239ce9872080da2828e Mon Sep 17 00:00:00 2001 From: Carlos O'Ryan Date: Tue, 30 Nov 2021 12:09:11 -0500 Subject: [PATCH] feat(generator): document details about `*Client` (#7673) Customers often wonder about the performance, thread-safety, and connection pooling in our `*Client` classes. This changes the generator to include this information in the generated code. --- .../golden/golden_kitchen_sink_client.h | 23 ++++++++++++++++ .../golden/golden_thing_admin_client.h | 23 ++++++++++++++++ generator/internal/descriptor_utils.cc | 26 ++++++++++++++++++- generator/internal/descriptor_utils_test.cc | 2 +- google/cloud/bigquery/bigquery_read_client.h | 23 ++++++++++++++++ google/cloud/iam/iam_client.h | 23 ++++++++++++++++ google/cloud/iam/iam_credentials_client.h | 23 ++++++++++++++++ .../cloud/logging/logging_service_v2_client.h | 23 ++++++++++++++++ google/cloud/pubsublite/admin_client.h | 23 ++++++++++++++++ .../secretmanager/secret_manager_client.h | 23 ++++++++++++++++ .../spanner/admin/database_admin_client.h | 23 ++++++++++++++++ .../spanner/admin/instance_admin_client.h | 23 ++++++++++++++++ google/cloud/tasks/cloud_tasks_client.h | 23 ++++++++++++++++ 13 files changed, 279 insertions(+), 2 deletions(-) diff --git a/generator/integration_tests/golden/golden_kitchen_sink_client.h b/generator/integration_tests/golden/golden_kitchen_sink_client.h index 15717474040c8..cd24d0410162a 100644 --- a/generator/integration_tests/golden/golden_kitchen_sink_client.h +++ b/generator/integration_tests/golden/golden_kitchen_sink_client.h @@ -44,6 +44,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// tokens, OpenID Connect ID tokens, self-signed JSON Web Tokens (JWTs), and /// more. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class GoldenKitchenSinkClient { public: explicit GoldenKitchenSinkClient(std::shared_ptr connection); diff --git a/generator/integration_tests/golden/golden_thing_admin_client.h b/generator/integration_tests/golden/golden_thing_admin_client.h index fc43e955c4f55..297d48f73ca07 100644 --- a/generator/integration_tests/golden/golden_thing_admin_client.h +++ b/generator/integration_tests/golden/golden_thing_admin_client.h @@ -42,6 +42,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// databases. It can be also used to create, delete and list backups for a /// database and to restore from an existing backup. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class GoldenThingAdminClient { public: explicit GoldenThingAdminClient(std::shared_ptr connection); diff --git a/generator/internal/descriptor_utils.cc b/generator/internal/descriptor_utils.cc index fefdb03d38202..e844c7f2c03a8 100644 --- a/generator/internal/descriptor_utils.cc +++ b/generator/internal/descriptor_utils.cc @@ -292,7 +292,31 @@ std::string FormatClassCommentsFromServiceComments( absl::StrReplaceAll( ChompByValue(service_source_location.leading_comments), {{"\n\n", "\n///\n/// "}, {"\n", "\n/// "}}), - "\n///"); + R"""( +/// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +///)"""); return absl::StrReplaceAll(doxygen_formatted_comments, {{"/// ", "/// "}}); } diff --git a/generator/internal/descriptor_utils_test.cc b/generator/internal/descriptor_utils_test.cc index 35c95fecd0c2c..5e0501e640f10 100644 --- a/generator/internal/descriptor_utils_test.cc +++ b/generator/internal/descriptor_utils_test.cc @@ -183,7 +183,7 @@ TEST_P(CreateServiceVarsTest, KeySetCorrectly) { {std::make_pair("product_path", "google/cloud/frobber/")}); auto iter = service_vars_.find(GetParam().first); EXPECT_TRUE(iter != service_vars_.end()); - EXPECT_EQ(iter->second, GetParam().second); + EXPECT_THAT(iter->second, HasSubstr(GetParam().second)); } INSTANTIATE_TEST_SUITE_P( diff --git a/google/cloud/bigquery/bigquery_read_client.h b/google/cloud/bigquery/bigquery_read_client.h index 08f56ba948217..7cce49a612911 100644 --- a/google/cloud/bigquery/bigquery_read_client.h +++ b/google/cloud/bigquery/bigquery_read_client.h @@ -36,6 +36,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// /// The Read API can be used to read data from BigQuery. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class BigQueryReadClient { public: explicit BigQueryReadClient( diff --git a/google/cloud/iam/iam_client.h b/google/cloud/iam/iam_client.h index 164c4c250cdb8..7912cd6c2e875 100644 --- a/google/cloud/iam/iam_client.h +++ b/google/cloud/iam/iam_client.h @@ -54,6 +54,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// * Check which roles you can grant for a specific resource /// * Lint, or validate, condition expressions in an IAM policy /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class IAMClient { public: explicit IAMClient(std::shared_ptr connection); diff --git a/google/cloud/iam/iam_credentials_client.h b/google/cloud/iam/iam_credentials_client.h index 1b62c8947c22c..1f97b998823de 100644 --- a/google/cloud/iam/iam_credentials_client.h +++ b/google/cloud/iam/iam_credentials_client.h @@ -43,6 +43,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// tokens, OpenID Connect ID tokens, self-signed JSON Web Tokens (JWTs), and /// more. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class IAMCredentialsClient { public: explicit IAMCredentialsClient( diff --git a/google/cloud/logging/logging_service_v2_client.h b/google/cloud/logging/logging_service_v2_client.h index 3dcc52f9e6741..8cb49ad60faee 100644 --- a/google/cloud/logging/logging_service_v2_client.h +++ b/google/cloud/logging/logging_service_v2_client.h @@ -35,6 +35,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// /// Service for ingesting and querying logs. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class LoggingServiceV2Client { public: explicit LoggingServiceV2Client( diff --git a/google/cloud/pubsublite/admin_client.h b/google/cloud/pubsublite/admin_client.h index ab869ab5a66b7..7ab4134393a29 100644 --- a/google/cloud/pubsublite/admin_client.h +++ b/google/cloud/pubsublite/admin_client.h @@ -37,6 +37,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// subscriptions, such creating, listing, and deleting topics and /// subscriptions. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class AdminServiceClient { public: explicit AdminServiceClient( diff --git a/google/cloud/secretmanager/secret_manager_client.h b/google/cloud/secretmanager/secret_manager_client.h index e8dd412f576d2..66f19c7786307 100644 --- a/google/cloud/secretmanager/secret_manager_client.h +++ b/google/cloud/secretmanager/secret_manager_client.h @@ -41,6 +41,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// * [Secret][google.cloud.secretmanager.v1.Secret] /// * [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class SecretManagerServiceClient { public: explicit SecretManagerServiceClient( diff --git a/google/cloud/spanner/admin/database_admin_client.h b/google/cloud/spanner/admin/database_admin_client.h index 435a09d5a8daa..3c342bf9a36be 100644 --- a/google/cloud/spanner/admin/database_admin_client.h +++ b/google/cloud/spanner/admin/database_admin_client.h @@ -42,6 +42,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// databases. It can be also used to create, delete and list backups for a /// database and to restore from an existing backup. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class DatabaseAdminClient { public: explicit DatabaseAdminClient( diff --git a/google/cloud/spanner/admin/instance_admin_client.h b/google/cloud/spanner/admin/instance_admin_client.h index 88580572f4b2d..4b942df4e3e5c 100644 --- a/google/cloud/spanner/admin/instance_admin_client.h +++ b/google/cloud/spanner/admin/instance_admin_client.h @@ -58,6 +58,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// instance resources, fewer resources are available for other /// databases in that instance, and their performance may suffer. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class InstanceAdminClient { public: explicit InstanceAdminClient( diff --git a/google/cloud/tasks/cloud_tasks_client.h b/google/cloud/tasks/cloud_tasks_client.h index a012c08f06449..bfc495577a023 100644 --- a/google/cloud/tasks/cloud_tasks_client.h +++ b/google/cloud/tasks/cloud_tasks_client.h @@ -37,6 +37,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /// Cloud Tasks allows developers to manage the execution of background /// work in their applications. /// +/// @par Equality +/// +/// Instances of this class created via copy-construction or copy-assignment +/// always compare equal. Instances created with equal +/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare +/// equal share the same underlying resources. +/// +/// @par Performance +/// +/// Creating a new instance of this class is a relatively expensive operation, +/// new objects establish new connections to the service. In contrast, +/// copy-construction, move-construction, and the corresponding assignment +/// operations are relatively efficient as the copies share all underlying +/// resources. +/// +/// @par Thread Safety +/// +/// Concurrent access to different instances of this class, even if they compare +/// equal, is guaranteed to work. Two or more threads operating on the same +/// instance of this class is not guaranteed to work. Since copy-construction +/// and move-construction is a relatively efficient operation, consider using +/// such a copy when using this class from multiple threads. +/// class CloudTasksClient { public: explicit CloudTasksClient(std::shared_ptr connection);