From 60ee8dd2fc6c3e417389059957cda0732bcb9037 Mon Sep 17 00:00:00 2001
From: David Garcia Quintas <dgq@google.com>
Date: Tue, 8 Mar 2016 17:21:42 -0800
Subject: [PATCH] docstrings
---
include/grpc++/alarm.h | 2 +-
include/grpc++/channel.h | 2 +-
.../grpc++/impl/codegen/completion_queue.h | 2 +-
.../impl/codegen/core_codegen_interface.h | 37 +++++++++++--------
include/grpc++/impl/codegen/grpc_library.h | 11 ++++--
include/grpc++/impl/grpc_library.h | 2 +-
include/grpc++/security/credentials.h | 4 +-
include/grpc++/server.h | 2 +-
src/cpp/client/secure_credentials.cc | 16 ++++----
src/cpp/codegen/codegen_init.cc | 6 +++
src/cpp/common/core_codegen.h | 21 +++++------
src/cpp/common/grpc_library.cc | 3 ++
12 files changed, 62 insertions(+), 46 deletions(-)
diff --git a/include/grpc++/alarm.h b/include/grpc++/alarm.h
index 3b8104d135..764837a958 100644
--- a/include/grpc++/alarm.h
+++ b/include/grpc++/alarm.h
@@ -50,7 +50,7 @@ namespace grpc {
class CompletionQueue;
/// A thin wrapper around \a grpc_alarm (see / \a / src/core/surface/alarm.h).
-class Alarm : private GrpcLibrary {
+class Alarm : private GrpcLibraryCodegen {
public:
/// Create a completion queue alarm instance associated to \a cq.
///
diff --git a/include/grpc++/channel.h b/include/grpc++/channel.h
index 80547f7ab8..679d473204 100644
--- a/include/grpc++/channel.h
+++ b/include/grpc++/channel.h
@@ -49,7 +49,7 @@ namespace grpc {
class Channel GRPC_FINAL : public ChannelInterface,
public CallHook,
public std::enable_shared_from_this<Channel>,
- private GrpcLibrary {
+ private GrpcLibraryCodegen {
public:
~Channel();
diff --git a/include/grpc++/impl/codegen/completion_queue.h b/include/grpc++/impl/codegen/completion_queue.h
index 889990d1a0..fdea88e6e3 100644
--- a/include/grpc++/impl/codegen/completion_queue.h
+++ b/include/grpc++/impl/codegen/completion_queue.h
@@ -83,7 +83,7 @@ extern CoreCodegenInterface* g_core_codegen_interface;
/// A thin wrapper around \a grpc_completion_queue (see / \a
/// src/core/surface/completion_queue.h).
-class CompletionQueue : private GrpcLibrary {
+class CompletionQueue : private GrpcLibraryCodegen {
public:
/// Default constructor. Implicitly creates a \a grpc_completion_queue
/// instance.
diff --git a/include/grpc++/impl/codegen/core_codegen_interface.h b/include/grpc++/impl/codegen/core_codegen_interface.h
index 860c773907..a23031fe65 100644
--- a/include/grpc++/impl/codegen/core_codegen_interface.h
+++ b/include/grpc++/impl/codegen/core_codegen_interface.h
@@ -31,7 +31,6 @@
*
*/
-/// XXX
#ifndef GRPCXX_IMPL_CODEGEN_CORE_CODEGEN_INTERFACE_H
#define GRPCXX_IMPL_CODEGEN_CORE_CODEGEN_INTERFACE_H
@@ -41,20 +40,15 @@
namespace grpc {
-class CoreCodegenInterface;
-
-extern CoreCodegenInterface* g_core_codegen_interface;
-
+/// Interface between the codegen library and the minimal subset of core
+/// features required by the generated code.
+///
+/// All undocumented methods are simply forwarding the call to their namesakes.
+/// Please refer to their corresponding documentation for details.
+///
+/// \warning This interface should be considered internal and private.
class CoreCodegenInterface {
public:
- virtual grpc_completion_queue* grpc_completion_queue_create(
- void* reserved) = 0;
- virtual void grpc_completion_queue_destroy(grpc_completion_queue* cq) = 0;
- virtual grpc_event grpc_completion_queue_pluck(grpc_completion_queue* cq,
- void* tag,
- gpr_timespec deadline,
- void* reserved) = 0;
-
// Serialize the msg into a buffer created inside the function. The caller
// should destroy the returned buffer when done with it. If serialization
// fails,
@@ -67,6 +61,17 @@ class CoreCodegenInterface {
grpc::protobuf::Message* msg,
int max_message_size) = 0;
+ /// Upon a failed assertion, log the error.
+ virtual void assert_fail(const char* failed_assertion) = 0;
+
+ virtual grpc_completion_queue* grpc_completion_queue_create(
+ void* reserved) = 0;
+ virtual void grpc_completion_queue_destroy(grpc_completion_queue* cq) = 0;
+ virtual grpc_event grpc_completion_queue_pluck(grpc_completion_queue* cq,
+ void* tag,
+ gpr_timespec deadline,
+ void* reserved) = 0;
+
virtual void* gpr_malloc(size_t size) = 0;
virtual void gpr_free(void* p) = 0;
@@ -75,11 +80,11 @@ class CoreCodegenInterface {
virtual void grpc_metadata_array_destroy(grpc_metadata_array* array) = 0;
virtual gpr_timespec gpr_inf_future(gpr_clock_type type) = 0;
-
- virtual void assert_fail(const char* failed_assertion) = 0;
};
-/* XXX */
+extern CoreCodegenInterface* g_core_codegen_interface;
+
+/// Codegen specific version of \a GPR_ASSERT.
#define GPR_CODEGEN_ASSERT(x) \
do { \
if (!(x)) { \
diff --git a/include/grpc++/impl/codegen/grpc_library.h b/include/grpc++/impl/codegen/grpc_library.h
index 02f9039131..3cdc6f3f7c 100644
--- a/include/grpc++/impl/codegen/grpc_library.h
+++ b/include/grpc++/impl/codegen/grpc_library.h
@@ -45,17 +45,20 @@ class GrpcLibraryInterface {
virtual void shutdown() = 0;
};
+/// Initialized by \a grpc::GrpcLibraryInitializer from
+/// <grpc++/impl/grpc_library.h>
extern GrpcLibraryInterface* g_glip;
-class GrpcLibrary {
+/// Classes that require gRPC to be initialized should inherit from this class.
+class GrpcLibraryCodegen {
public:
- GrpcLibrary() {
+ GrpcLibraryCodegen() {
GPR_CODEGEN_ASSERT(g_glip &&
"gRPC library not initialized. See "
"grpc::internal::GrpcLibraryInitializer.");
g_glip->init();
}
- virtual ~GrpcLibrary() {
+ virtual ~GrpcLibraryCodegen() {
GPR_CODEGEN_ASSERT(g_glip &&
"gRPC library not initialized. See "
"grpc::internal::GrpcLibraryInitializer.");
@@ -65,4 +68,4 @@ class GrpcLibrary {
} // namespace grpc
-#endif // GRPCXX_IMPL_GRPC_LIBRARY_H
+#endif // GRPCXX_IMPL_CODEGEN_GRPC_LIBRARY_H
diff --git a/include/grpc++/impl/grpc_library.h b/include/grpc++/impl/grpc_library.h
index 9d32ec152f..d26f4a4cab 100644
--- a/include/grpc++/impl/grpc_library.h
+++ b/include/grpc++/impl/grpc_library.h
@@ -48,13 +48,13 @@ namespace internal {
class GrpcLibrary GRPC_FINAL : public GrpcLibraryInterface {
public:
void init() GRPC_OVERRIDE { grpc_init(); }
-
void shutdown() GRPC_OVERRIDE { grpc_shutdown(); }
};
static GrpcLibrary g_gli;
static CoreCodegen g_core_codegen;
+/// Instantiating this class ensures the proper initialization of gRPC.
class GrpcLibraryInitializer GRPC_FINAL {
public:
GrpcLibraryInitializer() {
diff --git a/include/grpc++/security/credentials.h b/include/grpc++/security/credentials.h
index e0806c0b7b..f2e2efd7a6 100644
--- a/include/grpc++/security/credentials.h
+++ b/include/grpc++/security/credentials.h
@@ -57,7 +57,7 @@ class SecureCallCredentials;
/// for all the calls on that channel.
///
/// \see http://www.grpc.io/docs/guides/auth.html
-class ChannelCredentials : private GrpcLibrary {
+class ChannelCredentials : private GrpcLibraryCodegen {
public:
ChannelCredentials();
~ChannelCredentials();
@@ -83,7 +83,7 @@ class ChannelCredentials : private GrpcLibrary {
/// authenticate with a server for a given call on a channel.
///
/// \see http://www.grpc.io/docs/guides/auth.html
-class CallCredentials : private GrpcLibrary {
+class CallCredentials : private GrpcLibraryCodegen {
public:
CallCredentials();
~CallCredentials();
diff --git a/include/grpc++/server.h b/include/grpc++/server.h
index c177805236..9eb8c287e1 100644
--- a/include/grpc++/server.h
+++ b/include/grpc++/server.h
@@ -62,7 +62,7 @@ class ThreadPoolInterface;
/// Models a gRPC server.
///
/// Servers are configured and started via \a grpc::ServerBuilder.
-class Server GRPC_FINAL : public ServerInterface, private GrpcLibrary {
+class Server GRPC_FINAL : public ServerInterface, private GrpcLibraryCodegen {
public:
~Server();
diff --git a/src/cpp/client/secure_credentials.cc b/src/cpp/client/secure_credentials.cc
index 074dae7ca7..308455527c 100644
--- a/src/cpp/client/secure_credentials.cc
+++ b/src/cpp/client/secure_credentials.cc
@@ -83,14 +83,14 @@ std::shared_ptr<CallCredentials> WrapCallCredentials(
} // namespace
std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials() {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
return WrapChannelCredentials(grpc_google_default_credentials_create());
}
// Builds SSL Credentials given SSL specific options
std::shared_ptr<ChannelCredentials> SslCredentials(
const SslCredentialsOptions& options) {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
grpc_ssl_pem_key_cert_pair pem_key_cert_pair = {
options.pem_private_key.c_str(), options.pem_cert_chain.c_str()};
@@ -102,7 +102,7 @@ std::shared_ptr<ChannelCredentials> SslCredentials(
// Builds credentials for use when running in GCE
std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials() {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
return WrapCallCredentials(
grpc_google_compute_engine_credentials_create(nullptr));
}
@@ -110,7 +110,7 @@ std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials() {
// Builds JWT credentials.
std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
const grpc::string& json_key, long token_lifetime_seconds) {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
if (token_lifetime_seconds <= 0) {
gpr_log(GPR_ERROR,
"Trying to create JWTCredentials with non-positive lifetime");
@@ -125,7 +125,7 @@ std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
// Builds refresh token credentials.
std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
const grpc::string& json_refresh_token) {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
return WrapCallCredentials(grpc_google_refresh_token_credentials_create(
json_refresh_token.c_str(), nullptr));
}
@@ -133,7 +133,7 @@ std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
// Builds access token credentials.
std::shared_ptr<CallCredentials> AccessTokenCredentials(
const grpc::string& access_token) {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
return WrapCallCredentials(
grpc_access_token_credentials_create(access_token.c_str(), nullptr));
}
@@ -142,7 +142,7 @@ std::shared_ptr<CallCredentials> AccessTokenCredentials(
std::shared_ptr<CallCredentials> GoogleIAMCredentials(
const grpc::string& authorization_token,
const grpc::string& authority_selector) {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
return WrapCallCredentials(grpc_google_iam_credentials_create(
authorization_token.c_str(), authority_selector.c_str(), nullptr));
}
@@ -224,7 +224,7 @@ MetadataCredentialsPluginWrapper::MetadataCredentialsPluginWrapper(
std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
std::unique_ptr<MetadataCredentialsPlugin> plugin) {
- GrpcLibrary init; // To call grpc_init().
+ GrpcLibraryCodegen init; // To call grpc_init().
const char* type = plugin->GetType();
MetadataCredentialsPluginWrapper* wrapper =
new MetadataCredentialsPluginWrapper(std::move(plugin));
diff --git a/src/cpp/codegen/codegen_init.cc b/src/cpp/codegen/codegen_init.cc
index 917f1bb541..37abbad2da 100644
--- a/src/cpp/codegen/codegen_init.cc
+++ b/src/cpp/codegen/codegen_init.cc
@@ -34,5 +34,11 @@
#include <grpc++/impl/codegen/core_codegen_interface.h>
#include <grpc++/impl/codegen/grpc_library.h>
+/// Initializes the global gRPC variables for the codegen library. These will
+/// stay null in the absence of of grpc++ library. In this case, no gRPC
+/// features such as the ability to perform calls will be available. Trying to
+/// perform them would result in a segmentation fault when trying to deference
+/// the following nulled globals.
+
grpc::CoreCodegenInterface* grpc::g_core_codegen_interface = nullptr;
grpc::GrpcLibraryInterface* grpc::g_glip = nullptr;
diff --git a/src/cpp/common/core_codegen.h b/src/cpp/common/core_codegen.h
index fc54b0848f..0d8c6b79f7 100644
--- a/src/cpp/common/core_codegen.h
+++ b/src/cpp/common/core_codegen.h
@@ -31,42 +31,41 @@
*
*/
+// This file should be compiled as part of grpc++.
+
#include <grpc++/impl/codegen/core_codegen_interface.h>
#include <grpc/impl/codegen/grpc_types.h>
#include <grpc/byte_buffer.h>
namespace grpc {
+/// Implementation of the core codegen interface.
class CoreCodegen : public CoreCodegenInterface {
private:
- grpc_completion_queue* grpc_completion_queue_create(void* reserved) override;
+ Status SerializeProto(const grpc::protobuf::Message& msg,
+ grpc_byte_buffer** bp) override;
- void grpc_completion_queue_destroy(grpc_completion_queue* cq) override;
+ Status DeserializeProto(grpc_byte_buffer* buffer,
+ grpc::protobuf::Message* msg,
+ int max_message_size) override;
+ grpc_completion_queue* grpc_completion_queue_create(void* reserved) override;
+ void grpc_completion_queue_destroy(grpc_completion_queue* cq) override;
grpc_event grpc_completion_queue_pluck(grpc_completion_queue* cq, void* tag,
gpr_timespec deadline,
void* reserved) override;
void* gpr_malloc(size_t size) override;
-
void gpr_free(void* p) override;
void grpc_byte_buffer_destroy(grpc_byte_buffer* bb) override;
void grpc_metadata_array_init(grpc_metadata_array* array) override;
-
void grpc_metadata_array_destroy(grpc_metadata_array* array) override;
gpr_timespec gpr_inf_future(gpr_clock_type type) override;
void assert_fail(const char* failed_assertion) override;
-
- Status SerializeProto(const grpc::protobuf::Message& msg,
- grpc_byte_buffer** bp) override;
-
- Status DeserializeProto(grpc_byte_buffer* buffer,
- grpc::protobuf::Message* msg,
- int max_message_size) override;
};
} // namespace grpc
diff --git a/src/cpp/common/grpc_library.cc b/src/cpp/common/grpc_library.cc
index 72be4e41a5..c08b8f81f3 100644
--- a/src/cpp/common/grpc_library.cc
+++ b/src/cpp/common/grpc_library.cc
@@ -34,6 +34,9 @@
#include <grpc++/impl/codegen/core_codegen_interface.h>
#include <grpc++/impl/codegen/grpc_library.h>
+/// Definition of gRPC's globals. These should be associated with actual
+/// as part of the instantiation of a \a grpc::GrpcLibraryInitializer variable.
+
namespace grpc {
GrpcLibraryInterface *g_glip = nullptr;
--
GitLab