Merge pull request #11026 from markdroth/grpclb_drop_alt
Implement grpclb drop support.
diff --git a/BUILD b/BUILD
index 3e54e87..cc5fd3e 100644
--- a/BUILD
+++ b/BUILD
@@ -745,7 +745,7 @@
"grpc_transport_chttp2_server_insecure",
"grpc_workaround_cronet_compression_filter",
"grpc_server_backward_compatibility",
- ]
+ ],
)
grpc_cc_library(
@@ -1400,22 +1400,22 @@
grpc_cc_library(
name = "grpc++_base",
- hdrs = GRPCXX_HDRS,
srcs = GRPCXX_SRCS,
- public_hdrs = GRPCXX_PUBLIC_HDRS,
+ hdrs = GRPCXX_HDRS,
language = "c++",
+ public_hdrs = GRPCXX_PUBLIC_HDRS,
deps = [
- "grpc++_codegen_base",
"grpc",
+ "grpc++_codegen_base",
],
)
grpc_cc_library(
name = "grpc++_base_unsecure",
- hdrs = GRPCXX_HDRS,
srcs = GRPCXX_SRCS,
- public_hdrs = GRPCXX_PUBLIC_HDRS,
+ hdrs = GRPCXX_HDRS,
language = "c++",
+ public_hdrs = GRPCXX_PUBLIC_HDRS,
deps = [
"grpc++_codegen_base",
"grpc_unsecure",
@@ -1539,5 +1539,4 @@
],
)
-
grpc_generate_one_off_targets()
diff --git a/build.yaml b/build.yaml
index 2c54055..ecd9ebe 100644
--- a/build.yaml
+++ b/build.yaml
@@ -4628,7 +4628,6 @@
deps:
- grpc
- gpr
- - ares
- boringssl
headers:
- src/php/ext/grpc/byte_buffer.h
@@ -4642,6 +4641,7 @@
- src/php/ext/grpc/server.h
- src/php/ext/grpc/server_credentials.h
- src/php/ext/grpc/timeval.h
+ - src/php/ext/grpc/version.h
src:
- src/php/ext/grpc/byte_buffer.c
- src/php/ext/grpc/call.c
diff --git a/composer.json b/composer.json
index 284b57a..2cf3f17 100644
--- a/composer.json
+++ b/composer.json
@@ -6,12 +6,15 @@
"homepage": "http://grpc.io",
"license": "BSD-3-Clause",
"require": {
- "php": ">=5.5.0",
- "google/protobuf": "^v3.3.0"
+ "php": ">=5.5.0"
},
"require-dev": {
"google/auth": "v0.9"
},
+ "suggest": {
+ "ext-protobuf": "For better performance, install the protobuf C extension.",
+ "google/protobuf": "To get started using grpc quickly, install the native protobuf library."
+ },
"autoload": {
"psr-4": {
"Grpc\\": "src/php/lib/Grpc/"
diff --git a/config.m4 b/config.m4
index cc050ed..ec463b2 100644
--- a/config.m4
+++ b/config.m4
@@ -8,23 +8,21 @@
PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/include)
PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/src/php/ext/grpc)
PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/boringssl/include)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares/cares)
LIBS="-lpthread $LIBS"
+ CFLAGS="-Wall -Werror -Wno-parentheses-equality -Wno-unused-value -std=c11"
+ CXXFLAGS="-std=c++11"
GRPC_SHARED_LIBADD="-lpthread $GRPC_SHARED_LIBADD"
+ PHP_REQUIRE_CXX()
PHP_ADD_LIBRARY(pthread)
-
PHP_ADD_LIBRARY(dl,,GRPC_SHARED_LIBADD)
PHP_ADD_LIBRARY(dl)
case $host in
*darwin*)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares/config_darwin)
;;
*)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares/config_linux)
PHP_ADD_LIBRARY(rt,,GRPC_SHARED_LIBADD)
PHP_ADD_LIBRARY(rt)
;;
@@ -639,59 +637,9 @@
third_party/boringssl/ssl/tls13_server.c \
third_party/boringssl/ssl/tls_method.c \
third_party/boringssl/ssl/tls_record.c \
- third_party/cares/cares/ares__close_sockets.c \
- third_party/cares/cares/ares__get_hostent.c \
- third_party/cares/cares/ares__read_line.c \
- third_party/cares/cares/ares__timeval.c \
- third_party/cares/cares/ares_cancel.c \
- third_party/cares/cares/ares_create_query.c \
- third_party/cares/cares/ares_data.c \
- third_party/cares/cares/ares_destroy.c \
- third_party/cares/cares/ares_expand_name.c \
- third_party/cares/cares/ares_expand_string.c \
- third_party/cares/cares/ares_fds.c \
- third_party/cares/cares/ares_free_hostent.c \
- third_party/cares/cares/ares_free_string.c \
- third_party/cares/cares/ares_getenv.c \
- third_party/cares/cares/ares_gethostbyaddr.c \
- third_party/cares/cares/ares_gethostbyname.c \
- third_party/cares/cares/ares_getnameinfo.c \
- third_party/cares/cares/ares_getopt.c \
- third_party/cares/cares/ares_getsock.c \
- third_party/cares/cares/ares_init.c \
- third_party/cares/cares/ares_library_init.c \
- third_party/cares/cares/ares_llist.c \
- third_party/cares/cares/ares_mkquery.c \
- third_party/cares/cares/ares_nowarn.c \
- third_party/cares/cares/ares_options.c \
- third_party/cares/cares/ares_parse_a_reply.c \
- third_party/cares/cares/ares_parse_aaaa_reply.c \
- third_party/cares/cares/ares_parse_mx_reply.c \
- third_party/cares/cares/ares_parse_naptr_reply.c \
- third_party/cares/cares/ares_parse_ns_reply.c \
- third_party/cares/cares/ares_parse_ptr_reply.c \
- third_party/cares/cares/ares_parse_soa_reply.c \
- third_party/cares/cares/ares_parse_srv_reply.c \
- third_party/cares/cares/ares_parse_txt_reply.c \
- third_party/cares/cares/ares_platform.c \
- third_party/cares/cares/ares_process.c \
- third_party/cares/cares/ares_query.c \
- third_party/cares/cares/ares_search.c \
- third_party/cares/cares/ares_send.c \
- third_party/cares/cares/ares_strcasecmp.c \
- third_party/cares/cares/ares_strdup.c \
- third_party/cares/cares/ares_strerror.c \
- third_party/cares/cares/ares_timeout.c \
- third_party/cares/cares/ares_version.c \
- third_party/cares/cares/ares_writev.c \
- third_party/cares/cares/bitncmp.c \
- third_party/cares/cares/inet_net_pton.c \
- third_party/cares/cares/inet_ntop.c \
- third_party/cares/cares/windows_port.c \
- , $ext_shared, , -Wall -Werror \
- -Wno-parentheses-equality -Wno-unused-value -std=c11 \
- -fvisibility=hidden -DOPENSSL_NO_ASM -D_GNU_SOURCE -DWIN32_LEAN_AND_MEAN \
- -D_HAS_EXCEPTIONS=0 -DNOMINMAX)
+ , $ext_shared, , -fvisibility=hidden \
+ -DOPENSSL_NO_ASM -D_GNU_SOURCE -DWIN32_LEAN_AND_MEAN \
+ -D_HAS_EXCEPTIONS=0 -DNOMINMAX -DGRPC_ARES=0)
PHP_ADD_BUILD_DIR($ext_builddir/src/php/ext/grpc)
@@ -791,6 +739,5 @@
PHP_ADD_BUILD_DIR($ext_builddir/third_party/boringssl/crypto/x509)
PHP_ADD_BUILD_DIR($ext_builddir/third_party/boringssl/crypto/x509v3)
PHP_ADD_BUILD_DIR($ext_builddir/third_party/boringssl/ssl)
- PHP_ADD_BUILD_DIR($ext_builddir/third_party/cares/cares)
PHP_ADD_BUILD_DIR($ext_builddir/third_party/nanopb)
fi
diff --git a/doc/PROTOCOL-WEB.md b/doc/PROTOCOL-WEB.md
index 6bb2808..5f37df9 100644
--- a/doc/PROTOCOL-WEB.md
+++ b/doc/PROTOCOL-WEB.md
@@ -1,4 +1,4 @@
-# Overview
+# gRPC Web
gRPC-Web provides a JS client library that supports the same API
as gRPC-Node to access a gRPC service. Due to browser limitation,
diff --git a/doc/compression.md b/doc/compression.md
index de245d9..ee22bc3 100644
--- a/doc/compression.md
+++ b/doc/compression.md
@@ -1,4 +1,4 @@
-## **gRPC Compression**
+## gRPC Compression
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
@@ -112,7 +112,7 @@
1. An ill-constructed message with its [Compressed-Flag
bit](PROTOCOL-HTTP2.md#compressed-flag)
set but lacking a
-"[grpc-encoding](PROTOCOL-HTTP2.md#message-encoding)"
+[grpc-encoding](PROTOCOL-HTTP2.md#message-encoding)
entry different from _identity_ in its metadata MUST fail with `INTERNAL`
status, its associated description indicating the invalid Compressed-Flag
condition.
diff --git a/doc/cpp-style-guide.md b/doc/cpp-style-guide.md
index a1f9135..8211703 100644
--- a/doc/cpp-style-guide.md
+++ b/doc/cpp-style-guide.md
@@ -5,5 +5,4 @@
guide] (https://google.github.io/styleguide/cppguide.html). Additionally,
as in C, layout rules are defined by clang-format, and all code
should be passed through clang-format. A (docker-based) script to do
-so is included in [tools/distrib/clang\_format\_code.sh]
-(../tools/distrib/clang_format_code.sh).
+so is included in [tools/distrib/clang_format_code.sh](../tools/distrib/clang_format_code.sh).
diff --git a/doc/fail_fast.md b/doc/fail_fast.md
index 2dd5561..ff3d235 100644
--- a/doc/fail_fast.md
+++ b/doc/fail_fast.md
@@ -1 +1 @@
-Moved to wait-for-ready.md
+Moved to [wait-for-ready.md](wait-for-ready.md)
diff --git a/doc/service_config.md b/doc/service_config.md
index 8039fca..99d985f 100644
--- a/doc/service_config.md
+++ b/doc/service_config.md
@@ -131,8 +131,8 @@
# Architecture
-A service config is associated with a server name. The [name
-resolver](naming.md) plugin, when asked to resolve a particular server
+A service config is associated with a server name. The [name resolver](naming.md)
+plugin, when asked to resolve a particular server
name, will return both the resolved addresses and the service config.
TODO(roth): Design how the service config will be encoded in DNS.
diff --git a/doc/stress_test_framework.md b/doc/stress_test_framework.md
index 18f545e..2212d98 100644
--- a/doc/stress_test_framework.md
+++ b/doc/stress_test_framework.md
@@ -2,7 +2,7 @@
(Sree Kuchibhotla - sreek@)
-> Status: This is implemented. More details at [README.md](https://github.com/grpc/grpc/blob/master/tools/run_tests/stress_test/README.md)
+Status: This is implemented. More details at [README.md](https://github.com/grpc/grpc/blob/master/tools/run_tests/stress_test/README.md)
**I. GOALS**
diff --git a/doc/workarounds.md b/doc/workarounds.md
new file mode 100644
index 0000000..bc51186
--- /dev/null
+++ b/doc/workarounds.md
@@ -0,0 +1,19 @@
+# gRPC Server Backward Compatibility Issues and Workarounds Manageent
+
+## Introduction
+This document lists the workarounds implemented on gRPC servers for record and reference when users need to enable a certain workaround.
+
+## Workaround List
+
+### Cronet Compression
+
+**Workaround ID:** WORKAROUND\_ID\_CRONET\_COMPRESSION
+
+**Date added:** May 06, 2017
+
+**Status:** Implemented in C core and C++
+
+**Issue:** Before version v1.3.0-dev, gRPC iOS client's Cronet transport did not implement compression. However the clients still claim to support compression. As a result, a client fails to parse received message when the message is compressed.
+The problem above was resolved in gRPC v1.3.0-dev. For backward compatibility, a server must forcingly disable compression for gRPC clients of version lower than or equal to v1.3.0-dev.
+
+**Workaround Description:** Implemented as a server channel filter in C core. The filter identifies the version of peer client with incoming `user-agent` header of each call. If the client's gRPC version is lower that or equal to v1.3.x, a flag GRPC_WRITE_NO_COMPRESS is marked for all send_message ops which prevents compression of the messages to be sent out.
diff --git a/examples/php/composer.json b/examples/php/composer.json
index f4b177c..9d900eb 100644
--- a/examples/php/composer.json
+++ b/examples/php/composer.json
@@ -2,7 +2,8 @@
"name": "grpc/grpc-demo",
"description": "gRPC example for PHP",
"require": {
- "grpc/grpc": "^v1.1.0"
+ "grpc/grpc": "^v1.3.0",
+ "google/protobuf": "^v3.3.0"
},
"autoload": {
"psr-4": {
diff --git a/include/grpc++/ext/health_check_service_server_builder_option.h b/include/grpc++/ext/health_check_service_server_builder_option.h
index 4861daa..a27841a 100644
--- a/include/grpc++/ext/health_check_service_server_builder_option.h
+++ b/include/grpc++/ext/health_check_service_server_builder_option.h
@@ -44,8 +44,8 @@
class HealthCheckServiceServerBuilderOption : public ServerBuilderOption {
public:
- // The ownership of hc will be taken and transferred to the grpc server.
- // To explicitly disable default service, pass in a nullptr.
+ /// The ownership of hc will be taken and transferred to the grpc server.
+ /// To explicitly disable default service, pass in a nullptr.
explicit HealthCheckServiceServerBuilderOption(
std::unique_ptr<HealthCheckServiceInterface> hc);
~HealthCheckServiceServerBuilderOption() override {}
diff --git a/include/grpc++/ext/proto_server_reflection_plugin.h b/include/grpc++/ext/proto_server_reflection_plugin.h
index 66f39eb..6497bba 100644
--- a/include/grpc++/ext/proto_server_reflection_plugin.h
+++ b/include/grpc++/ext/proto_server_reflection_plugin.h
@@ -59,8 +59,8 @@
std::shared_ptr<grpc::ProtoServerReflection> reflection_service_;
};
-// Add proto reflection plugin to ServerBuilder. This function should be called
-// at the static initialization time.
+/// Add proto reflection plugin to ServerBuilder. This function should be called
+/// at the static initialization time.
void InitProtoReflectionServerBuilderPlugin();
} // namespace reflection
diff --git a/include/grpc++/generic/generic_stub.h b/include/grpc++/generic/generic_stub.h
index 02c00d0..1478846 100644
--- a/include/grpc++/generic/generic_stub.h
+++ b/include/grpc++/generic/generic_stub.h
@@ -43,14 +43,18 @@
typedef ClientAsyncReaderWriter<ByteBuffer, ByteBuffer>
GenericClientAsyncReaderWriter;
-// Generic stubs provide a type-unsafe interface to call gRPC methods
-// by name.
+/// Generic stubs provide a type-unsafe interface to call gRPC methods
+/// by name.
class GenericStub final {
public:
explicit GenericStub(std::shared_ptr<ChannelInterface> channel)
: channel_(channel) {}
- // begin a call to a named method
+ /// Begin a call to a named method \a method using \a context.
+ /// A tag \a tag will be delivered to \a cq when the call has been started
+ /// (i.e, initial metadata has been sent).
+ /// The return value only indicates whether or not registration of the call
+ /// succeeded (i.e. the call won't proceed if the return value is nullptr).
std::unique_ptr<GenericClientAsyncReaderWriter> Call(
ClientContext* context, const grpc::string& method, CompletionQueue* cq,
void* tag);
diff --git a/include/grpc++/grpc++.h b/include/grpc++/grpc++.h
index daecfea..978b172 100644
--- a/include/grpc++/grpc++.h
+++ b/include/grpc++/grpc++.h
@@ -34,14 +34,18 @@
/// \mainpage gRPC C++ API
///
/// The gRPC C++ API mainly consists of the following classes:
+//
/// - grpc::Channel, which represents the connection to an endpoint. See [the
/// gRPC Concepts page](http://www.grpc.io/docs/guides/concepts.html) for more
/// details. Channels are created by the factory function grpc::CreateChannel.
+//
/// - grpc::CompletionQueue, the producer-consumer queue used for all
/// asynchronous communication with the gRPC runtime.
+//
/// - grpc::ClientContext and grpc::ServerContext, where optional configuration
/// for an RPC can be set, such as setting custom metadata to be conveyed to the
/// peer, compression settings, authentication, etc.
+//
/// - grpc::Server, representing a gRPC server, created by grpc::ServerBuilder.
///
/// Streaming calls are handled with the streaming classes in
diff --git a/include/grpc++/health_check_service_interface.h b/include/grpc++/health_check_service_interface.h
index 0eed702..c1b4319 100644
--- a/include/grpc++/health_check_service_interface.h
+++ b/include/grpc++/health_check_service_interface.h
@@ -41,26 +41,27 @@
const char kHealthCheckServiceInterfaceArg[] =
"grpc.health_check_service_interface";
-// The gRPC server uses this interface to expose the health checking service
-// without depending on protobuf.
+/// The gRPC server uses this interface to expose the health checking service
+/// without depending on protobuf.
class HealthCheckServiceInterface {
public:
virtual ~HealthCheckServiceInterface() {}
- // Set or change the serving status of the given service_name.
+ /// Set or change the serving status of the given service_name.
virtual void SetServingStatus(const grpc::string& service_name,
bool serving) = 0;
- // Apply to all registered service names.
+ /// Apply to all registered service names.
virtual void SetServingStatus(bool serving) = 0;
};
-// Enable/disable the default health checking service. This applies to all C++
-// servers created afterwards. For each server, user can override the default
-// with a HealthCheckServiceServerBuilderOption.
-// NOT thread safe.
+/// Enable/disable the default health checking service. This applies to all C++
+/// servers created afterwards. For each server, user can override the default
+/// with a HealthCheckServiceServerBuilderOption.
+/// NOT thread safe.
void EnableDefaultHealthCheckService(bool enable);
-// NOT thread safe.
+/// Returns whether the default health checking service is enabled.
+/// NOT thread safe.
bool DefaultHealthCheckServiceEnabled();
} // namespace grpc
diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h
index f97d824..04fc524 100644
--- a/include/grpc++/impl/codegen/async_stream.h
+++ b/include/grpc++/impl/codegen/async_stream.h
@@ -53,16 +53,38 @@
/// Request notification of the reading of the initial metadata. Completion
/// will be notified by \a tag on the associated completion queue.
/// This call is optional, but if it is used, it cannot be used concurrently
- /// with or after the \a Read method.
+ /// with or after the \a AsyncReaderInterface::Read method.
///
/// \param[in] tag Tag identifying this request.
virtual void ReadInitialMetadata(void* tag) = 0;
- /// Indicate that the stream is to be finished and request notification
- /// Should not be used concurrently with other operations
+ /// Indicate that the stream is to be finished and request notification for
+ /// when the call has been ended.
+ /// Should not be used concurrently with other operations.
///
- /// \param[out] status To be updated with the operation status.
+ /// It is appropriate to call this method when both:
+ /// * the client side has no more message to send
+ /// (this can be declared implicitly by calling this method, or
+ /// explicitly through an earlier call to the <i>WritesDone</i> method
+ /// of the class in use, e.g. \a ClientAsyncWriterInterface::WritesDone or
+ /// \a ClientAsyncReaderWriterInterface::WritesDone).
+ /// * there are no more messages to be received from the server (this can
+ /// be known implicitly by the calling code, or explicitly from an
+ /// earlier call to \a AsyncReaderInterface::Read that yielded a failed
+ /// result, e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false').
+ ///
+ /// This function will return when either:
+ /// - all incoming messages have been read and the server has returned
+ /// a status.
+ /// - the server has returned a non-OK status.
+ /// - the call failed for some reason and the library generated a
+ /// status.
+ ///
+ /// Note that implementations of this method attempt to receive initial
+ /// metadata from the server if initial metadata hasn't yet been received.
+ ///
/// \param[in] tag Tag identifying this request.
+ /// \param[out] status To be updated with the operation status.
virtual void Finish(Status* status, void* tag) = 0;
};
@@ -77,11 +99,14 @@
/// This is thread-safe with respect to \a Write or \a WritesDone methods. It
/// should not be called concurrently with other streaming APIs
/// on the same stream. It is not meaningful to call it concurrently
- /// with another \a Read on the same stream since reads on the same stream
- /// are delivered in order.
+ /// with another \a AsyncReaderInterface::Read on the same stream since reads
+ /// on the same stream are delivered in order.
///
/// \param[out] msg Where to eventually store the read message.
/// \param[in] tag The tag identifying the operation.
+ ///
+ /// Side effect: note that this method attempt to receive initial metadata for
+ /// a stream if it hasn't yet been received.
virtual void Read(R* msg, void* tag) = 0;
};
@@ -96,7 +121,7 @@
/// Only one write may be outstanding at any given time. This means that
/// after calling Write, one must wait to receive \a tag from the completion
/// queue BEFORE calling Write again.
- /// This is thread-safe with respect to \a Read
+ /// This is thread-safe with respect to \a AsyncReaderInterface::Read
///
/// \param[in] msg The message to be written.
/// \param[in] tag The tag identifying the operation.
@@ -109,7 +134,7 @@
/// after calling Write, one must wait to receive \a tag from the completion
/// queue BEFORE calling Write again.
/// WriteOptions \a options is used to set the write options of this message.
- /// This is thread-safe with respect to \a Read
+ /// This is thread-safe with respect to \a AsyncReaderInterface::Read
///
/// \param[in] msg The message to be written.
/// \param[in] options The WriteOptions to be used to write this message.
@@ -117,11 +142,11 @@
virtual void Write(const W& msg, WriteOptions options, void* tag) = 0;
/// Request the writing of \a msg and coalesce it with the writing
- /// of trailing metadata, using WriteOptions \a options with identifying tag
- /// \a tag.
+ /// of trailing metadata, using WriteOptions \a options with
+ /// identifying tag \a tag.
///
- /// For client, WriteLast is equivalent of performing Write and WritesDone in
- /// a single step.
+ /// For client, WriteLast is equivalent of performing Write and
+ /// WritesDone in a single step.
/// For server, WriteLast buffers the \a msg. The writing of \a msg is held
/// until Finish is called, where \a msg and trailing metadata are coalesced
/// and write is initiated. Note that WriteLast can only buffer \a msg up to
@@ -140,10 +165,17 @@
class ClientAsyncReaderInterface : public ClientAsyncStreamingInterface,
public AsyncReaderInterface<R> {};
+/// Async client-side API for doing server-streaming RPCs,
+/// where the incoming message stream coming from the server has
+/// messages of type \a R.
template <class R>
class ClientAsyncReader final : public ClientAsyncReaderInterface<R> {
public:
/// Create a stream and write the first request out.
+ /// \a tag will be notified on \a cq when the call has been started and
+ /// \a request has been written out.
+ /// Note that \a context will be used to fill in custom initial metadata
+ /// used to send to the server when starting the call.
template <class W>
static ClientAsyncReader* Create(ChannelInterface* channel,
CompletionQueue* cq, const RpcMethod& method,
@@ -160,6 +192,14 @@
assert(size == sizeof(ClientAsyncReader));
}
+ /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata
+ /// method for semantics.
+ ///
+ /// Side effect:
+ /// - upon receiving initial metadata from the server,
+ /// the \a ClientContext associated with this call is updated, and the
+ /// calling code can access the received metadata through the
+ /// \a ClientContext.
void ReadInitialMetadata(void* tag) override {
GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_);
@@ -177,6 +217,11 @@
call_.PerformOps(&read_ops_);
}
+ /// See the \a ClientAsyncStreamingInterface.Finish method for semantics.
+ ///
+ /// Side effect:
+ /// - the \a ClientContext associated with this call is updated with
+ /// possible initial and trailing metadata received from the server.
void Finish(Status* status, void* tag) override {
finish_ops_.set_output_tag(tag);
if (!context_->initial_metadata_received_) {
@@ -214,16 +259,27 @@
class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface,
public AsyncWriterInterface<W> {
public:
- /// Signal the client is done with the writes.
- /// Thread-safe with respect to \a Read
+ /// Signal the client is done with the writes (half-close the client stream).
+ /// Thread-safe with respect to \a AsyncReaderInterface::Read
///
/// \param[in] tag The tag identifying the operation.
virtual void WritesDone(void* tag) = 0;
};
+/// Async API on the client side for doing client-streaming RPCs,
+/// where the outgoing message stream going to the server contains
+/// messages of type \a W.
template <class W>
class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> {
public:
+ /// Create a stream and write the first request out.
+ /// \a tag will be notified on \a cq when the call has been started (i.e.
+ /// intitial metadata sent) and \a request has been written out.
+ /// Note that \a context will be used to fill in custom initial metadata
+ /// used to send to the server when starting the call.
+ /// \a response will be filled in with the single expected response
+ /// message from the server upon a successful call to the \a Finish
+ /// method of this instance.
template <class R>
static ClientAsyncWriter* Create(ChannelInterface* channel,
CompletionQueue* cq, const RpcMethod& method,
@@ -240,6 +296,13 @@
assert(size == sizeof(ClientAsyncWriter));
}
+ /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method for
+ /// semantics.
+ ///
+ /// Side effect:
+ /// - upon receiving initial metadata from the server, the \a ClientContext
+ /// associated with this call is updated, and the calling code can access
+ /// the received metadata through the \a ClientContext.
void ReadInitialMetadata(void* tag) override {
GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_);
@@ -272,6 +335,13 @@
call_.PerformOps(&write_ops_);
}
+ /// See the \a ClientAsyncStreamingInterface.Finish method for semantics.
+ ///
+ /// Side effect:
+ /// - the \a ClientContext associated with this call is updated with
+ /// possible initial and trailing metadata received from the server.
+ /// - attempts to fill in the \a response parameter passed to this class's
+ /// constructor with the server's response message.
void Finish(Status* status, void* tag) override {
finish_ops_.set_output_tag(tag);
if (!context_->initial_metadata_received_) {
@@ -310,23 +380,34 @@
finish_ops_;
};
-/// Client-side interface for asynchronous bi-directional streaming.
+/// Async client-side interface for bi-directional streaming,
+/// where the client-to-server message stream has messages of type \a W,
+/// and the server-to-client message stream has messages of type \a R.
template <class W, class R>
class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface,
public AsyncWriterInterface<W>,
public AsyncReaderInterface<R> {
public:
- /// Signal the client is done with the writes.
- /// Thread-safe with respect to \a Read
+ /// Signal the client is done with the writes (half-close the client stream).
+ /// Thread-safe with respect to \a AsyncReaderInterface::Read
///
/// \param[in] tag The tag identifying the operation.
virtual void WritesDone(void* tag) = 0;
};
+/// Async client-side interface for bi-directional streaming,
+/// where the outgoing message stream going to the server
+/// has messages of type \a W, and the incoming message stream coming
+/// from the server has messages of type \a R.
template <class W, class R>
class ClientAsyncReaderWriter final
: public ClientAsyncReaderWriterInterface<W, R> {
public:
+ /// Create a stream and write the first request out.
+ /// \a tag will be notified on \a cq when the call has been started (i.e.
+ /// intitial metadata sent).
+ /// Note that \a context will be used to fill in custom initial metadata
+ /// used to send to the server when starting the call.
static ClientAsyncReaderWriter* Create(ChannelInterface* channel,
CompletionQueue* cq,
const RpcMethod& method,
@@ -343,6 +424,13 @@
assert(size == sizeof(ClientAsyncReaderWriter));
}
+ /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method
+ /// for semantics of this method.
+ ///
+ /// Side effect:
+ /// - upon receiving initial metadata from the server, the \a ClientContext
+ /// is updated with it, and then the receiving initial metadata can
+ /// be accessed through this \a ClientContext.
void ReadInitialMetadata(void* tag) override {
GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_);
@@ -384,6 +472,10 @@
call_.PerformOps(&write_ops_);
}
+ /// See the \a ClientAsyncStreamingInterface.Finish method for semantics.
+ /// Side effect
+ /// - the \a ClientContext associated with this call is updated with
+ /// possible initial and trailing metadata sent from the server.
void Finish(Status* status, void* tag) override {
finish_ops_.set_output_tag(tag);
if (!context_->initial_metadata_received_) {
@@ -422,17 +514,62 @@
class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface,
public AsyncReaderInterface<R> {
public:
+ /// Indicate that the stream is to be finished with a certain status code
+ /// and also send out \a msg response to the client.
+ /// Request notification for when the server has sent the response and the
+ /// appropriate signals to the client to end the call.
+ /// Should not be used concurrently with other operations.
+ ///
+ /// It is appropriate to call this method when:
+ /// * all messages from the client have been received (either known
+ /// implictly, or explicitly because a previous
+ /// \a AsyncReaderInterface::Read operation with a non-ok result,
+ /// e.g., cq->Next(&read_tag, &ok) filled in 'ok' with 'false').
+ ///
+ /// This operation will end when the server has finished sending out initial
+ /// metadata (if not sent already), response message, and status, or if
+ /// some failure occurred when trying to do so.
+ ///
+ /// \param[in] tag Tag identifying this request.
+ /// \param[in] status To be sent to the client as the result of this call.
+ /// \param[in] msg To be sent to the client as the response for this call.
virtual void Finish(const W& msg, const Status& status, void* tag) = 0;
+ /// Indicate that the stream is to be finished with a certain
+ /// non-OK status code.
+ /// Request notification for when the server has sent the appropriate
+ /// signals to the client to end the call.
+ /// Should not be used concurrently with other operations.
+ ///
+ /// This call is meant to end the call with some error, and can be called at
+ /// any point that the server would like to "fail" the call (though note
+ /// this shouldn't be called concurrently with any other "sending" call, like
+ /// \a AsyncWriterInterface::Write).
+ ///
+ /// This operation will end when the server has finished sending out initial
+ /// metadata (if not sent already), and status, or if some failure occurred
+ /// when trying to do so.
+ ///
+ /// \param[in] tag Tag identifying this request.
+ /// \param[in] status To be sent to the client as the result of this call.
+ /// - Note: \a status must have a non-OK code.
virtual void FinishWithError(const Status& status, void* tag) = 0;
};
+/// Async server-side API for doing client-streaming RPCs,
+/// where the incoming message stream from the client has messages of type \a R,
+/// and the single response message sent from the server is type \a W.
template <class W, class R>
class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> {
public:
explicit ServerAsyncReader(ServerContext* ctx)
: call_(nullptr, nullptr, nullptr), ctx_(ctx) {}
+ /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics.
+ ///
+ /// Implicit input parameter:
+ /// - The initial metadata that will be sent to the client from this op will
+ /// be taken from the \a ServerContext associated with the call.
void SendInitialMetadata(void* tag) override {
GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_);
@@ -452,6 +589,14 @@
call_.PerformOps(&read_ops_);
}
+ /// See the \a ServerAsyncReaderInterface.Read method for semantics
+ ///
+ /// Side effect:
+ /// - also sends initial metadata if not alreay sent.
+ /// - uses the \a ServerContext associated with this call to send possible
+ /// initial and trailing metadata.
+ ///
+ /// Note: \a msg is not sent if \a status has a non-OK code.
void Finish(const W& msg, const Status& status, void* tag) override {
finish_ops_.set_output_tag(tag);
if (!ctx_->sent_initial_metadata_) {
@@ -472,6 +617,12 @@
call_.PerformOps(&finish_ops_);
}
+ /// See the \a ServerAsyncReaderInterface.Read method for semantics
+ ///
+ /// Side effect:
+ /// - also sends initial metadata if not alreay sent.
+ /// - uses the \a ServerContext associated with this call to send possible
+ /// initial and trailing metadata.
void FinishWithError(const Status& status, void* tag) override {
GPR_CODEGEN_ASSERT(!status.ok());
finish_ops_.set_output_tag(tag);
@@ -503,14 +654,32 @@
class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface,
public AsyncWriterInterface<W> {
public:
+ /// Indicate that the stream is to be finished with a certain status code.
+ /// Request notification for when the server has sent the appropriate
+ /// signals to the client to end the call.
+ /// Should not be used concurrently with other operations.
+ ///
+ /// It is appropriate to call this method when either:
+ /// * all messages from the client have been received (either known
+ /// implictly, or explicitly because a previous \a
+ /// AsyncReaderInterface::Read operation with a non-ok
+ /// result (e.g., cq->Next(&read_tag, &ok) filled in 'ok' with 'false'.
+ /// * it is desired to end the call early with some non-OK status code.
+ ///
+ /// This operation will end when the server has finished sending out initial
+ /// metadata (if not sent already), response message, and status, or if
+ /// some failure occurred when trying to do so.
+ ///
+ /// \param[in] tag Tag identifying this request.
+ /// \param[in] status To be sent to the client as the result of this call.
virtual void Finish(const Status& status, void* tag) = 0;
/// Request the writing of \a msg and coalesce it with trailing metadata which
- /// contains \a status, using WriteOptions options with identifying tag \a
- /// tag.
+ /// contains \a status, using WriteOptions options with
+ /// identifying tag \a tag.
///
- /// WriteAndFinish is equivalent of performing WriteLast and Finish in a
- /// single step.
+ /// WriteAndFinish is equivalent of performing WriteLast and Finish
+ /// in a single step.
///
/// \param[in] msg The message to be written.
/// \param[in] options The WriteOptions to be used to write this message.
@@ -520,12 +689,21 @@
const Status& status, void* tag) = 0;
};
+/// Async server-side API for doing server streaming RPCs,
+/// where the outgoing message stream from the server has messages of type \a W.
template <class W>
class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> {
public:
explicit ServerAsyncWriter(ServerContext* ctx)
: call_(nullptr, nullptr, nullptr), ctx_(ctx) {}
+ /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics.
+ ///
+ /// Implicit input parameter:
+ /// - The initial metadata that will be sent to the client from this op will
+ /// be taken from the \a ServerContext associated with the call.
+ ///
+ /// \param[in] tag Tag identifying this request.
void SendInitialMetadata(void* tag) override {
GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_);
@@ -559,6 +737,13 @@
call_.PerformOps(&write_ops_);
}
+ /// See the \a ServerAsyncWriterInterface.WriteAndFinish method for semantics.
+ ///
+ /// Implicit input parameter:
+ /// - the \a ServerContext associated with this call is used
+ /// for sending trailing (and initial) metadata to the client.
+ ///
+ /// Note: \a status must have an OK code.
void WriteAndFinish(const W& msg, WriteOptions options, const Status& status,
void* tag) override {
write_ops_.set_output_tag(tag);
@@ -569,6 +754,14 @@
call_.PerformOps(&write_ops_);
}
+ /// See the \a ServerAsyncWriterInterface.Finish method for semantics.
+ ///
+ /// Implicit input parameter:
+ /// - the \a ServerContext associated with this call is used for sending
+ /// trailing (and initial if not already sent) metadata to the client.
+ ///
+ /// Note: there are no restrictions are the code of
+ /// \a status,it may be non-OK
void Finish(const Status& status, void* tag) override {
finish_ops_.set_output_tag(tag);
EnsureInitialMetadataSent(&finish_ops_);
@@ -606,11 +799,30 @@
public AsyncWriterInterface<W>,
public AsyncReaderInterface<R> {
public:
+ /// Indicate that the stream is to be finished with a certain status code.
+ /// Request notification for when the server has sent the appropriate
+ /// signals to the client to end the call.
+ /// Should not be used concurrently with other operations.
+ ///
+ /// It is appropriate to call this method when either:
+ /// * all messages from the client have been received (either known
+ /// implictly, or explicitly because a previous \a
+ /// AsyncReaderInterface::Read operation
+ /// with a non-ok result (e.g., cq->Next(&read_tag, &ok) filled in 'ok'
+ /// with 'false'.
+ /// * it is desired to end the call early with some non-OK status code.
+ ///
+ /// This operation will end when the server has finished sending out initial
+ /// metadata (if not sent already), response message, and status, or if some
+ /// failure occurred when trying to do so.
+ ///
+ /// \param[in] tag Tag identifying this request.
+ /// \param[in] status To be sent to the client as the result of this call.
virtual void Finish(const Status& status, void* tag) = 0;
/// Request the writing of \a msg and coalesce it with trailing metadata which
- /// contains \a status, using WriteOptions options with identifying tag \a
- /// tag.
+ /// contains \a status, using WriteOptions options with
+ /// identifying tag \a tag.
///
/// WriteAndFinish is equivalent of performing WriteLast and Finish in a
/// single step.
@@ -623,6 +835,10 @@
const Status& status, void* tag) = 0;
};
+/// Async server-side API for doing bidirectional streaming RPCs,
+/// where the incoming message stream coming from the client has messages of
+/// type \a R, and the outgoing message stream coming from the server has
+/// messages of type \a W.
template <class W, class R>
class ServerAsyncReaderWriter final
: public ServerAsyncReaderWriterInterface<W, R> {
@@ -630,6 +846,13 @@
explicit ServerAsyncReaderWriter(ServerContext* ctx)
: call_(nullptr, nullptr, nullptr), ctx_(ctx) {}
+ /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics.
+ ///
+ /// Implicit input parameter:
+ /// - The initial metadata that will be sent to the client from this op will
+ /// be taken from the \a ServerContext associated with the call.
+ ///
+ /// \param[in] tag Tag identifying this request.
void SendInitialMetadata(void* tag) override {
GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_);
@@ -667,6 +890,14 @@
call_.PerformOps(&write_ops_);
}
+ /// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish
+ /// method for semantics.
+ ///
+ /// Implicit input parameter:
+ /// - the \a ServerContext associated with this call is used
+ /// for sending trailing (and initial) metadata to the client.
+ ///
+ /// Note: \a status must have an OK code.
void WriteAndFinish(const W& msg, WriteOptions options, const Status& status,
void* tag) override {
write_ops_.set_output_tag(tag);
@@ -677,6 +908,14 @@
call_.PerformOps(&write_ops_);
}
+ /// See the \a ServerAsyncReaderWriterInterface.Finish method for semantics.
+ ///
+ /// Implicit input parameter:
+ /// - the \a ServerContext associated with this call is used for sending
+ /// trailing (and initial if not already sent) metadata to the client.
+ ///
+ /// Note: there are no restrictions are the code of \a status,
+ /// it may be non-OK
void Finish(const Status& status, void* tag) override {
finish_ops_.set_output_tag(tag);
EnsureInitialMetadataSent(&finish_ops_);
diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h
index a147a6a..aadf77d 100644
--- a/include/grpc++/impl/codegen/async_unary_call.h
+++ b/include/grpc++/impl/codegen/async_unary_call.h
@@ -47,18 +47,49 @@
class CompletionQueue;
extern CoreCodegenInterface* g_core_codegen_interface;
+/// An interface relevant for async client side unary RPCS (which send
+/// one request message to a server and receive one response message).
template <class R>
class ClientAsyncResponseReaderInterface {
public:
virtual ~ClientAsyncResponseReaderInterface() {}
+
+ /// Request notification of the reading of initial metadata. Completion
+ /// will be notified by \a tag on the associated completion queue.
+ /// This call is optional, but if it is used, it cannot be used concurrently
+ /// with or after the \a Finish method.
+ ///
+ /// \param[in] tag Tag identifying this request.
virtual void ReadInitialMetadata(void* tag) = 0;
+
+ /// Request to receive the server's response \a msg and final \a status for
+ /// the call, and to notify \a tag on this call's completion queue when
+ /// finished.
+ ///
+ /// This function will return when either:
+ /// - when the server's response message and status have been received.
+ /// - when the server has returned a non-OK status (no message expected in
+ /// this case).
+ /// - when the call failed for some reason and the library generated a
+ /// non-OK status.
+ ///
+ /// \param[in] tag Tag identifying this request.
+ /// \param[out] status To be updated with the operation status.
+ /// \param[out] msg To be filled in with the server's response message.
virtual void Finish(R* msg, Status* status, void* tag) = 0;
};
+/// Async API for client-side unary RPCs, where the message response
+/// received from the server is of type \a R.
template <class R>
class ClientAsyncResponseReader final
: public ClientAsyncResponseReaderInterface<R> {
public:
+ /// Start a call and write the request out.
+ /// \a tag will be notified on \a cq when the call has been started (i.e.
+ /// intitial metadata sent) and \a request has been written out.
+ /// Note that \a context will be used to fill in custom initial metadata
+ /// used to send to the server when starting the call.
template <class W>
static ClientAsyncResponseReader* Create(ChannelInterface* channel,
CompletionQueue* cq,
@@ -76,6 +107,12 @@
assert(size == sizeof(ClientAsyncResponseReader));
}
+ /// See \a ClientAsyncResponseReaderInterface::ReadInitialMetadata for
+ /// semantics.
+ ///
+ /// Side effect:
+ /// - the \a ClientContext associated with this call is updated with
+ /// possible initial and trailing metadata sent from the serve.
void ReadInitialMetadata(void* tag) {
GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_);
@@ -84,6 +121,11 @@
call_.PerformOps(&meta_buf_);
}
+ /// See \a ClientAysncResponseReaderInterface::Finish for semantics.
+ ///
+ /// Side effect:
+ /// - the \a ClientContext associated with this call is updated with
+ /// possible initial and trailing metadata sent from the server.
void Finish(R* msg, Status* status, void* tag) {
finish_buf_.set_output_tag(tag);
if (!context_->initial_metadata_received_) {
@@ -123,12 +165,21 @@
finish_buf_;
};
+/// Async server-side API for handling unary calls, where the single
+/// response message sent to the client is of type \a W.
template <class W>
class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface {
public:
explicit ServerAsyncResponseWriter(ServerContext* ctx)
: call_(nullptr, nullptr, nullptr), ctx_(ctx) {}
+ /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics.
+ ///
+ /// Side effect:
+ /// The initial metadata that will be sent to the client from this op will
+ /// be taken from the \a ServerContext associated with the call.
+ ///
+ /// \param[in] tag Tag identifying this request.
void SendInitialMetadata(void* tag) override {
GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_);
@@ -142,6 +193,21 @@
call_.PerformOps(&meta_buf_);
}
+ /// Indicate that the stream is to be finished and request notification
+ /// when the server has sent the appropriate signals to the client to
+ /// end the call. Should not be used concurrently with other operations.
+ ///
+ /// \param[in] tag Tag identifying this request.
+ /// \param[in] status To be sent to the client as the result of the call.
+ /// \param[in] msg Message to be sent to the client.
+ ///
+ /// Side effect:
+ /// - also sends initial metadata if not already sent (using the
+ /// \a ServerContext associated with this call).
+ ///
+ /// Note: if \a status has a non-OK code, then \a msg will not be sent,
+ /// and the client will receive only the status with possible trailing
+ /// metadata.
void Finish(const W& msg, const Status& status, void* tag) {
finish_buf_.set_output_tag(tag);
if (!ctx_->sent_initial_metadata_) {
@@ -162,6 +228,18 @@
call_.PerformOps(&finish_buf_);
}
+ /// Indicate that the stream is to be finished with a non-OK status,
+ /// and request notification for when the server has finished sending the
+ /// appropriate signals to the client to end the call.
+ /// Should not be used concurrently with other operations.
+ ///
+ /// \param[in] tag Tag identifying this request.
+ /// \param[in] status To be sent to the client as the result of the call.
+ /// - Note: \a status must have a non-OK code.
+ ///
+ /// Side effect:
+ /// - also sends initial metadata if not already sent (using the
+ /// \a ServerContext associated with this call).
void FinishWithError(const Status& status, void* tag) {
GPR_CODEGEN_ASSERT(!status.ok());
finish_buf_.set_output_tag(tag);
diff --git a/include/grpc++/impl/codegen/call.h b/include/grpc++/impl/codegen/call.h
index 9fe2bbb..bbd0fc2 100644
--- a/include/grpc++/impl/codegen/call.h
+++ b/include/grpc++/impl/codegen/call.h
@@ -634,10 +634,10 @@
}
};
-// Straightforward wrapping of the C call object
+/// Straightforward wrapping of the C call object
class Call final {
public:
- /* call is owned by the caller */
+ /** call is owned by the caller */
Call(grpc_call* call, CallHook* call_hook, CompletionQueue* cq)
: call_hook_(call_hook),
cq_(cq),
diff --git a/include/grpc++/impl/codegen/call_hook.h b/include/grpc++/impl/codegen/call_hook.h
index 6a82582..85a5f86 100644
--- a/include/grpc++/impl/codegen/call_hook.h
+++ b/include/grpc++/impl/codegen/call_hook.h
@@ -39,7 +39,8 @@
class CallOpSetInterface;
class Call;
-/// Channel and Server implement this to allow them to hook performing ops
+/// This is an interface that Channel and Server implement to allow them to hook
+/// performing ops.
class CallHook {
public:
virtual ~CallHook() {}
diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h
index 3c50e6b..b1b9be0 100644
--- a/include/grpc++/impl/codegen/client_context.h
+++ b/include/grpc++/impl/codegen/client_context.h
@@ -151,6 +151,20 @@
class InteropClientContextInspector;
} // namespace testing
+/// A ClientContext allows the person implementing a service client to:
+///
+/// - Add custom metadata key-value pairs that will propagated to the server
+/// side.
+/// - Control call settings such as compression and authentication.
+/// - Initial and trailing metadata coming from the server.
+/// - Get performance metrics (ie, census).
+///
+/// Context settings are only relevant to the call they are invoked with, that
+/// is to say, they aren't sticky. Some of these settings, such as the
+/// compression options, can be made persistant at channel construction time
+/// (see \a grpc::CreateCustomChannel).
+///
+/// \warning ClientContext instances should \em not be reused across rpcs.
class ClientContext {
public:
ClientContext();
@@ -178,9 +192,8 @@
///
/// \param meta_key The metadata key. If \a meta_value is binary data, it must
/// end in "-bin".
- /// \param meta_value The metadata value. If its value is binary, it must be
- /// base64-encoding (see https://tools.ietf.org/html/rfc4648#section-4) and \a
- /// meta_key must end in "-bin".
+ /// \param meta_value The metadata value. If its value is binary, the key name
+ /// must end in "-bin".
void AddMetadata(const grpc::string& meta_key,
const grpc::string& meta_value);
@@ -222,13 +235,24 @@
deadline_ = deadline_tp.raw_time();
}
- /// EXPERIMENTAL: Set this request to be idempotent
+ /// EXPERIMENTAL: Indicate that this request is idempotent.
+ /// By default, RPCs are assumed to <i>not</i> be idempotent.
+ ///
+ /// If true, the gRPC library assumes that it's safe to initiate
+ /// this RPC multiple times.
void set_idempotent(bool idempotent) { idempotent_ = idempotent; }
- /// EXPERIMENTAL: Set this request to be cacheable
+ /// EXPERIMENTAL: Set this request to be cacheable.
+ /// If set, grpc is free to use the HTTP GET verb for sending the request,
+ /// with the possibility of receiving a cached respone.
void set_cacheable(bool cacheable) { cacheable_ = cacheable; }
- /// EXPERIMENTAL: Trigger wait-for-ready or not on this request
+ /// EXPERIMENTAL: Trigger wait-for-ready or not on this request.
+ /// See https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md.
+ /// If set, if an RPC is made when a channel's connectivity state is
+ /// TRANSIENT_FAILURE or CONNECTING, the call will not "fail fast",
+ /// and the channel will wait until the channel is READY before making the
+ /// call.
void set_wait_for_ready(bool wait_for_ready) {
wait_for_ready_ = wait_for_ready;
wait_for_ready_explicitly_set_ = true;
@@ -325,8 +349,8 @@
};
static void SetGlobalCallbacks(GlobalCallbacks* callbacks);
- // Should be used for framework-level extensions only.
- // Applications never need to call this method.
+ /// Should be used for framework-level extensions only.
+ /// Applications never need to call this method.
grpc_call* c_call() { return call_; }
private:
diff --git a/include/grpc++/impl/codegen/client_unary_call.h b/include/grpc++/impl/codegen/client_unary_call.h
index 4bf35ae..b923498 100644
--- a/include/grpc++/impl/codegen/client_unary_call.h
+++ b/include/grpc++/impl/codegen/client_unary_call.h
@@ -47,7 +47,7 @@
class CompletionQueue;
class RpcMethod;
-// Wrapper that performs a blocking unary call
+/// Wrapper that performs a blocking unary call
template <class InputMessage, class OutputMessage>
Status BlockingUnaryCall(ChannelInterface* channel, const RpcMethod& method,
ClientContext* context, const InputMessage& request,
diff --git a/include/grpc++/impl/codegen/completion_queue.h b/include/grpc++/impl/codegen/completion_queue.h
index c8ab726..57333d7 100644
--- a/include/grpc++/impl/codegen/completion_queue.h
+++ b/include/grpc++/impl/codegen/completion_queue.h
@@ -159,7 +159,8 @@
/// will start to return false and \a AsyncNext will return \a
/// NextStatus::SHUTDOWN. Only once either one of these methods does that
/// (that is, once the queue has been \em drained) can an instance of this
- /// class be destroyed.
+ /// class be destroyed. Also note that applications must ensure that
+ /// no work is enqueued on this completion queue after this method is called.
void Shutdown();
/// Returns a \em raw pointer to the underlying \a grpc_completion_queue
diff --git a/include/grpc++/impl/codegen/completion_queue_tag.h b/include/grpc++/impl/codegen/completion_queue_tag.h
index 19a0850..0affc81 100644
--- a/include/grpc++/impl/codegen/completion_queue_tag.h
+++ b/include/grpc++/impl/codegen/completion_queue_tag.h
@@ -40,10 +40,10 @@
class CompletionQueueTag {
public:
virtual ~CompletionQueueTag() {}
- // Called prior to returning from Next(), return value is the status of the
- // operation (return status is the default thing to do). If this function
- // returns false, the tag is dropped and not returned from the completion
- // queue
+ /// Called prior to returning from Next(), return value is the status of the
+ /// operation (return status is the default thing to do). If this function
+ /// returns false, the tag is dropped and not returned from the completion
+ /// queue
virtual bool FinalizeResult(void** tag, bool* status) = 0;
};
diff --git a/include/grpc++/impl/codegen/config.h b/include/grpc++/impl/codegen/config.h
index a43bf65..79352ee 100644
--- a/include/grpc++/impl/codegen/config.h
+++ b/include/grpc++/impl/codegen/config.h
@@ -39,9 +39,9 @@
#define GRPC_CUSTOM_STRING std::string
#endif
-// The following macros are deprecated and appear only for users
-// with PB files generated using gRPC 1.0.x plugins. They should
-// not be used in new code
+/// The following macros are deprecated and appear only for users
+/// with PB files generated using gRPC 1.0.x plugins. They should
+/// not be used in new code
#define GRPC_OVERRIDE override // deprecated
#define GRPC_FINAL final // deprecated
diff --git a/include/grpc++/impl/codegen/method_handler_impl.h b/include/grpc++/impl/codegen/method_handler_impl.h
index 83b569c..8dfaf58 100644
--- a/include/grpc++/impl/codegen/method_handler_impl.h
+++ b/include/grpc++/impl/codegen/method_handler_impl.h
@@ -40,7 +40,7 @@
namespace grpc {
-// A wrapper class of an application provided rpc method handler.
+/// A wrapper class of an application provided rpc method handler.
template <class ServiceType, class RequestType, class ResponseType>
class RpcMethodHandler : public MethodHandler {
public:
@@ -77,7 +77,7 @@
}
private:
- // Application provided rpc handler function.
+ /// Application provided rpc handler function.
std::function<Status(ServiceType*, ServerContext*, const RequestType*,
ResponseType*)>
func_;
@@ -85,7 +85,7 @@
ServiceType* service_;
};
-// A wrapper class of an application provided client streaming handler.
+/// A wrapper class of an application provided client streaming handler.
template <class ServiceType, class RequestType, class ResponseType>
class ClientStreamingHandler : public MethodHandler {
public:
@@ -125,7 +125,7 @@
ServiceType* service_;
};
-// A wrapper class of an application provided server streaming handler.
+/// A wrapper class of an application provided server streaming handler.
template <class ServiceType, class RequestType, class ResponseType>
class ServerStreamingHandler : public MethodHandler {
public:
@@ -166,13 +166,13 @@
ServiceType* service_;
};
-// A wrapper class of an application provided bidi-streaming handler.
-// This also applies to server-streamed implementation of a unary method
-// with the additional requirement that such methods must have done a
-// write for status to be ok
-// Since this is used by more than 1 class, the service is not passed in.
-// Instead, it is expected to be an implicitly-captured argument of func
-// (through bind or something along those lines)
+/// A wrapper class of an application provided bidi-streaming handler.
+/// This also applies to server-streamed implementation of a unary method
+/// with the additional requirement that such methods must have done a
+/// write for status to be ok
+/// Since this is used by more than 1 class, the service is not passed in.
+/// Instead, it is expected to be an implicitly-captured argument of func
+/// (through bind or something along those lines)
template <class Streamer, bool WriteNeeded>
class TemplatedBidiStreamingHandler : public MethodHandler {
public:
@@ -249,7 +249,7 @@
ServerSplitStreamer<RequestType, ResponseType>, false>(func) {}
};
-// Handle unknown method by returning UNIMPLEMENTED error.
+/// Handle unknown method by returning UNIMPLEMENTED error.
class UnknownMethodHandler : public MethodHandler {
public:
template <class T>
diff --git a/include/grpc++/impl/codegen/rpc_method.h b/include/grpc++/impl/codegen/rpc_method.h
index 4897428..ca75275 100644
--- a/include/grpc++/impl/codegen/rpc_method.h
+++ b/include/grpc++/impl/codegen/rpc_method.h
@@ -40,6 +40,7 @@
namespace grpc {
+/// Descriptor of an RPC method
class RpcMethod {
public:
enum RpcType {
diff --git a/include/grpc++/impl/codegen/rpc_service_method.h b/include/grpc++/impl/codegen/rpc_service_method.h
index eb8f9a1..96bb739 100644
--- a/include/grpc++/impl/codegen/rpc_service_method.h
+++ b/include/grpc++/impl/codegen/rpc_service_method.h
@@ -52,7 +52,7 @@
class ServerContext;
class StreamContextInterface;
-// Base class for running an RPC handler.
+/// Base class for running an RPC handler.
class MethodHandler {
public:
virtual ~MethodHandler() {}
@@ -67,17 +67,17 @@
virtual void RunHandler(const HandlerParameter& param) = 0;
};
-// Server side rpc method class
+/// Server side rpc method class
class RpcServiceMethod : public RpcMethod {
public:
- // Takes ownership of the handler
+ /// Takes ownership of the handler
RpcServiceMethod(const char* name, RpcMethod::RpcType type,
MethodHandler* handler)
: RpcMethod(name, type), server_tag_(nullptr), handler_(handler) {}
void set_server_tag(void* tag) { server_tag_ = tag; }
void* server_tag() const { return server_tag_; }
- // if MethodHandler is nullptr, then this is an async method
+ /// if MethodHandler is nullptr, then this is an async method
MethodHandler* handler() const { return handler_.get(); }
void ResetHandler() { handler_.reset(); }
void SetHandler(MethodHandler* handler) { handler_.reset(handler); }
diff --git a/include/grpc++/impl/codegen/security/auth_context.h b/include/grpc++/impl/codegen/security/auth_context.h
index 75f2482..e83877b 100644
--- a/include/grpc++/impl/codegen/security/auth_context.h
+++ b/include/grpc++/impl/codegen/security/auth_context.h
@@ -99,7 +99,7 @@
virtual AuthPropertyIterator begin() const = 0;
virtual AuthPropertyIterator end() const = 0;
- // Mutation functions: should only be used by an AuthMetadataProcessor.
+ /// Mutation functions: should only be used by an AuthMetadataProcessor.
virtual void AddProperty(const grpc::string& key,
const grpc::string_ref& value) = 0;
virtual bool SetPeerIdentityPropertyName(const grpc::string& name) = 0;
diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h
index ada304d..48967c2 100644
--- a/include/grpc++/impl/codegen/server_context.h
+++ b/include/grpc++/impl/codegen/server_context.h
@@ -91,63 +91,128 @@
class ServerContextTestSpouse;
} // namespace testing
-// Interface of server side rpc context.
+/// A ServerContext allows the person implementing a service handler to:
+///
+/// - Add custom initial and trailing metadata key-value pairs that will
+/// propagated to the client side.
+/// - Control call settings such as compression and authentication.
+/// - Access metadata coming from the client.
+/// - Get performance metrics (ie, census).
+///
+/// Context settings are only relevant to the call handler they are supplied to,
+/// that is to say, they aren't sticky across multiple calls. Some of these
+/// settings, such as the compression options, can be made persistant at server
+/// construction time by specifying the approriate \a ChannelArguments
+/// to a \a grpc::ServerBuilder, via \a ServerBuilder::AddChannelArgument.
+///
+/// \warning ServerContext instances should \em not be reused across rpcs.
class ServerContext {
public:
ServerContext(); // for async calls
~ServerContext();
+ /// Return the deadline for the server call.
std::chrono::system_clock::time_point deadline() const {
return Timespec2Timepoint(deadline_);
}
+ /// Return a \a gpr_timespec representation of the server call's deadline.
gpr_timespec raw_deadline() const { return deadline_; }
+ /// Add the (\a meta_key, \a meta_value) pair to the initial metadata
+ /// associated with a server call. These are made available at the client side
+ /// by the \a grpc::ClientContext::GetServerInitialMetadata() method.
+ ///
+ /// \warning This method should only be called before sending initial metadata
+ /// to the client (which can happen explicitly, or implicitly when sending a
+ /// a response message or status to the client).
+ ///
+ /// \param meta_key The metadata key. If \a meta_value is binary data, it must
+ /// end in "-bin".
+ /// \param meta_value The metadata value. If its value is binary, the key name
+ /// must end in "-bin".
void AddInitialMetadata(const grpc::string& key, const grpc::string& value);
+
+ /// Add the (\a meta_key, \a meta_value) pair to the initial metadata
+ /// associated with a server call. These are made available at the client
+ /// side by the \a grpc::ClientContext::GetServerTrailingMetadata() method.
+ ///
+ /// \warning This method should only be called before sending trailing
+ /// metadata to the client (which happens when the call is finished and a
+ /// status is sent to the client).
+ ///
+ /// \param meta_key The metadata key. If \a meta_value is binary data,
+ /// it must end in "-bin".
+ /// \param meta_value The metadata value. If its value is binary, the key name
+ /// must end in "-bin".
void AddTrailingMetadata(const grpc::string& key, const grpc::string& value);
- // IsCancelled is always safe to call when using sync API
- // When using async API, it is only safe to call IsCancelled after
- // the AsyncNotifyWhenDone tag has been delivered
+ /// IsCancelled is always safe to call when using sync API.
+ /// When using async API, it is only safe to call IsCancelled after
+ /// the AsyncNotifyWhenDone tag has been delivered.
bool IsCancelled() const;
- // Cancel the Call from the server. This is a best-effort API and depending on
- // when it is called, the RPC may still appear successful to the client.
- // For example, if TryCancel() is called on a separate thread, it might race
- // with the server handler which might return success to the client before
- // TryCancel() was even started by the thread.
- //
- // It is the caller's responsibility to prevent such races and ensure that if
- // TryCancel() is called, the serverhandler must return Status::CANCELLED. The
- // only exception is that if the serverhandler is already returning an error
- // status code, it is ok to not return Status::CANCELLED even if TryCancel()
- // was called.
+ /// Cancel the Call from the server. This is a best-effort API and
+ /// depending on when it is called, the RPC may still appear successful to
+ /// the client.
+ /// For example, if TryCancel() is called on a separate thread, it might race
+ /// with the server handler which might return success to the client before
+ /// TryCancel() was even started by the thread.
+ ///
+ /// It is the caller's responsibility to prevent such races and ensure that if
+ /// TryCancel() is called, the serverhandler must return Status::CANCELLED.
+ /// The only exception is that if the serverhandler is already returning an
+ /// error status code, it is ok to not return Status::CANCELLED even if
+ /// TryCancel() was called.
void TryCancel() const;
+ /// Return a collection of initial metadata key-value pairs sent from the
+ /// client. Note that keys may happen more than
+ /// once (ie, a \a std::multimap is returned).
+ ///
+ /// It is safe to use this method after initial metadata has been received,
+ /// Calls always begin with the client sending initial metadata, so this is
+ /// safe to access as soon as the call has begun on the server side.
+ ///
+ /// \return A multimap of initial metadata key-value pairs from the server.
const std::multimap<grpc::string_ref, grpc::string_ref>& client_metadata()
const {
return *client_metadata_.map();
}
+ /// Return the compression algorithm to be used by the server call.
grpc_compression_level compression_level() const {
return compression_level_;
}
+ /// Set \a algorithm to be the compression algorithm used for the server call.
+ ///
+ /// \param algorithm The compression algorithm used for the server call.
void set_compression_level(grpc_compression_level level) {
compression_level_set_ = true;
compression_level_ = level;
}
+ /// Return a bool indicating whether the compression level for this call
+ /// has been set (either implicitly or through a previous call to
+ /// \a set_compression_level.
bool compression_level_set() const { return compression_level_set_; }
+ /// Return the compression algorithm to be used by the server call.
grpc_compression_algorithm compression_algorithm() const {
return compression_algorithm_;
}
+ /// Set \a algorithm to be the compression algorithm used for the server call.
+ ///
+ /// \param algorithm The compression algorithm used for the server call.
void set_compression_algorithm(grpc_compression_algorithm algorithm);
- // Set the load reporting costs in \a cost_data for the call.
+ /// Set the load reporting costs in \a cost_data for the call.
void SetLoadReportingCosts(const std::vector<grpc::string>& cost_data);
+ /// Return the authentication context for this server call.
+ ///
+ /// \see grpc::AuthContext.
std::shared_ptr<const AuthContext> auth_context() const {
if (auth_context_.get() == nullptr) {
auth_context_ = CreateAuthContext(call_);
@@ -155,24 +220,25 @@
return auth_context_;
}
- // Return the peer uri in a string.
- // WARNING: this value is never authenticated or subject to any security
- // related code. It must not be used for any authentication related
- // functionality. Instead, use auth_context.
+ /// Return the peer uri in a string.
+ /// WARNING: this value is never authenticated or subject to any security
+ /// related code. It must not be used for any authentication related
+ /// functionality. Instead, use auth_context.
grpc::string peer() const;
+ /// Get the census context associated with this server call.
const struct census_context* census_context() const;
- // Async only. Has to be called before the rpc starts.
- // Returns the tag in completion queue when the rpc finishes.
- // IsCancelled() can then be called to check whether the rpc was cancelled.
+ /// Async only. Has to be called before the rpc starts.
+ /// Returns the tag in completion queue when the rpc finishes.
+ /// IsCancelled() can then be called to check whether the rpc was cancelled.
void AsyncNotifyWhenDone(void* tag) {
has_notify_when_done_tag_ = true;
async_notify_when_done_tag_ = tag;
}
- // Should be used for framework-level extensions only.
- // Applications never need to call this method.
+ /// Should be used for framework-level extensions only.
+ /// Applications never need to call this method.
grpc_call* c_call() { return call_; }
private:
@@ -205,14 +271,14 @@
friend class UnknownMethodHandler;
friend class ::grpc::ClientContext;
- // Prevent copying.
+ /// Prevent copying.
ServerContext(const ServerContext&);
ServerContext& operator=(const ServerContext&);
class CompletionOp;
void BeginCompletionOp(Call* call);
- // Return the tag queued by BeginCompletionOp()
+ /// Return the tag queued by BeginCompletionOp()
CompletionQueueTag* GetCompletionOpTag();
ServerContext(gpr_timespec deadline, grpc_metadata_array* arr);
diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h
index bd65ea0..b880191 100644
--- a/include/grpc++/impl/codegen/service_type.h
+++ b/include/grpc++/impl/codegen/service_type.h
@@ -54,6 +54,12 @@
public:
virtual ~ServerAsyncStreamingInterface() {}
+ /// Request notification of the sending of initial metadata to the client.
+ /// Completion will be notified by \a tag on the associated completion
+ /// queue. This call is optional, but if it is used, it cannot be used
+ /// concurrently with or after the \a Finish method.
+ ///
+ /// \param[in] tag Tag identifying this request.
virtual void SendInitialMetadata(void* tag) = 0;
private:
@@ -61,6 +67,7 @@
virtual void BindCall(Call* call) = 0;
};
+/// Desriptor of an RPC service and its various RPC methods
class Service {
public:
Service() : server_(nullptr) {}
@@ -155,7 +162,7 @@
// From the server's point of view, streamed unary is a special
// case of BIDI_STREAMING that has 1 read and 1 write, in that order,
// and split server-side streaming is BIDI_STREAMING with 1 read and
- // any number of writes, in that order
+ // any number of writes, in that order.
methods_[index]->SetMethodType(::grpc::RpcMethod::BIDI_STREAMING);
}
diff --git a/include/grpc++/impl/codegen/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h
index 9a90a18..c3d27fa 100644
--- a/include/grpc++/impl/codegen/status_code_enum.h
+++ b/include/grpc++/impl/codegen/status_code_enum.h
@@ -136,6 +136,11 @@
/// The service is currently unavailable. This is a most likely a transient
/// condition and may be corrected by retrying with a backoff.
///
+ /// \warning Although data MIGHT not have been transmitted when this
+ /// status occurs, there is NOT A GUARANTEE that the server has not seen
+ /// anything. So in general it is unsafe to retry on this status code
+ /// if the call is non-idempotent.
+ ///
/// See litmus test above for deciding between FAILED_PRECONDITION, ABORTED,
/// and UNAVAILABLE.
UNAVAILABLE = 14,
diff --git a/include/grpc++/impl/codegen/string_ref.h b/include/grpc++/impl/codegen/string_ref.h
index 0037938..4ed11b1 100644
--- a/include/grpc++/impl/codegen/string_ref.h
+++ b/include/grpc++/impl/codegen/string_ref.h
@@ -55,14 +55,14 @@
/// compatibility.
class string_ref {
public:
- // types
+ /// types
typedef const char* const_iterator;
typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
- // constants
+ /// constants
const static size_t npos;
- // construct/copy.
+ /// construct/copy.
string_ref() : data_(nullptr), length_(0) {}
string_ref(const string_ref& other)
: data_(other.data_), length_(other.length_) {}
@@ -76,7 +76,7 @@
string_ref(const char* s, size_t l) : data_(s), length_(l) {}
string_ref(const grpc::string& s) : data_(s.data()), length_(s.length()) {}
- // iterators
+ /// iterators
const_iterator begin() const { return data_; }
const_iterator end() const { return data_ + length_; }
const_iterator cbegin() const { return data_; }
@@ -94,16 +94,16 @@
return const_reverse_iterator(begin());
}
- // capacity
+ /// capacity
size_t size() const { return length_; }
size_t length() const { return length_; }
size_t max_size() const { return length_; }
bool empty() const { return length_ == 0; }
- // element access
+ /// element access
const char* data() const { return data_; }
- // string operations
+ /// string operations
int compare(string_ref x) const {
size_t min_size = length_ < x.length_ ? length_ : x.length_;
int r = memcmp(data_, x.data_, min_size);
@@ -144,7 +144,7 @@
size_t length_;
};
-// Comparison operators
+/// Comparison operators
inline bool operator==(string_ref x, string_ref y) { return x.compare(y) == 0; }
inline bool operator!=(string_ref x, string_ref y) { return x.compare(y) != 0; }
inline bool operator<(string_ref x, string_ref y) { return x.compare(y) < 0; }
diff --git a/include/grpc++/impl/codegen/stub_options.h b/include/grpc++/impl/codegen/stub_options.h
index 8e966a8..41aef19 100644
--- a/include/grpc++/impl/codegen/stub_options.h
+++ b/include/grpc++/impl/codegen/stub_options.h
@@ -36,6 +36,7 @@
namespace grpc {
+/// Useful interface for generated stubs
class StubOptions {};
} // namespace grpc
diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h
index a010924..db9048d 100644
--- a/include/grpc++/impl/codegen/sync_stream.h
+++ b/include/grpc++/impl/codegen/sync_stream.h
@@ -50,16 +50,30 @@
public:
virtual ~ClientStreamingInterface() {}
- /// Wait until the stream finishes, and return the final status. When the
- /// client side declares it has no more message to send, either implicitly or
- /// by calling \a WritesDone(), it needs to make sure there is no more message
- /// to be received from the server, either implicitly or by getting a false
- /// from a \a Read().
+ /// Block waiting until the stream finishes and a final status of the call is
+ /// available.
+ ///
+ /// It is appropriate to call this method when both:
+ /// * the calling code (client-side) has no more message to send
+ /// (this can be declared implicitly by calling this method, or
+ /// explicitly through an earlier call to <i>WritesDone</i> method of the
+ /// class in use, e.g. \a ClientWriterInterface::WritesDone or
+ /// \a ClientReaderWriterInterface::WritesDone).
+ /// * there are no more messages to be received from the server (which can
+ /// be known implicitly, or explicitly from an earlier call to \a
+ /// ReaderInterface::Read that returned "false").
///
/// This function will return either:
- /// - when all incoming messages have been read and the server has returned
+ /// - when all incoming messages have been read and the server has
+ /// returned status.
+ /// - when the server has returned a non-OK status.
+ /// - OR when the call failed for some reason and the library generated a
/// status.
- /// - OR when the server has returned a non-OK status.
+ ///
+ /// Return values:
+ /// - \a Status contains the status code, message and details for the call
+ /// - the \a ClientContext associated with this call is updated with
+ /// possible trailing metadata sent from the server.
virtual Status Finish() = 0;
};
@@ -68,7 +82,12 @@
public:
virtual ~ServerStreamingInterface() {}
- /// Blocking send initial metadata to client.
+ /// Block to send initial metadata to client.
+ /// This call is optional, but if it is used, it cannot be used concurrently
+ /// with or after the \a Finish method.
+ ///
+ /// The initial metadata that will be sent to the client will be
+ /// taken from the \a ServerContext associated with the call.
virtual void SendInitialMetadata() = 0;
};
@@ -78,10 +97,11 @@
public:
virtual ~ReaderInterface() {}
- /// Upper bound on the next message size available for reading on this stream
+ /// Get an upper bound on the next message size available for reading on this
+ /// stream.
virtual bool NextMessageSize(uint32_t* sz) = 0;
- /// Blocking read a message and parse to \a msg. Returns \a true on success.
+ /// Block to read a message and parse to \a msg. Returns \a true on success.
/// This is thread-safe with respect to \a Write or \WritesDone methods on
/// the same stream. It should not be called concurrently with another \a
/// Read on the same stream as the order of delivery will not be defined.
@@ -100,8 +120,8 @@
public:
virtual ~WriterInterface() {}
- /// Blocking write \a msg to the stream with WriteOptions \a options.
- /// This is thread-safe with respect to \a Read
+ /// Block to write \a msg to the stream with WriteOptions \a options.
+ /// This is thread-safe with respect to \a ReaderInterface::Read
///
/// \param msg The message to be written to the stream.
/// \param options The WriteOptions affecting the write operation.
@@ -109,8 +129,8 @@
/// \return \a true on success, \a false when the stream has been closed.
virtual bool Write(const W& msg, WriteOptions options) = 0;
- /// Blocking write \a msg to the stream with default write options.
- /// This is thread-safe with respect to \a Read
+ /// Block to write \a msg to the stream with default write options.
+ /// This is thread-safe with respect to \a ReaderInterface::Read
///
/// \param msg The message to be written to the stream.
///
@@ -122,12 +142,12 @@
///
/// For client, WriteLast is equivalent of performing Write and WritesDone in
/// a single step. \a msg and trailing metadata are coalesced and sent on wire
- /// by calling this function.
- /// For server, WriteLast buffers the \a msg. The writing of \a msg is held
- /// until the service handler returns, where \a msg and trailing metadata are
- /// coalesced and sent on wire. Note that WriteLast can only buffer \a msg up
- /// to the flow control window size. If \a msg size is larger than the window
- /// size, it will be sent on wire without buffering.
+ /// by calling this function. For server, WriteLast buffers the \a msg.
+ /// The writing of \a msg is held until the service handler returns,
+ /// where \a msg and trailing metadata are coalesced and sent on wire.
+ /// Note that WriteLast can only buffer \a msg up to the flow control window
+ /// size. If \a msg size is larger than the window size, it will be sent on
+ /// wire without buffering.
///
/// \param[in] msg The message to be written to the stream.
/// \param[in] options The WriteOptions to be used to write this message.
@@ -141,17 +161,22 @@
class ClientReaderInterface : public ClientStreamingInterface,
public ReaderInterface<R> {
public:
- /// Blocking wait for initial metadata from server. The received metadata
+ /// Block to wait for initial metadata from server. The received metadata
/// can only be accessed after this call returns. Should only be called before
/// the first read. Calling this method is optional, and if it is not called
/// the metadata will be available in ClientContext after the first read.
virtual void WaitForInitialMetadata() = 0;
};
+/// Synchronous (blocking) client-side API for doing server-streaming RPCs,
+/// where the stream of messages coming from the server has messages
+/// of type \a R.
template <class R>
class ClientReader final : public ClientReaderInterface<R> {
public:
- /// Blocking create a stream and write the first request out.
+ /// Block to create a stream and write the initial metadata and \a request
+ /// out. Note that \a context will be used to fill in custom initial
+ /// metadata used to send to the server when starting the call.
template <class W>
ClientReader(ChannelInterface* channel, const RpcMethod& method,
ClientContext* context, const W& request)
@@ -172,6 +197,13 @@
cq_.Pluck(&ops);
}
+ /// See the \a ClientStreamingInterface.WaitForInitialMetadata method for
+ /// semantics.
+ ///
+ // Side effect:
+ /// Once complete, the initial metadata read from
+ /// the server will be accessable through the \a ClientContext used to
+ /// construct this object.
void WaitForInitialMetadata() override {
GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_);
@@ -186,6 +218,11 @@
return true;
}
+ /// See the \a ReaderInterface.Read method for semantics.
+ /// Side effect:
+ /// This also receives initial metadata from the server, if not
+ /// already received (if initial metadata is received, it can be then
+ /// accessed through the \a ClientContext associated with this call).
bool Read(R* msg) override {
CallOpSet<CallOpRecvInitialMetadata, CallOpRecvMessage<R>> ops;
if (!context_->initial_metadata_received_) {
@@ -196,6 +233,11 @@
return cq_.Pluck(&ops) && ops.got_message;
}
+ /// See the \a ClientStreamingInterface.Finish method for semantics.
+ ///
+ /// Side effect:
+ /// The \a ClientContext associated with this call is updated with
+ /// possible metadata received from the server.
Status Finish() override {
CallOpSet<CallOpClientRecvStatus> ops;
Status status;
@@ -211,23 +253,31 @@
Call call_;
};
-/// Client-side interface for streaming writes of message of type \a W.
+/// Client-side interface for streaming writes of message type \a W.
template <class W>
class ClientWriterInterface : public ClientStreamingInterface,
public WriterInterface<W> {
public:
- /// Half close writing from the client.
- /// Block until currently-pending writes are completed.
- /// Thread safe with respect to \a Read operations only
+ /// Half close writing from the client. (signal that the stream of messages
+ /// coming from the clinet is complete).
+ /// Blocks until currently-pending writes are completed.
+ /// Thread safe with respect to \a ReaderInterface::Read operations only
///
/// \return Whether the writes were successful.
virtual bool WritesDone() = 0;
};
+/// Synchronous (blocking) client-side API for doing client-streaming RPCs,
+/// where the outgoing message stream coming from the client has messages of
+/// type \a W.
template <class W>
class ClientWriter : public ClientWriterInterface<W> {
public:
- /// Blocking create a stream.
+ /// Block to create a stream (i.e. send request headers and other initial
+ /// metadata to the server). Note that \a context will be used to fill
+ /// in custom initial metadata. \a response will be filled in with the
+ /// single expected response message from the server upon a successful
+ /// call to the \a Finish method of this instance.
template <class R>
ClientWriter(ChannelInterface* channel, const RpcMethod& method,
ClientContext* context, R* response)
@@ -248,6 +298,12 @@
}
}
+ /// See the \a ClientStreamingInterface.WaitForInitialMetadata method for
+ /// semantics.
+ ///
+ // Side effect:
+ /// Once complete, the initial metadata read from the server will be
+ /// accessable through the \a ClientContext used to construct this object.
void WaitForInitialMetadata() {
GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_);
@@ -257,6 +313,12 @@
cq_.Pluck(&ops); // status ignored
}
+ /// See the WriterInterface.Write(const W& msg, WriteOptions options) method
+ /// for semantics.
+ ///
+ /// Side effect:
+ /// Also sends initial metadata if not already sent (using the
+ /// \a ClientContext associated with this call).
using WriterInterface<W>::Write;
bool Write(const W& msg, WriteOptions options) override {
CallOpSet<CallOpSendInitialMetadata, CallOpSendMessage,
@@ -287,7 +349,12 @@
return cq_.Pluck(&ops);
}
- /// Read the final response and wait for the final status.
+ /// See the ClientStreamingInterface.Finish method for semantics.
+ /// Side effects:
+ /// - Also receives initial metadata if not already received.
+ /// - Attempts to fill in the \a response parameter passed
+ /// to the constructor of this instance with the response
+ /// message from the server.
Status Finish() override {
Status status;
if (!context_->initial_metadata_received_) {
@@ -308,29 +375,39 @@
Call call_;
};
-/// Client-side interface for bi-directional streaming.
+/// Client-side interface for bi-directional streaming with
+/// client-to-server stream messages of type \a W and
+/// server-to-client stream messages of type \a R.
template <class W, class R>
class ClientReaderWriterInterface : public ClientStreamingInterface,
public WriterInterface<W>,
public ReaderInterface<R> {
public:
- /// Blocking wait for initial metadata from server. The received metadata
+ /// Block to wait for initial metadata from server. The received metadata
/// can only be accessed after this call returns. Should only be called before
/// the first read. Calling this method is optional, and if it is not called
/// the metadata will be available in ClientContext after the first read.
virtual void WaitForInitialMetadata() = 0;
- /// Block until currently-pending writes are completed.
- /// Thread-safe with respect to \a Read
+ /// Half close writing from the client. (signal that the stream of messages
+ /// coming from the clinet is complete).
+ /// Blocks until currently-pending writes are completed.
+ /// Thread-safe with respect to \a ReaderInterface::Read
///
/// \return Whether the writes were successful.
virtual bool WritesDone() = 0;
};
+/// Synchronous (blocking) client-side API for bi-directional streaming RPCs,
+/// where the outgoing message stream coming from the client has messages of
+/// type \a W, and the incoming messages stream coming from the server has
+/// messages of type \a R.
template <class W, class R>
class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> {
public:
- /// Blocking create a stream.
+ /// Block to create a stream and write the initial metadata and \a request
+ /// out. Note that \a context will be used to fill in custom initial metadata
+ /// used to send to the server when starting the call.
ClientReaderWriter(ChannelInterface* channel, const RpcMethod& method,
ClientContext* context)
: context_(context),
@@ -347,6 +424,12 @@
}
}
+ /// Block waiting to read initial metadata from the server.
+ /// This call is optional, but if it is used, it cannot be used concurrently
+ /// with or after the \a Finish method.
+ ///
+ /// Once complete, the initial metadata read from the server will be
+ /// accessable through the \a ClientContext used to construct this object.
void WaitForInitialMetadata() override {
GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_);
@@ -361,6 +444,10 @@
return true;
}
+ /// See the \a ReaderInterface.Read method for semantics.
+ /// Side effect:
+ /// Also receives initial metadata if not already received (updates the \a
+ /// ClientContext associated with this call in that case).
bool Read(R* msg) override {
CallOpSet<CallOpRecvInitialMetadata, CallOpRecvMessage<R>> ops;
if (!context_->initial_metadata_received_) {
@@ -371,6 +458,11 @@
return cq_.Pluck(&ops) && ops.got_message;
}
+ /// See the \a WriterInterface.Write method for semantics.
+ ///
+ /// Side effect:
+ /// Also sends initial metadata if not already sent (using the
+ /// \a ClientContext associated with this call to fill in values).
using WriterInterface<W>::Write;
bool Write(const W& msg, WriteOptions options) override {
CallOpSet<CallOpSendInitialMetadata, CallOpSendMessage,
@@ -401,6 +493,11 @@
return cq_.Pluck(&ops);
}
+ /// See the ClientStreamingInterface.Finish method for semantics.
+ ///
+ /// Side effect:
+ /// - the \a ClientContext associated with this call is updated with
+ /// possible trailing metadata sent from the server.
Status Finish() override {
CallOpSet<CallOpRecvInitialMetadata, CallOpClientRecvStatus> ops;
if (!context_->initial_metadata_received_) {
@@ -424,11 +521,17 @@
class ServerReaderInterface : public ServerStreamingInterface,
public ReaderInterface<R> {};
+/// Synchronous (blocking) server-side API for doing client-streaming RPCs,
+/// where the incoming message stream coming from the client has messages of
+/// type \a R.
template <class R>
class ServerReader final : public ServerReaderInterface<R> {
public:
ServerReader(Call* call, ServerContext* ctx) : call_(call), ctx_(ctx) {}
+ /// See the \a ServerStreamingInterface.SendInitialMetadata method
+ /// for semantics. Note that initial metadata will be affected by the
+ /// \a ServerContext associated with this call.
void SendInitialMetadata() override {
GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_);
@@ -465,11 +568,18 @@
class ServerWriterInterface : public ServerStreamingInterface,
public WriterInterface<W> {};
+/// Synchronous (blocking) server-side API for doing for doing a
+/// server-streaming RPCs, where the outgoing message stream coming from the
+/// server has messages of type \a W.
template <class W>
class ServerWriter final : public ServerWriterInterface<W> {
public:
ServerWriter(Call* call, ServerContext* ctx) : call_(call), ctx_(ctx) {}
+ /// See the \a ServerStreamingInterface.SendInitialMetadata method
+ /// for semantics.
+ /// Note that initial metadata will be affected by the
+ /// \a ServerContext associated with this call.
void SendInitialMetadata() override {
GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_);
@@ -484,6 +594,11 @@
call_->cq()->Pluck(&ops);
}
+ /// See the \a WriterInterface.Write method for semantics.
+ ///
+ /// Side effect:
+ /// Also sends initial metadata if not already sent (using the
+ /// \a ClientContext associated with this call to fill in values).
using WriterInterface<W>::Write;
bool Write(const W& msg, WriteOptions options) override {
if (options.is_last_message()) {
@@ -516,7 +631,7 @@
public WriterInterface<W>,
public ReaderInterface<R> {};
-// Actual implementation of bi-directional streaming
+/// Actual implementation of bi-directional streaming
namespace internal {
template <class W, class R>
class ServerReaderWriterBody final {
@@ -576,12 +691,18 @@
};
} // namespace internal
-// class to represent the user API for a bidirectional streaming call
+/// Synchronous (blocking) server-side API for a bidirectional
+/// streaming call, where the incoming message stream coming from the client has
+/// messages of type \a R, and the outgoing message streaming coming from
+/// the server has messages of type \a W.
template <class W, class R>
class ServerReaderWriter final : public ServerReaderWriterInterface<W, R> {
public:
ServerReaderWriter(Call* call, ServerContext* ctx) : body_(call, ctx) {}
+ /// See the \a ServerStreamingInterface.SendInitialMetadata method
+ /// for semantics. Note that initial metadata will be affected by the
+ /// \a ServerContext associated with this call.
void SendInitialMetadata() override { body_.SendInitialMetadata(); }
bool NextMessageSize(uint32_t* sz) override {
@@ -590,6 +711,11 @@
bool Read(R* msg) override { return body_.Read(msg); }
+ /// See the \a WriterInterface.Write(const W& msg, WriteOptions options)
+ /// method for semantics.
+ /// Side effect:
+ /// Also sends initial metadata if not already sent (using the \a
+ /// ServerContext associated with this call).
using WriterInterface<W>::Write;
bool Write(const W& msg, WriteOptions options) override {
return body_.Write(msg, options);
@@ -604,8 +730,7 @@
/// through a unary call on the client side, but the server responds to it
/// as though it were a single-ping-pong streaming call. The server can use
/// the \a NextMessageSize method to determine an upper-bound on the size of
-/// the message.
-/// A key difference relative to streaming: ServerUnaryStreamer
+/// the message. A key difference relative to streaming: ServerUnaryStreamer
/// must have exactly 1 Read and exactly 1 Write, in that order, to function
/// correctly. Otherwise, the RPC is in error.
template <class RequestType, class ResponseType>
@@ -615,12 +740,27 @@
ServerUnaryStreamer(Call* call, ServerContext* ctx)
: body_(call, ctx), read_done_(false), write_done_(false) {}
+ /// Block to send initial metadata to client.
+ /// Implicit input parameter:
+ /// - the \a ServerContext associated with this call will be used for
+ /// sending initial metadata.
void SendInitialMetadata() override { body_.SendInitialMetadata(); }
+ /// Get an upper bound on the request message size from the client.
bool NextMessageSize(uint32_t* sz) override {
return body_.NextMessageSize(sz);
}
+ /// Read a message of type \a R into \a msg. Completion will be notified by \a
+ /// tag on the associated completion queue.
+ /// This is thread-safe with respect to \a Write or \a WritesDone methods. It
+ /// should not be called concurrently with other streaming APIs
+ /// on the same stream. It is not meaningful to call it concurrently
+ /// with another \a ReaderInterface::Read on the same stream since reads on
+ /// the same stream are delivered in order.
+ ///
+ /// \param[out] msg Where to eventually store the read message.
+ /// \param[in] tag The tag identifying the operation.
bool Read(RequestType* request) override {
if (read_done_) {
return false;
@@ -629,6 +769,13 @@
return body_.Read(request);
}
+ /// Block to write \a msg to the stream with WriteOptions \a options.
+ /// This is thread-safe with respect to \a ReaderInterface::Read
+ ///
+ /// \param msg The message to be written to the stream.
+ /// \param options The WriteOptions affecting the write operation.
+ ///
+ /// \return \a true on success, \a false when the stream has been closed.
using WriterInterface<ResponseType>::Write;
bool Write(const ResponseType& response, WriteOptions options) override {
if (write_done_ || !read_done_) {
@@ -656,12 +803,27 @@
ServerSplitStreamer(Call* call, ServerContext* ctx)
: body_(call, ctx), read_done_(false) {}
+ /// Block to send initial metadata to client.
+ /// Implicit input parameter:
+ /// - the \a ServerContext associated with this call will be used for
+ /// sending initial metadata.
void SendInitialMetadata() override { body_.SendInitialMetadata(); }
+ /// Get an upper bound on the request message size from the client.
bool NextMessageSize(uint32_t* sz) override {
return body_.NextMessageSize(sz);
}
+ /// Read a message of type \a R into \a msg. Completion will be notified by \a
+ /// tag on the associated completion queue.
+ /// This is thread-safe with respect to \a Write or \a WritesDone methods. It
+ /// should not be called concurrently with other streaming APIs
+ /// on the same stream. It is not meaningful to call it concurrently
+ /// with another \a ReaderInterface::Read on the same stream since reads on
+ /// the same stream are delivered in order.
+ ///
+ /// \param[out] msg Where to eventually store the read message.
+ /// \param[in] tag The tag identifying the operation.
bool Read(RequestType* request) override {
if (read_done_) {
return false;
@@ -670,6 +832,13 @@
return body_.Read(request);
}
+ /// Block to write \a msg to the stream with WriteOptions \a options.
+ /// This is thread-safe with respect to \a ReaderInterface::Read
+ ///
+ /// \param msg The message to be written to the stream.
+ /// \param options The WriteOptions affecting the write operation.
+ ///
+ /// \return \a true on success, \a false when the stream has been closed.
using WriterInterface<ResponseType>::Write;
bool Write(const ResponseType& response, WriteOptions options) override {
return read_done_ && body_.Write(response, options);
diff --git a/include/grpc++/impl/codegen/time.h b/include/grpc++/impl/codegen/time.h
index e090ece..81ca7bb 100644
--- a/include/grpc++/impl/codegen/time.h
+++ b/include/grpc++/impl/codegen/time.h
@@ -39,17 +39,16 @@
namespace grpc {
-/* If you are trying to use CompletionQueue::AsyncNext with a time class that
- isn't either gpr_timespec or std::chrono::system_clock::time_point, you
- will most likely be looking at this comment as your compiler will have
- fired an error below. In order to fix this issue, you have two potential
- solutions:
+/** If you are trying to use CompletionQueue::AsyncNext with a time class that
+ isn't either gpr_timespec or std::chrono::system_clock::time_point, you
+ will most likely be looking at this comment as your compiler will have
+ fired an error below. In order to fix this issue, you have two potential
+ solutions:
- 1. Use gpr_timespec or std::chrono::system_clock::time_point instead
- 2. Specialize the TimePoint class with whichever time class that you
- want to use here. See below for two examples of how to do this.
+ 1. Use gpr_timespec or std::chrono::system_clock::time_point instead
+ 2. Specialize the TimePoint class with whichever time class that you
+ want to use here. See below for two examples of how to do this.
*/
-
template <typename T>
class TimePoint {
public:
diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h
index 61632e3..8f2bce5 100644
--- a/include/grpc++/impl/server_builder_plugin.h
+++ b/include/grpc++/impl/server_builder_plugin.h
@@ -43,24 +43,27 @@
class ServerInitializer;
class ChannelArguments;
+/// This interface is meant for internal usage only. Implementations of this
+/// interface should add themselves to a \a ServerBuilder instance through the
+/// \a InternalAddPluginFactory method.
class ServerBuilderPlugin {
public:
virtual ~ServerBuilderPlugin() {}
virtual grpc::string name() = 0;
- // InitServer will be called in ServerBuilder::BuildAndStart(), after the
- // Server instance is created.
+ /// InitServer will be called in ServerBuilder::BuildAndStart(), after the
+ /// Server instance is created.
virtual void InitServer(ServerInitializer* si) = 0;
- // Finish will be called at the end of ServerBuilder::BuildAndStart().
+ /// Finish will be called at the end of ServerBuilder::BuildAndStart().
virtual void Finish(ServerInitializer* si) = 0;
- // ChangeArguments is an interface that can be used in
- // ServerBuilderOption::UpdatePlugins
+ /// ChangeArguments is an interface that can be used in
+ /// ServerBuilderOption::UpdatePlugins
virtual void ChangeArguments(const grpc::string& name, void* value) = 0;
- // UpdateChannelArguments will be called in ServerBuilder::BuildAndStart(),
- // before the Server instance is created.
+ /// UpdateChannelArguments will be called in ServerBuilder::BuildAndStart(),
+ /// before the Server instance is created.
virtual void UpdateChannelArguments(ChannelArguments* args) {}
virtual bool has_sync_methods() const { return false; }
diff --git a/include/grpc++/resource_quota.h b/include/grpc++/resource_quota.h
index 68a5146..1199ae9 100644
--- a/include/grpc++/resource_quota.h
+++ b/include/grpc++/resource_quota.h
@@ -47,6 +47,7 @@
/// all attached entities below the ResourceQuota bound.
class ResourceQuota final : private GrpcLibraryCodegen {
public:
+ /// \param name - a unique name for this ResourceQuota.
explicit ResourceQuota(const grpc::string& name);
ResourceQuota();
~ResourceQuota();
diff --git a/include/grpc++/security/auth_metadata_processor.h b/include/grpc++/security/auth_metadata_processor.h
index 1ae32d0..3536923 100644
--- a/include/grpc++/security/auth_metadata_processor.h
+++ b/include/grpc++/security/auth_metadata_processor.h
@@ -49,19 +49,19 @@
virtual ~AuthMetadataProcessor() {}
- // If this method returns true, the Process function will be scheduled in
- // a different thread from the one processing the call.
+ /// If this method returns true, the Process function will be scheduled in
+ /// a different thread from the one processing the call.
virtual bool IsBlocking() const { return true; }
- // context is read/write: it contains the properties of the channel peer and
- // it is the job of the Process method to augment it with properties derived
- // from the passed-in auth_metadata.
- // consumed_auth_metadata needs to be filled with metadata that has been
- // consumed by the processor and will be removed from the call.
- // response_metadata is the metadata that will be sent as part of the
- // response.
- // If the return value is not Status::OK, the rpc call will be aborted with
- // the error code and error message sent back to the client.
+ /// context is read/write: it contains the properties of the channel peer and
+ /// it is the job of the Process method to augment it with properties derived
+ /// from the passed-in auth_metadata.
+ /// consumed_auth_metadata needs to be filled with metadata that has been
+ /// consumed by the processor and will be removed from the call.
+ /// response_metadata is the metadata that will be sent as part of the
+ /// response.
+ /// If the return value is not Status::OK, the rpc call will be aborted with
+ /// the error code and error message sent back to the client.
virtual Status Process(const InputMetadata& auth_metadata,
AuthContext* context,
OutputMetadata* consumed_auth_metadata,
diff --git a/include/grpc++/security/credentials.h b/include/grpc++/security/credentials.h
index 59861b7..8d9d181 100644
--- a/include/grpc++/security/credentials.h
+++ b/include/grpc++/security/credentials.h
@@ -204,23 +204,23 @@
/// Credentials for a channel using Cronet.
std::shared_ptr<ChannelCredentials> CronetChannelCredentials(void* engine);
-// User defined metadata credentials.
+/// User defined metadata credentials.
class MetadataCredentialsPlugin {
public:
virtual ~MetadataCredentialsPlugin() {}
- // If this method returns true, the Process function will be scheduled in
- // a different thread from the one processing the call.
+ /// If this method returns true, the Process function will be scheduled in
+ /// a different thread from the one processing the call.
virtual bool IsBlocking() const { return true; }
- // Type of credentials this plugin is implementing.
+ /// Type of credentials this plugin is implementing.
virtual const char* GetType() const { return ""; }
- // Gets the auth metatada produced by this plugin.
- // The fully qualified method name is:
- // service_url + "/" + method_name.
- // The channel_auth_context contains (among other things), the identity of
- // the server.
+ /// Gets the auth metatada produced by this plugin.
+ /// The fully qualified method name is:
+ /// service_url + "/" + method_name.
+ /// The channel_auth_context contains (among other things), the identity of
+ /// the server.
virtual Status GetMetadata(
grpc::string_ref service_url, grpc::string_ref method_name,
const AuthContext& channel_auth_context,
diff --git a/include/grpc++/security/server_credentials.h b/include/grpc++/security/server_credentials.h
index 229bab8..4676b04 100644
--- a/include/grpc++/security/server_credentials.h
+++ b/include/grpc++/security/server_credentials.h
@@ -46,13 +46,13 @@
namespace grpc {
class Server;
-// Wrapper around \a grpc_server_credentials, a way to authenticate a server.
+/// Wrapper around \a grpc_server_credentials, a way to authenticate a server.
class ServerCredentials {
public:
virtual ~ServerCredentials();
- // This method is not thread-safe and has to be called before the server is
- // started. The last call to this function wins.
+ /// This method is not thread-safe and has to be called before the server is
+ /// started. The last call to this function wins.
virtual void SetAuthMetadataProcessor(
const std::shared_ptr<AuthMetadataProcessor>& processor) = 0;
@@ -70,7 +70,7 @@
/// Options to create ServerCredentials with SSL
struct SslServerCredentialsOptions {
- // Deprecated
+ /// Deprecated
SslServerCredentialsOptions()
: force_client_auth(false),
client_certificate_request(GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE) {}
@@ -84,12 +84,12 @@
};
grpc::string pem_root_certs;
std::vector<PemKeyCertPair> pem_key_cert_pairs;
- // Deprecated
+ /// Deprecated
bool force_client_auth;
- // If both force_client_auth and client_certificate_request fields are set,
- // force_client_auth takes effect i.e
- // REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY will be enforced.
+ /// If both force_client_auth and client_certificate_request fields are set,
+ /// force_client_auth takes effect i.e
+ /// REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY will be enforced.
grpc_ssl_client_certificate_request_type client_certificate_request;
};
diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h
index 5a85776..2185b28 100644
--- a/include/grpc++/server_builder.h
+++ b/include/grpc++/server_builder.h
@@ -46,6 +46,7 @@
#include <grpc/compression.h>
#include <grpc/support/cpu.h>
#include <grpc/support/useful.h>
+#include <grpc/support/workaround_list.h>
struct grpc_resource_quota;
@@ -184,6 +185,11 @@
static void InternalAddPluginFactory(
std::unique_ptr<ServerBuilderPlugin> (*CreatePlugin)());
+ /// Enable a server workaround. Do not use unless you know what the workaround
+ /// does. For explanation and detailed descriptions of workarounds, see
+ /// doc/workarounds.md.
+ ServerBuilder& EnableWorkaround(grpc_workaround_list id);
+
private:
friend class ::grpc::testing::ServerBuilderPluginTest;
diff --git a/include/grpc++/support/error_details.h b/include/grpc++/support/error_details.h
index 411175f..d4324d3 100644
--- a/include/grpc++/support/error_details.h
+++ b/include/grpc++/support/error_details.h
@@ -44,16 +44,16 @@
namespace grpc {
-// Maps a grpc::Status to a google::rpc::Status.
-// The given \a to object will be cleared.
-// On success, returns status with OK.
-// Returns status with INVALID_ARGUMENT, if failed to deserialize.
-// Returns status with FAILED_PRECONDITION, if \a to is nullptr.
+/// Maps a grpc::Status to a google::rpc::Status.
+/// The given \a to object will be cleared.
+/// On success, returns status with OK.
+/// Returns status with INVALID_ARGUMENT, if failed to deserialize.
+/// Returns status with FAILED_PRECONDITION, if \a to is nullptr.
Status ExtractErrorDetails(const Status& from, ::google::rpc::Status* to);
-// Maps google::rpc::Status to a grpc::Status.
-// Returns OK on success.
-// Returns status with FAILED_PRECONDITION if \a to is nullptr.
+/// Maps google::rpc::Status to a grpc::Status.
+/// Returns OK on success.
+/// Returns status with FAILED_PRECONDITION if \a to is nullptr.
Status SetErrorDetails(const ::google::rpc::Status& from, Status* to);
} // namespace grpc
diff --git a/include/grpc++/test/mock_stream.h b/include/grpc++/test/mock_stream.h
index f2de947..f6e94a4 100644
--- a/include/grpc++/test/mock_stream.h
+++ b/include/grpc++/test/mock_stream.h
@@ -50,14 +50,14 @@
public:
MockClientReader() = default;
- // ClientStreamingInterface
+ /// ClientStreamingInterface
MOCK_METHOD0_T(Finish, Status());
- // ReaderInterface
+ /// ReaderInterface
MOCK_METHOD1_T(NextMessageSize, bool(uint32_t*));
MOCK_METHOD1_T(Read, bool(R*));
- // ClientReaderInterface
+ /// ClientReaderInterface
MOCK_METHOD0_T(WaitForInitialMetadata, void());
};
@@ -66,13 +66,13 @@
public:
MockClientWriter() = default;
- // ClientStreamingInterface
+ /// ClientStreamingInterface
MOCK_METHOD0_T(Finish, Status());
- // WriterInterface
+ /// WriterInterface
MOCK_METHOD2_T(Write, bool(const W&, const WriteOptions));
- // ClientWriterInterface
+ /// ClientWriterInterface
MOCK_METHOD0_T(WritesDone, bool());
};
@@ -81,22 +81,22 @@
public:
MockClientReaderWriter() = default;
- // ClientStreamingInterface
+ /// ClientStreamingInterface
MOCK_METHOD0_T(Finish, Status());
- // ReaderInterface
+ /// ReaderInterface
MOCK_METHOD1_T(NextMessageSize, bool(uint32_t*));
MOCK_METHOD1_T(Read, bool(R*));
- // WriterInterface
+ /// WriterInterface
MOCK_METHOD2_T(Write, bool(const W&, const WriteOptions));
- // ClientReaderWriterInterface
+ /// ClientReaderWriterInterface
MOCK_METHOD0_T(WaitForInitialMetadata, void());
MOCK_METHOD0_T(WritesDone, bool());
};
-// TODO: We do not support mocking an async RPC for now.
+/// TODO: We do not support mocking an async RPC for now.
template <class R>
class MockClientAsyncResponseReader
@@ -113,11 +113,11 @@
public:
MockClientAsyncReader() = default;
- // ClientAsyncStreamingInterface
+ /// ClientAsyncStreamingInterface
MOCK_METHOD1_T(ReadInitialMetadata, void(void*));
MOCK_METHOD2_T(Finish, void(Status*, void*));
- // AsyncReaderInterface
+ /// AsyncReaderInterface
MOCK_METHOD2_T(Read, void(R*, void*));
};
@@ -126,14 +126,14 @@
public:
MockClientAsyncWriter() = default;
- // ClientAsyncStreamingInterface
+ /// ClientAsyncStreamingInterface
MOCK_METHOD1_T(ReadInitialMetadata, void(void*));
MOCK_METHOD2_T(Finish, void(Status*, void*));
- // AsyncWriterInterface
+ /// AsyncWriterInterface
MOCK_METHOD2_T(Write, void(const W&, void*));
- // ClientAsyncWriterInterface
+ /// ClientAsyncWriterInterface
MOCK_METHOD1_T(WritesDone, void(void*));
};
@@ -143,17 +143,17 @@
public:
MockClientAsyncReaderWriter() = default;
- // ClientAsyncStreamingInterface
+ /// ClientAsyncStreamingInterface
MOCK_METHOD1_T(ReadInitialMetadata, void(void*));
MOCK_METHOD2_T(Finish, void(Status*, void*));
- // AsyncWriterInterface
+ /// AsyncWriterInterface
MOCK_METHOD2_T(Write, void(const W&, void*));
- // AsyncReaderInterface
+ /// AsyncReaderInterface
MOCK_METHOD2_T(Read, void(R*, void*));
- // ClientAsyncReaderWriterInterface
+ /// ClientAsyncReaderWriterInterface
MOCK_METHOD1_T(WritesDone, void(void*));
};
diff --git a/include/grpc++/test/server_context_test_spouse.h b/include/grpc++/test/server_context_test_spouse.h
index bac0db7..5bd07e7 100644
--- a/include/grpc++/test/server_context_test_spouse.h
+++ b/include/grpc++/test/server_context_test_spouse.h
@@ -41,13 +41,13 @@
namespace grpc {
namespace testing {
-// A test-only class to access private members and methods of ServerContext.
+/// A test-only class to access private members and methods of ServerContext.
class ServerContextTestSpouse {
public:
explicit ServerContextTestSpouse(ServerContext* ctx) : ctx_(ctx) {}
- // Inject client metadata to the ServerContext for the test. The test spouse
- // must be alive when ServerContext::client_metadata is called.
+ /// Inject client metadata to the ServerContext for the test. The test spouse
+ /// must be alive when ServerContext::client_metadata is called.
void AddClientMetadata(const grpc::string& key, const grpc::string& value) {
client_metadata_storage_.insert(
std::pair<grpc::string, grpc::string>(key, value));
@@ -70,7 +70,7 @@
}
private:
- ServerContext* ctx_; // not owned
+ ServerContext* ctx_; /// not owned
std::multimap<grpc::string, grpc::string> client_metadata_storage_;
};
diff --git a/include/grpc/census.h b/include/grpc/census.h
index 822c42c..68cefd8 100644
--- a/include/grpc/census.h
+++ b/include/grpc/census.h
@@ -31,7 +31,7 @@
*
*/
-/* RPC-internal Census API's. These are designed to be generic enough that
+/** RPC-internal Census API's. These are designed to be generic enough that
* they can (ultimately) be used in many different RPC systems (with differing
* implementations). */
@@ -44,12 +44,12 @@
extern "C" {
#endif
-/* Identify census features that can be enabled via census_initialize(). */
+/** Identify census features that can be enabled via census_initialize(). */
enum census_features {
- CENSUS_FEATURE_NONE = 0, /* Do not enable census. */
- CENSUS_FEATURE_TRACING = 1, /* Enable census tracing. */
- CENSUS_FEATURE_STATS = 2, /* Enable Census stats collection. */
- CENSUS_FEATURE_CPU = 4, /* Enable Census CPU usage collection. */
+ CENSUS_FEATURE_NONE = 0, /** Do not enable census. */
+ CENSUS_FEATURE_TRACING = 1, /** Enable census tracing. */
+ CENSUS_FEATURE_STATS = 2, /** Enable Census stats collection. */
+ CENSUS_FEATURE_CPU = 4, /** Enable Census CPU usage collection. */
CENSUS_FEATURE_ALL =
CENSUS_FEATURE_TRACING | CENSUS_FEATURE_STATS | CENSUS_FEATURE_CPU
};
@@ -82,7 +82,7 @@
metrics will be recorded. Keys are unique within a context. */
typedef struct census_context census_context;
-/* A tag is a key:value pair. Both keys and values are nil-terminated strings,
+/** A tag is a key:value pair. Both keys and values are nil-terminated strings,
containing printable ASCII characters (decimal 32-126). Keys must be at
least one character in length. Both keys and values can have at most
CENSUS_MAX_TAG_KB_LEN characters (including the terminating nil). The
@@ -97,36 +97,36 @@
uint8_t flags;
} census_tag;
-/* Maximum length of a tag's key or value. */
+/** Maximum length of a tag's key or value. */
#define CENSUS_MAX_TAG_KV_LEN 255
-/* Maximum number of propagatable tags. */
+/** Maximum number of propagatable tags. */
#define CENSUS_MAX_PROPAGATED_TAGS 255
-/* Tag flags. */
-#define CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */
-#define CENSUS_TAG_STATS 2 /* Tag will be used for statistics aggregation */
-#define CENSUS_TAG_RESERVED 4 /* Reserved for internal use. */
-/* Flag values 4,8,16,32,64,128 are reserved for future/internal use. Clients
+/** Tag flags. */
+#define CENSUS_TAG_PROPAGATE 1 /** Tag should be propagated over RPC */
+#define CENSUS_TAG_STATS 2 /** Tag will be used for statistics aggregation */
+#define CENSUS_TAG_RESERVED 4 /** Reserved for internal use. */
+/** Flag values 4,8,16,32,64,128 are reserved for future/internal use. Clients
should not use or rely on their values. */
#define CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE)
#define CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS)
-/* An instance of this structure is kept by every context, and records the
+/** An instance of this structure is kept by every context, and records the
basic information associated with the creation of that context. */
typedef struct {
- int n_propagated_tags; /* number of propagated tags */
- int n_local_tags; /* number of non-propagated (local) tags */
- int n_deleted_tags; /* number of tags that were deleted */
- int n_added_tags; /* number of tags that were added */
- int n_modified_tags; /* number of tags that were modified */
- int n_invalid_tags; /* number of tags with bad keys or values (e.g.
+ int n_propagated_tags; /** number of propagated tags */
+ int n_local_tags; /** number of non-propagated (local) tags */
+ int n_deleted_tags; /** number of tags that were deleted */
+ int n_added_tags; /** number of tags that were added */
+ int n_modified_tags; /** number of tags that were modified */
+ int n_invalid_tags; /** number of tags with bad keys or values (e.g.
longer than CENSUS_MAX_TAG_KV_LEN) */
- int n_ignored_tags; /* number of tags ignored because of
+ int n_ignored_tags; /** number of tags ignored because of
CENSUS_MAX_PROPAGATED_TAGS limit. */
} census_context_status;
-/* Create a new context, adding and removing tags from an existing context.
+/** Create a new context, adding and removing tags from an existing context.
This will copy all tags from the 'tags' input, so it is recommended
to add as many tags in a single operation as is practical for the client.
@param base Base context to build upon. Can be NULL.
@@ -148,15 +148,15 @@
const census_context *base, const census_tag *tags, int ntags,
census_context_status const **status);
-/* Destroy a context. Once this function has been called, the context cannot
+/** Destroy a context. Once this function has been called, the context cannot
be reused. */
CENSUSAPI void census_context_destroy(census_context *context);
-/* Get a pointer to the original status from the context creation. */
+/** Get a pointer to the original status from the context creation. */
CENSUSAPI const census_context_status *census_context_get_status(
const census_context *context);
-/* Structure used for iterating over the tags in a context. API clients should
+/** Structure used for iterating over the tags in a context. API clients should
not use or reference internal fields - neither their contents or
presence/absence are guaranteed. */
typedef struct {
@@ -166,25 +166,25 @@
char *kvm;
} census_context_iterator;
-/* Initialize a census_tag_iterator. Must be called before first use. */
+/** Initialize a census_tag_iterator. Must be called before first use. */
CENSUSAPI void census_context_initialize_iterator(
const census_context *context, census_context_iterator *iterator);
-/* Get the contents of the "next" tag in the context. If there are no more
+/** Get the contents of the "next" tag in the context. If there are no more
tags, returns 0 (and 'tag' contents will be unchanged), otherwise returns 1.
*/
CENSUSAPI int census_context_next_tag(census_context_iterator *iterator,
census_tag *tag);
-/* Get a context tag by key. Returns 0 if the key is not present. */
+/** Get a context tag by key. Returns 0 if the key is not present. */
CENSUSAPI int census_context_get_tag(const census_context *context,
const char *key, census_tag *tag);
-/* Tag set encode/decode functionality. These functions are intended
+/** Tag set encode/decode functionality. These functions are intended
for use by RPC systems only, for purposes of transmitting/receiving contexts.
*/
-/* Encode a context into a buffer.
+/** Encode a context into a buffer.
@param context context to be encoded
@param buffer buffer into which the context will be encoded.
@param buf_size number of available bytes in buffer.
@@ -193,15 +193,15 @@
CENSUSAPI size_t census_context_encode(const census_context *context,
char *buffer, size_t buf_size);
-/* Decode context buffer encoded with census_context_encode(). Returns NULL
+/** Decode context buffer encoded with census_context_encode(). Returns NULL
if there is an error in parsing either buffer. */
CENSUSAPI census_context *census_context_decode(const char *buffer,
size_t size);
-/* Distributed traces can have a number of options. */
+/** Distributed traces can have a number of options. */
enum census_trace_mask_values {
- CENSUS_TRACE_MASK_NONE = 0, /* Default, empty flags */
- CENSUS_TRACE_MASK_IS_SAMPLED = 1 /* RPC tracing enabled for this context. */
+ CENSUS_TRACE_MASK_NONE = 0, /** Default, empty flags */
+ CENSUS_TRACE_MASK_IS_SAMPLED = 1 /** RPC tracing enabled for this context. */
};
/** Get the current trace mask associated with this context. The value returned
@@ -211,7 +211,7 @@
/** Set the trace mask associated with a context. */
CENSUSAPI void census_set_trace_mask(int trace_mask);
-/* The concept of "operation" is a fundamental concept for Census. In an RPC
+/** The concept of "operation" is a fundamental concept for Census. In an RPC
system, an operation typically represents a single RPC, or a significant
sub-part thereof (e.g. a single logical "read" RPC to a distributed storage
system might do several other actions in parallel, from looking up metadata
@@ -238,7 +238,7 @@
at which an operation begins.
*/
typedef struct {
- /* Use gpr_timespec for default implementation. High performance
+ /** Use gpr_timespec for default implementation. High performance
* implementations should use a cycle-counter based timestamp. */
gpr_timespec ts;
} census_timestamp;
@@ -398,12 +398,12 @@
/** Trace record. */
typedef struct {
- census_timestamp timestamp; /* Time of record creation */
- uint64_t trace_id; /* Trace ID associated with record */
- uint64_t op_id; /* Operation ID associated with record */
- uint32_t type; /* Type (as used in census_trace_print() */
- const char *buffer; /* Buffer (from census_trace_print() */
- size_t buf_size; /* Number of bytes inside buffer */
+ census_timestamp timestamp; /** Time of record creation */
+ uint64_t trace_id; /** Trace ID associated with record */
+ uint64_t op_id; /** Operation ID associated with record */
+ uint32_t type; /** Type (as used in census_trace_print() */
+ const char *buffer; /** Buffer (from census_trace_print() */
+ size_t buf_size; /** Number of bytes inside buffer */
} census_trace_record;
/** Start a scan of existing trace records. While a scan is ongoing, addition
@@ -431,7 +431,7 @@
/** End a scan previously started by census_trace_scan_start() */
CENSUSAPI void census_trace_scan_end();
-/* Core stats collection API's. The following concepts are used:
+/** Core stats collection API's. The following concepts are used:
* Resource: Users record measurements for a single resource. Examples
include RPC latency, CPU seconds consumed, and bytes transmitted.
* Aggregation: An aggregation of a set of measurements. Census supports the
@@ -450,7 +450,7 @@
implementations. The proto definitions can be found in src/proto/census.
*/
-/* Define a new resource. `resource_pb` should contain an encoded Resource
+/** Define a new resource. `resource_pb` should contain an encoded Resource
protobuf, `resource_pb_size` being the size of the buffer. Returns a -ve
value on error, or a positive (>= 0) resource id (for use in
census_delete_resource() and census_record_values()). In order to be valid, a
@@ -459,21 +459,21 @@
CENSUSAPI int32_t census_define_resource(const uint8_t *resource_pb,
size_t resource_pb_size);
-/* Delete a resource created by census_define_resource(). */
+/** Delete a resource created by census_define_resource(). */
CENSUSAPI void census_delete_resource(int32_t resource_id);
-/* Determine the id of a resource, given its name. returns -1 if the resource
+/** Determine the id of a resource, given its name. returns -1 if the resource
does not exist. */
CENSUSAPI int32_t census_resource_id(const char *name);
-/* A single value to be recorded comprises two parts: an ID for the particular
+/** A single value to be recorded comprises two parts: an ID for the particular
* resource and the value to be recorded against it. */
typedef struct {
int32_t resource_id;
double value;
} census_value;
-/* Record new usage values against the given context. */
+/** Record new usage values against the given context. */
CENSUSAPI void census_record_values(census_context *context,
census_value *values, size_t nvalues);
diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h
index 1eeb075..a36367f 100644
--- a/include/grpc/grpc.h
+++ b/include/grpc/grpc.h
@@ -287,7 +287,7 @@
/** Close and destroy a grpc channel */
GRPCAPI void grpc_channel_destroy(grpc_channel *channel);
-/* Error handling for grpc_call
+/** Error handling for grpc_call
Most grpc_call functions return a grpc_error. If the error is not GRPC_OK
then the operation failed due to some unsatisfied precondition.
If a grpc_call fails, it's guaranteed that no change to the call state
diff --git a/include/grpc/grpc_security.h b/include/grpc/grpc_security.h
index 5d3cc4f..4f35506 100644
--- a/include/grpc/grpc_security.h
+++ b/include/grpc/grpc_security.h
@@ -42,7 +42,7 @@
extern "C" {
#endif
-/* --- Authentication Context. --- */
+/** --- Authentication Context. --- */
typedef struct grpc_auth_context grpc_auth_context;
@@ -52,84 +52,84 @@
const char *name;
} grpc_auth_property_iterator;
-/* value, if not NULL, is guaranteed to be NULL terminated. */
+/** value, if not NULL, is guaranteed to be NULL terminated. */
typedef struct grpc_auth_property {
char *name;
char *value;
size_t value_length;
} grpc_auth_property;
-/* Returns NULL when the iterator is at the end. */
+/** Returns NULL when the iterator is at the end. */
GRPCAPI const grpc_auth_property *grpc_auth_property_iterator_next(
grpc_auth_property_iterator *it);
-/* Iterates over the auth context. */
+/** Iterates over the auth context. */
GRPCAPI grpc_auth_property_iterator
grpc_auth_context_property_iterator(const grpc_auth_context *ctx);
-/* Gets the peer identity. Returns an empty iterator (first _next will return
+/** Gets the peer identity. Returns an empty iterator (first _next will return
NULL) if the peer is not authenticated. */
GRPCAPI grpc_auth_property_iterator
grpc_auth_context_peer_identity(const grpc_auth_context *ctx);
-/* Finds a property in the context. May return an empty iterator (first _next
+/** Finds a property in the context. May return an empty iterator (first _next
will return NULL) if no property with this name was found in the context. */
GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(
const grpc_auth_context *ctx, const char *name);
-/* Gets the name of the property that indicates the peer identity. Will return
+/** Gets the name of the property that indicates the peer identity. Will return
NULL if the peer is not authenticated. */
GRPCAPI const char *grpc_auth_context_peer_identity_property_name(
const grpc_auth_context *ctx);
-/* Returns 1 if the peer is authenticated, 0 otherwise. */
+/** Returns 1 if the peer is authenticated, 0 otherwise. */
GRPCAPI int grpc_auth_context_peer_is_authenticated(
const grpc_auth_context *ctx);
-/* Gets the auth context from the call. Caller needs to call
+/** Gets the auth context from the call. Caller needs to call
grpc_auth_context_release on the returned context. */
GRPCAPI grpc_auth_context *grpc_call_auth_context(grpc_call *call);
-/* Releases the auth context returned from grpc_call_auth_context. */
+/** Releases the auth context returned from grpc_call_auth_context. */
GRPCAPI void grpc_auth_context_release(grpc_auth_context *context);
-/* --
+/** --
The following auth context methods should only be called by a server metadata
processor to set properties extracted from auth metadata.
-- */
-/* Add a property. */
+/** Add a property. */
GRPCAPI void grpc_auth_context_add_property(grpc_auth_context *ctx,
const char *name, const char *value,
size_t value_length);
-/* Add a C string property. */
+/** Add a C string property. */
GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context *ctx,
const char *name,
const char *value);
-/* Sets the property name. Returns 1 if successful or 0 in case of failure
+/** Sets the property name. Returns 1 if successful or 0 in case of failure
(which means that no property with this name exists). */
GRPCAPI int grpc_auth_context_set_peer_identity_property_name(
grpc_auth_context *ctx, const char *name);
-/* --- grpc_channel_credentials object. ---
+/** --- grpc_channel_credentials object. ---
A channel credentials object represents a way to authenticate a client on a
channel. */
typedef struct grpc_channel_credentials grpc_channel_credentials;
-/* Releases a channel credentials object.
+/** Releases a channel credentials object.
The creator of the credentials object is responsible for its release. */
GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials *creds);
-/* Creates default credentials to connect to a google gRPC service.
+/** Creates default credentials to connect to a google gRPC service.
WARNING: Do NOT use this credentials to connect to a non-google service as
this could result in an oauth2 token leak. */
GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void);
-/* Callback for getting the SSL roots override from the application.
+/** Callback for getting the SSL roots override from the application.
In case of success, *pem_roots_certs must be set to a NULL terminated string
containing the list of PEM encoded root certificates. The ownership is passed
to the core and freed (laster by the core) with gpr_free.
@@ -138,7 +138,7 @@
typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)(
char **pem_root_certs);
-/* Setup a callback to override the default TLS/SSL roots.
+/** Setup a callback to override the default TLS/SSL roots.
This function is not thread-safe and must be called at initialization time
before any ssl credentials are created to have the desired side effect.
If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the
@@ -146,18 +146,18 @@
GRPCAPI void grpc_set_ssl_roots_override_callback(
grpc_ssl_roots_override_callback cb);
-/* Object that holds a private key / certificate chain pair in PEM format. */
+/** Object that holds a private key / certificate chain pair in PEM format. */
typedef struct {
- /* private_key is the NULL-terminated string containing the PEM encoding of
+ /** private_key is the NULL-terminated string containing the PEM encoding of
the client's private key. */
const char *private_key;
- /* cert_chain is the NULL-terminated string containing the PEM encoding of
+ /** cert_chain is the NULL-terminated string containing the PEM encoding of
the client's certificate chain. */
const char *cert_chain;
} grpc_ssl_pem_key_cert_pair;
-/* Creates an SSL credentials object.
+/** Creates an SSL credentials object.
- pem_root_certs is the NULL-terminated string containing the PEM encoding
of the server root certificates. If this parameter is NULL, the
implementation will first try to dereference the file pointed by the
@@ -172,7 +172,7 @@
const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair,
void *reserved);
-/* --- grpc_call_credentials object.
+/** --- grpc_call_credentials object.
A call credentials object represents a way to authenticate on a particular
call. These credentials can be composed with a channel credentials object
@@ -180,21 +180,21 @@
typedef struct grpc_call_credentials grpc_call_credentials;
-/* Releases a call credentials object.
+/** Releases a call credentials object.
The creator of the credentials object is responsible for its release. */
GRPCAPI void grpc_call_credentials_release(grpc_call_credentials *creds);
-/* Creates a composite channel credentials object. */
+/** Creates a composite channel credentials object. */
GRPCAPI grpc_channel_credentials *grpc_composite_channel_credentials_create(
grpc_channel_credentials *channel_creds, grpc_call_credentials *call_creds,
void *reserved);
-/* Creates a composite call credentials object. */
+/** Creates a composite call credentials object. */
GRPCAPI grpc_call_credentials *grpc_composite_call_credentials_create(
grpc_call_credentials *creds1, grpc_call_credentials *creds2,
void *reserved);
-/* Creates a compute engine credentials object for connecting to Google.
+/** Creates a compute engine credentials object for connecting to Google.
WARNING: Do NOT use this credentials to connect to a non-google service as
this could result in an oauth2 token leak. */
GRPCAPI grpc_call_credentials *grpc_google_compute_engine_credentials_create(
@@ -202,7 +202,7 @@
GRPCAPI gpr_timespec grpc_max_auth_token_lifetime();
-/* Creates a JWT credentials object. May return NULL if the input is invalid.
+/** Creates a JWT credentials object. May return NULL if the input is invalid.
- json_key is the JSON key string containing the client's private key.
- token_lifetime is the lifetime of each Json Web Token (JWT) created with
this credentials. It should not exceed grpc_max_auth_token_lifetime or
@@ -212,7 +212,7 @@
gpr_timespec token_lifetime,
void *reserved);
-/* Creates an Oauth2 Refresh Token credentials object for connecting to Google.
+/** Creates an Oauth2 Refresh Token credentials object for connecting to Google.
May return NULL if the input is invalid.
WARNING: Do NOT use this credentials to connect to a non-google service as
this could result in an oauth2 token leak.
@@ -221,17 +221,17 @@
GRPCAPI grpc_call_credentials *grpc_google_refresh_token_credentials_create(
const char *json_refresh_token, void *reserved);
-/* Creates an Oauth2 Access Token credentials with an access token that was
+/** Creates an Oauth2 Access Token credentials with an access token that was
aquired by an out of band mechanism. */
GRPCAPI grpc_call_credentials *grpc_access_token_credentials_create(
const char *access_token, void *reserved);
-/* Creates an IAM credentials object for connecting to Google. */
+/** Creates an IAM credentials object for connecting to Google. */
GRPCAPI grpc_call_credentials *grpc_google_iam_credentials_create(
const char *authorization_token, const char *authority_selector,
void *reserved);
-/* Callback function to be called by the metadata credentials plugin
+/** Callback function to be called by the metadata credentials plugin
implementation when the metadata is ready.
- user_data is the opaque pointer that was passed in the get_metadata method
of the grpc_metadata_credentials_plugin (see below).
@@ -246,31 +246,31 @@
void *user_data, const grpc_metadata *creds_md, size_t num_creds_md,
grpc_status_code status, const char *error_details);
-/* Context that can be used by metadata credentials plugin in order to create
+/** Context that can be used by metadata credentials plugin in order to create
auth related metadata. */
typedef struct {
- /* The fully qualifed service url. */
+ /** The fully qualifed service url. */
const char *service_url;
- /* The method name of the RPC being called (not fully qualified).
+ /** The method name of the RPC being called (not fully qualified).
The fully qualified method name can be built from the service_url:
full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */
const char *method_name;
- /* The auth_context of the channel which gives the server's identity. */
+ /** The auth_context of the channel which gives the server's identity. */
const grpc_auth_context *channel_auth_context;
- /* Reserved for future use. */
+ /** Reserved for future use. */
void *reserved;
} grpc_auth_metadata_context;
-/* grpc_metadata_credentials plugin is an API user provided structure used to
+/** grpc_metadata_credentials plugin is an API user provided structure used to
create grpc_credentials objects that can be set on a channel (composed) or
a call. See grpc_credentials_metadata_create_from_plugin below.
The grpc client stack will call the get_metadata method of the plugin for
every call in scope for the credentials created from it. */
typedef struct {
- /* The implementation of this method has to be non-blocking.
+ /** The implementation of this method has to be non-blocking.
- context is the information that can be used by the plugin to create auth
metadata.
- cb is the callback that needs to be called when the metadata is ready.
@@ -278,39 +278,39 @@
void (*get_metadata)(void *state, grpc_auth_metadata_context context,
grpc_credentials_plugin_metadata_cb cb, void *user_data);
- /* Destroys the plugin state. */
+ /** Destroys the plugin state. */
void (*destroy)(void *state);
- /* State that will be set as the first parameter of the methods above. */
+ /** State that will be set as the first parameter of the methods above. */
void *state;
- /* Type of credentials that this plugin is implementing. */
+ /** Type of credentials that this plugin is implementing. */
const char *type;
} grpc_metadata_credentials_plugin;
-/* Creates a credentials object from a plugin. */
+/** Creates a credentials object from a plugin. */
GRPCAPI grpc_call_credentials *grpc_metadata_credentials_create_from_plugin(
grpc_metadata_credentials_plugin plugin, void *reserved);
-/* --- Secure channel creation. --- */
+/** --- Secure channel creation. --- */
-/* Creates a secure channel using the passed-in credentials. */
+/** Creates a secure channel using the passed-in credentials. */
GRPCAPI grpc_channel *grpc_secure_channel_create(
grpc_channel_credentials *creds, const char *target,
const grpc_channel_args *args, void *reserved);
-/* --- grpc_server_credentials object. ---
+/** --- grpc_server_credentials object. ---
A server credentials object represents a way to authenticate a server. */
typedef struct grpc_server_credentials grpc_server_credentials;
-/* Releases a server_credentials object.
+/** Releases a server_credentials object.
The creator of the server_credentials object is responsible for its release.
*/
GRPCAPI void grpc_server_credentials_release(grpc_server_credentials *creds);
-/* Deprecated in favor of grpc_ssl_server_credentials_create_ex.
+/** Deprecated in favor of grpc_ssl_server_credentials_create_ex.
Creates an SSL server_credentials object.
- pem_roots_cert is the NULL-terminated string containing the PEM encoding of
the client root certificates. This parameter may be NULL if the server does
@@ -326,7 +326,7 @@
const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs,
size_t num_key_cert_pairs, int force_client_auth, void *reserved);
-/* Same as grpc_ssl_server_credentials_create method except uses
+/** Same as grpc_ssl_server_credentials_create method except uses
grpc_ssl_client_certificate_request_type enum to support more ways to
authenticate client cerificates.*/
GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex(
@@ -335,25 +335,25 @@
grpc_ssl_client_certificate_request_type client_certificate_request,
void *reserved);
-/* --- Server-side secure ports. --- */
+/** --- Server-side secure ports. --- */
-/* Add a HTTP2 over an encrypted link over tcp listener.
+/** Add a HTTP2 over an encrypted link over tcp listener.
Returns bound port number on success, 0 on failure.
REQUIRES: server not started */
GRPCAPI int grpc_server_add_secure_http2_port(grpc_server *server,
const char *addr,
grpc_server_credentials *creds);
-/* --- Call specific credentials. --- */
+/** --- Call specific credentials. --- */
-/* Sets a credentials to a call. Can only be called on the client side before
+/** Sets a credentials to a call. Can only be called on the client side before
grpc_call_start_batch. */
GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call *call,
grpc_call_credentials *creds);
-/* --- Auth Metadata Processing --- */
+/** --- Auth Metadata Processing --- */
-/* Callback function that is called when the metadata processing is done.
+/** Callback function that is called when the metadata processing is done.
- Consumed metadata will be removed from the set of metadata available on the
call. consumed_md may be NULL if no metadata has been consumed.
- Response metadata will be set on the response. response_md may be NULL.
@@ -367,9 +367,9 @@
const grpc_metadata *response_md, size_t num_response_md,
grpc_status_code status, const char *error_details);
-/* Pluggable server-side metadata processor object. */
+/** Pluggable server-side metadata processor object. */
typedef struct {
- /* The context object is read/write: it contains the properties of the
+ /** The context object is read/write: it contains the properties of the
channel peer and it is the job of the process function to augment it with
properties derived from the passed-in metadata.
The lifetime of these objects is guaranteed until cb is invoked. */
diff --git a/include/grpc/grpc_security_constants.h b/include/grpc/grpc_security_constants.h
index da05c5a..d7ac0b2 100644
--- a/include/grpc/grpc_security_constants.h
+++ b/include/grpc/grpc_security_constants.h
@@ -45,30 +45,30 @@
#define GRPC_X509_SAN_PROPERTY_NAME "x509_subject_alternative_name"
#define GRPC_X509_PEM_CERT_PROPERTY_NAME "x509_pem_cert"
-/* Environment variable that points to the default SSL roots file. This file
+/** Environment variable that points to the default SSL roots file. This file
must be a PEM encoded file with all the roots such as the one that can be
downloaded from https://pki.google.com/roots.pem. */
#define GRPC_DEFAULT_SSL_ROOTS_FILE_PATH_ENV_VAR \
"GRPC_DEFAULT_SSL_ROOTS_FILE_PATH"
-/* Environment variable that points to the google default application
+/** Environment variable that points to the google default application
credentials json key or refresh token. Used in the
grpc_google_default_credentials_create function. */
#define GRPC_GOOGLE_CREDENTIALS_ENV_VAR "GOOGLE_APPLICATION_CREDENTIALS"
-/* Results for the SSL roots override callback. */
+/** Results for the SSL roots override callback. */
typedef enum {
GRPC_SSL_ROOTS_OVERRIDE_OK,
- GRPC_SSL_ROOTS_OVERRIDE_FAIL_PERMANENTLY, /* Do not try fallback options. */
+ GRPC_SSL_ROOTS_OVERRIDE_FAIL_PERMANENTLY, /** Do not try fallback options. */
GRPC_SSL_ROOTS_OVERRIDE_FAIL
} grpc_ssl_roots_override_result;
typedef enum {
- /* Server does not request client certificate. A client can present a self
+ /** Server does not request client certificate. A client can present a self
signed or signed certificates if it wishes to do so and they would be
accepted. */
GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE,
- /* Server requests client certificate but does not enforce that the client
+ /** Server requests client certificate but does not enforce that the client
presents a certificate.
If the client presents a certificate, the client authentication is left to
@@ -77,7 +77,7 @@
The key cert pair should still be valid for the SSL connection to be
established. */
GRPC_SSL_REQUEST_CLIENT_CERTIFICATE_BUT_DONT_VERIFY,
- /* Server requests client certificate but does not enforce that the client
+ /** Server requests client certificate but does not enforce that the client
presents a certificate.
If the client presents a certificate, the client authentication is done by
@@ -87,7 +87,7 @@
The key cert pair should still be valid for the SSL connection to be
established. */
GRPC_SSL_REQUEST_CLIENT_CERTIFICATE_AND_VERIFY,
- /* Server requests client certificate but enforces that the client presents a
+ /** Server requests client certificate but enforces that the client presents a
certificate.
If the client presents a certificate, the client authentication is left to
@@ -96,7 +96,7 @@
The key cert pair should still be valid for the SSL connection to be
established. */
GRPC_SSL_REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_BUT_DONT_VERIFY,
- /* Server requests client certificate but enforces that the client presents a
+ /** Server requests client certificate but enforces that the client presents a
certificate.
The cerificate presented by the client is verified by grpc framework (The
diff --git a/include/grpc/impl/codegen/atm.h b/include/grpc/impl/codegen/atm.h
index 4bd572d..d348f32 100644
--- a/include/grpc/impl/codegen/atm.h
+++ b/include/grpc/impl/codegen/atm.h
@@ -34,7 +34,7 @@
#ifndef GRPC_IMPL_CODEGEN_ATM_H
#define GRPC_IMPL_CODEGEN_ATM_H
-/* This interface provides atomic operations and barriers.
+/** This interface provides atomic operations and barriers.
It is internal to gpr support code and should not be used outside it.
If an operation with acquire semantics precedes another memory access by the
diff --git a/include/grpc/impl/codegen/atm_windows.h b/include/grpc/impl/codegen/atm_windows.h
index a533651..fa842a3 100644
--- a/include/grpc/impl/codegen/atm_windows.h
+++ b/include/grpc/impl/codegen/atm_windows.h
@@ -34,7 +34,7 @@
#ifndef GRPC_IMPL_CODEGEN_ATM_WINDOWS_H
#define GRPC_IMPL_CODEGEN_ATM_WINDOWS_H
-/* Win32 variant of atm_platform.h */
+/** Win32 variant of atm_platform.h */
#include <grpc/impl/codegen/port_platform.h>
typedef intptr_t gpr_atm;
@@ -64,7 +64,7 @@
}
static __inline int gpr_atm_no_barrier_cas(gpr_atm *p, gpr_atm o, gpr_atm n) {
-/* InterlockedCompareExchangePointerNoFence() not available on vista or
+/** InterlockedCompareExchangePointerNoFence() not available on vista or
windows7 */
#ifdef GPR_ARCH_64
return o == (gpr_atm)InterlockedCompareExchangeAcquire64(
@@ -107,7 +107,7 @@
static __inline gpr_atm gpr_atm_no_barrier_fetch_add(gpr_atm *p,
gpr_atm delta) {
- /* Use the CAS operation to get pointer-sized fetch and add */
+ /** Use the CAS operation to get pointer-sized fetch and add */
gpr_atm old;
do {
old = *p;
@@ -116,7 +116,7 @@
}
static __inline gpr_atm gpr_atm_full_fetch_add(gpr_atm *p, gpr_atm delta) {
- /* Use a CAS operation to get pointer-sized fetch and add */
+ /** Use a CAS operation to get pointer-sized fetch and add */
gpr_atm old;
#ifdef GPR_ARCH_64
do {
diff --git a/include/grpc/impl/codegen/byte_buffer_reader.h b/include/grpc/impl/codegen/byte_buffer_reader.h
index 85a4864..354a28a 100644
--- a/include/grpc/impl/codegen/byte_buffer_reader.h
+++ b/include/grpc/impl/codegen/byte_buffer_reader.h
@@ -43,9 +43,9 @@
struct grpc_byte_buffer_reader {
struct grpc_byte_buffer *buffer_in;
struct grpc_byte_buffer *buffer_out;
- /* Different current objects correspond to different types of byte buffers */
+ /** Different current objects correspond to different types of byte buffers */
union {
- /* Index into a slice buffer's array of slices */
+ /** Index into a slice buffer's array of slices */
unsigned index;
} current;
};
diff --git a/include/grpc/impl/codegen/compression_types.h b/include/grpc/impl/codegen/compression_types.h
index a563711..953b51d 100644
--- a/include/grpc/impl/codegen/compression_types.h
+++ b/include/grpc/impl/codegen/compression_types.h
@@ -67,7 +67,7 @@
"grpc.compression_enabled_algorithms_bitset"
/** \} */
-/* The various compression algorithms supported by gRPC */
+/** The various compression algorithms supported by gRPC */
typedef enum {
GRPC_COMPRESS_NONE = 0,
GRPC_COMPRESS_DEFLATE,
diff --git a/include/grpc/impl/codegen/gpr_slice.h b/include/grpc/impl/codegen/gpr_slice.h
index c62e976..ead0b7d 100644
--- a/include/grpc/impl/codegen/gpr_slice.h
+++ b/include/grpc/impl/codegen/gpr_slice.h
@@ -33,11 +33,11 @@
#ifndef GRPC_IMPL_CODEGEN_GPR_SLICE_H
#define GRPC_IMPL_CODEGEN_GPR_SLICE_H
-/* WARNING: Please do not use this header. This was added as a temporary measure
- * to not break some of the external projects that depend on gpr_slice_*
- * functions. We are actively working on moving all the gpr_slice_* references
- * to grpc_slice_* and this file will be removed
- * */
+/** WARNING: Please do not use this header. This was added as a temporary
+ * measure to not break some of the external projects that depend on
+ * gpr_slice_* functions. We are actively working on moving all the
+ * gpr_slice_* references to grpc_slice_* and this file will be removed
+ */
/* TODO (sreek) - Allowed by default but will be very soon turned off */
#define GRPC_ALLOW_GPR_SLICE_FUNCTIONS 1
diff --git a/include/grpc/impl/codegen/gpr_types.h b/include/grpc/impl/codegen/gpr_types.h
index 34d8156..ee44252 100644
--- a/include/grpc/impl/codegen/gpr_types.h
+++ b/include/grpc/impl/codegen/gpr_types.h
@@ -42,22 +42,22 @@
extern "C" {
#endif
-/* The clocks we support. */
+/** The clocks we support. */
typedef enum {
- /* Monotonic clock. Epoch undefined. Always moves forwards. */
+ /** Monotonic clock. Epoch undefined. Always moves forwards. */
GPR_CLOCK_MONOTONIC = 0,
- /* Realtime clock. May jump forwards or backwards. Settable by
+ /** Realtime clock. May jump forwards or backwards. Settable by
the system administrator. Has its epoch at 0:00:00 UTC 1 Jan 1970. */
GPR_CLOCK_REALTIME,
- /* CPU cycle time obtained by rdtsc instruction on x86 platforms. Epoch
+ /** CPU cycle time obtained by rdtsc instruction on x86 platforms. Epoch
undefined. Degrades to GPR_CLOCK_REALTIME on other platforms. */
GPR_CLOCK_PRECISE,
- /* Unmeasurable clock type: no base, created by taking the difference
+ /** Unmeasurable clock type: no base, created by taking the difference
between two times */
GPR_TIMESPAN
} gpr_clock_type;
-/* Analogous to struct timespec. On some machines, absolute times may be in
+/** Analogous to struct timespec. On some machines, absolute times may be in
* local time. */
typedef struct gpr_timespec {
int64_t tv_sec;
diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h
index ffb5a77..072452c 100644
--- a/include/grpc/impl/codegen/grpc_types.h
+++ b/include/grpc/impl/codegen/grpc_types.h
@@ -50,7 +50,7 @@
typedef enum {
GRPC_BB_RAW
- /* Future types may include GRPC_BB_PROTOBUF, etc. */
+ /** Future types may include GRPC_BB_PROTOBUF, etc. */
} grpc_byte_buffer_type;
typedef struct grpc_byte_buffer {
@@ -67,8 +67,8 @@
} data;
} grpc_byte_buffer;
-/** Completion Queues enable notification of the completion of asynchronous
- actions. */
+/** Completion Queues enable notification of the completion of
+ * asynchronous actions. */
typedef struct grpc_completion_queue grpc_completion_queue;
/** An alarm associated with a completion queue. */
@@ -134,9 +134,9 @@
Used to set optional channel-level configuration.
These configuration options are modelled as key-value pairs as defined
by grpc_arg; keys are strings to allow easy backwards-compatible extension
- by arbitrary parties.
- All evaluation is performed at channel creation time (i.e. the values in
- this structure need only live through the creation invocation).
+ by arbitrary parties. All evaluation is performed at channel creation
+ time (i.e. the values in this structure need only live through the
+ creation invocation).
See the description of the \ref grpc_arg_keys "available args" for more
details. */
@@ -162,7 +162,8 @@
/** Maximum message length that the channel can receive. Int valued, bytes.
-1 means unlimited. */
#define GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH "grpc.max_receive_message_length"
-/** \deprecated For backward compatibility. */
+/** \deprecated For backward compatibility.
+ * Use GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH instead. */
#define GRPC_ARG_MAX_MESSAGE_LENGTH GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH
/** Maximum message length that the channel can send. Int valued, bytes.
-1 means unlimited. */
@@ -170,8 +171,8 @@
/** Maximum time that a channel may have no outstanding rpcs. Int valued,
milliseconds. INT_MAX means unlimited. */
#define GRPC_ARG_MAX_CONNECTION_IDLE_MS "grpc.max_connection_idle_ms"
-/** Maximum time that a channel may exist. Int valued, milliseconds. INT_MAX
- means unlimited. */
+/** Maximum time that a channel may exist. Int valued, milliseconds.
+ * INT_MAX means unlimited. */
#define GRPC_ARG_MAX_CONNECTION_AGE_MS "grpc.max_connection_age_ms"
/** Grace period after the chennel reaches its max age. Int valued,
milliseconds. INT_MAX means unlimited. */
@@ -182,7 +183,7 @@
/** Enable/disable support for deadline checking. Defaults to 1, unless
GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0 */
#define GRPC_ARG_ENABLE_DEADLINE_CHECKS "grpc.enable_deadline_checking"
-/** Initial sequence number for http2 transports. Int valued. */
+/** Initial stream ID for http2 transports. Int valued. */
#define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \
"grpc.http2.initial_sequence_number"
/** Amount to read ahead on individual streams. Defaults to 64kb, larger
@@ -197,27 +198,24 @@
#define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_ENCODER \
"grpc.http2.hpack_table_size.encoder"
/** How big a frame are we willing to receive via HTTP2.
- Min 16384, max 16777215.
- Larger values give lower CPU usage for large messages, but more head of line
- blocking for small messages. */
+ Min 16384, max 16777215. Larger values give lower CPU usage for large
+ messages, but more head of line blocking for small messages. */
#define GRPC_ARG_HTTP2_MAX_FRAME_SIZE "grpc.http2.max_frame_size"
/** Should BDP probing be performed? */
#define GRPC_ARG_HTTP2_BDP_PROBE "grpc.http2.bdp_probe"
/** Minimum time (in milliseconds) between successive ping frames being sent */
#define GRPC_ARG_HTTP2_MIN_TIME_BETWEEN_PINGS_MS \
"grpc.http2.min_time_between_pings_ms"
-/* Channel arg to override the http2 :scheme header */
+/** Channel arg to override the http2 :scheme header */
#define GRPC_ARG_HTTP2_SCHEME "grpc.http2_scheme"
/** How many pings can we send before needing to send a data frame or header
- frame?
- (0 indicates that an infinite number of pings can be sent without sending
- a data frame or header frame) */
+ frame? (0 indicates that an infinite number of pings can be sent without
+ sending a data frame or header frame) */
#define GRPC_ARG_HTTP2_MAX_PINGS_WITHOUT_DATA \
"grpc.http2.max_pings_without_data"
/** How many misbehaving pings the server can bear before sending goaway and
- closing the transport?
- (0 indicates that the server can bear an infinite number of misbehaving
- pings) */
+ closing the transport? (0 indicates that the server can bear an infinite
+ number of misbehaving pings) */
#define GRPC_ARG_HTTP2_MAX_PING_STRIKES "grpc.http2.max_ping_strikes"
/** Minimum allowed time between two pings without sending any data frame. Int
valued, seconds */
@@ -256,20 +254,22 @@
/** The time between the first and second connection attempts, in ms */
#define GRPC_ARG_INITIAL_RECONNECT_BACKOFF_MS \
"grpc.initial_reconnect_backoff_ms"
-/* The caller of the secure_channel_create functions may override the target
- name used for SSL host name checking using this channel argument which is of
- type \a GRPC_ARG_STRING. This *should* be used for testing only.
- If this argument is not specified, the name used for SSL host name checking
- will be the target parameter (assuming that the secure channel is an SSL
- channel). If this parameter is specified and the underlying is not an SSL
- channel, it will just be ignored. */
+/** This *should* be used for testing only.
+ The caller of the secure_channel_create functions may override the target
+ name used for SSL host name checking using this channel argument which is of
+ type \a GRPC_ARG_STRING. If this argument is not specified, the name used
+ for SSL host name checking will be the target parameter (assuming that the
+ secure channel is an SSL channel). If this parameter is specified and the
+ underlying is not an SSL channel, it will just be ignored. */
#define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"
-/* Maximum metadata size, in bytes. */
+/** Maximum metadata size, in bytes. Note this limit applies to the max sum of
+ all metadata key-value entries in a batch of headers. */
#define GRPC_ARG_MAX_METADATA_SIZE "grpc.max_metadata_size"
/** If non-zero, allow the use of SO_REUSEPORT if it's available (default 1) */
#define GRPC_ARG_ALLOW_REUSEPORT "grpc.so_reuseport"
-/** If non-zero, a pointer to a buffer pool (use grpc_resource_quota_arg_vtable
- to fetch an appropriate pointer arg vtable) */
+/** If non-zero, a pointer to a buffer pool (a pointer of type
+ * grpc_resource_quota*). (use grpc_resource_quota_arg_vtable() to fetch an
+ * appropriate pointer arg vtable) */
#define GRPC_ARG_RESOURCE_QUOTA "grpc.resource_quota"
/** If non-zero, expand wildcard addresses to a list of local addresses. */
#define GRPC_ARG_EXPAND_WILDCARD_ADDRS "grpc.expand_wildcard_addrs"
@@ -281,13 +281,16 @@
#define GRPC_ARG_SOCKET_MUTATOR "grpc.socket_mutator"
/** The grpc_socket_factory instance to create and bind sockets. A pointer. */
#define GRPC_ARG_SOCKET_FACTORY "grpc.socket_factory"
-/** If non-zero, Cronet transport will coalesce packets to fewer frames when
- * possible. */
+/** If non-zero, Cronet transport will coalesce packets to fewer frames
+ * when possible. */
#define GRPC_ARG_USE_CRONET_PACKET_COALESCING \
"grpc.use_cronet_packet_coalescing"
-/* Channel arg (integer) setting how large a slice to try and read from the wire
-each time recvmsg (or equivalent) is called */
+/** Channel arg (integer) setting how large a slice to try and read from the
+ wire each time recvmsg (or equivalent) is called **/
#define GRPC_ARG_TCP_READ_CHUNK_SIZE "grpc.experimental.tcp_read_chunk_size"
+/** Note this is not a "channel arg" key. This is the default slice size to use
+ * when trying to read from the wire if the GRPC_ARG_TCP_READ_CHUNK_SIZE
+ * channel arg is unspecified. */
#define GRPC_TCP_DEFAULT_READ_SLICE_SIZE 8192
#define GRPC_ARG_TCP_MIN_READ_CHUNK_SIZE \
"grpc.experimental.tcp_min_read_chunk_size"
@@ -331,8 +334,8 @@
GRPC_CALL_ERROR_INVALID_METADATA,
/** invalid message was passed to this call */
GRPC_CALL_ERROR_INVALID_MESSAGE,
- /** completion queue for notification has not been registered with the
- server */
+ /** completion queue for notification has not been registered
+ * with the server */
GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE,
/** this batch of operations leads to more operations than allowed */
GRPC_CALL_ERROR_BATCH_TOO_BIG,
@@ -340,12 +343,12 @@
GRPC_CALL_ERROR_PAYLOAD_TYPE_MISMATCH
} grpc_call_error;
-/* Default send/receive message size limits in bytes. -1 for unlimited. */
-/* TODO(roth) Make this match the default receive limit after next release */
+/** Default send/receive message size limits in bytes. -1 for unlimited. */
+/** TODO(roth) Make this match the default receive limit after next release */
#define GRPC_DEFAULT_MAX_SEND_MESSAGE_LENGTH -1
#define GRPC_DEFAULT_MAX_RECV_MESSAGE_LENGTH (4 * 1024 * 1024)
-/* Write Flags: */
+/** Write Flags: */
/** Hint that the write may be buffered and need not go out on the wire
immediately. GRPC is free to buffer the message until the next non-buffered
write, or until writes_done, but it need not buffer completely or at all. */
@@ -356,7 +359,7 @@
/** Mask of all valid flags. */
#define GRPC_WRITE_USED_MASK (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS)
-/* Initial metadata flags */
+/** Initial metadata flags */
/** Signal that the call is idempotent */
#define GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST (0x00000010u)
/** Signal that the call should not return UNAVAILABLE before it has started */
@@ -379,8 +382,8 @@
/** A single metadata element */
typedef struct grpc_metadata {
- /* the key, value values are expected to line up with grpc_mdelem: if changing
- them, update metadata.h at the same time. */
+ /** the key, value values are expected to line up with grpc_mdelem: if
+ changing them, update metadata.h at the same time. */
grpc_slice key;
grpc_slice value;
@@ -447,15 +450,13 @@
GRPC_OP_SEND_MESSAGE,
/** Send a close from the client: one and only one instance MUST be sent from
the client, unless the call was cancelled - in which case this can be
- skipped.
- This op completes after all bytes for the call (including the close)
- have passed outgoing flow control. */
+ skipped. This op completes after all bytes for the call
+ (including the close) have passed outgoing flow control. */
GRPC_OP_SEND_CLOSE_FROM_CLIENT,
/** Send status from the server: one and only one instance MUST be sent from
the server unless the call was cancelled - in which case this can be
- skipped.
- This op completes after all bytes for the call (including the status)
- have passed outgoing flow control. */
+ skipped. This op completes after all bytes for the call
+ (including the status) have passed outgoing flow control. */
GRPC_OP_SEND_STATUS_FROM_SERVER,
/** Receive initial metadata: one and only one MUST be made on the client,
must not be made on the server.
@@ -473,10 +474,10 @@
This op completes after all activity on the call has completed. */
GRPC_OP_RECV_STATUS_ON_CLIENT,
/** Receive close on the server: one and only one must be made on the
- server.
- This op completes after the close has been received by the server.
- This operation always succeeds, meaning ops paired with this operation
- will also appear to succeed, even though they may not have. */
+ server. This op completes after the close has been received by the
+ server. This operation always succeeds, meaning ops paired with
+ this operation will also appear to succeed, even though they may not
+ have. */
GRPC_OP_RECV_CLOSE_ON_SERVER
} grpc_op_type;
@@ -513,7 +514,7 @@
size_t trailing_metadata_count;
grpc_metadata *trailing_metadata;
grpc_status_code status;
- /* optional: set to NULL if no details need sending, non-NULL if they do
+ /** optional: set to NULL if no details need sending, non-NULL if they do
* pointer will not be retained past the start_batch call
*/
grpc_slice *status_details;
@@ -537,8 +538,7 @@
elements stays with the call object (ie key, value members are owned
by the call object, trailing_metadata->array is owned by the caller).
After the operation completes, call grpc_metadata_array_destroy on
- this
- value, or reuse it in a future op. */
+ this value, or reuse it in a future op. */
grpc_metadata_array *trailing_metadata;
grpc_status_code *status;
grpc_slice *status_details;
@@ -553,10 +553,10 @@
/** Information requested from the channel. */
typedef struct {
- /* If non-NULL, will be set to point to a string indicating the LB
+ /** If non-NULL, will be set to point to a string indicating the LB
* policy name. Caller takes ownership. */
char **lb_policy_name;
- /* If non-NULL, will be set to point to a string containing the
+ /** If non-NULL, will be set to point to a string containing the
* service config used by the channel in JSON form. */
char **service_config_json;
} grpc_channel_info;
@@ -600,9 +600,9 @@
#define GRPC_CQ_CURRENT_VERSION 1
typedef struct grpc_completion_queue_attributes {
- /* The version number of this structure. More fields might be added to this
+ /** The version number of this structure. More fields might be added to this
structure in future. */
- int version; /* Set to GRPC_CQ_CURRENT_VERSION */
+ int version; /** Set to GRPC_CQ_CURRENT_VERSION */
grpc_cq_completion_type cq_completion_type;
diff --git a/include/grpc/impl/codegen/propagation_bits.h b/include/grpc/impl/codegen/propagation_bits.h
index 4b64558..f58edb0 100644
--- a/include/grpc/impl/codegen/propagation_bits.h
+++ b/include/grpc/impl/codegen/propagation_bits.h
@@ -40,7 +40,7 @@
extern "C" {
#endif
-/* Propagation bits: this can be bitwise or-ed to form propagation_mask for
+/** Propagation bits: this can be bitwise or-ed to form propagation_mask for
* grpc_call */
/** Propagate deadline */
#define GRPC_PROPAGATE_DEADLINE ((uint32_t)1)
@@ -50,7 +50,7 @@
/** Propagate cancellation */
#define GRPC_PROPAGATE_CANCELLATION ((uint32_t)8)
-/* Default propagation mask: clients of the core API are encouraged to encode
+/** Default propagation mask: clients of the core API are encouraged to encode
deltas from this in their implementations... ie write:
GRPC_PROPAGATE_DEFAULTS & ~GRPC_PROPAGATE_DEADLINE to disable deadline
propagation. Doing so gives flexibility in the future to define new
diff --git a/include/grpc/impl/codegen/slice.h b/include/grpc/impl/codegen/slice.h
index b89a3f7..5c01c87 100644
--- a/include/grpc/impl/codegen/slice.h
+++ b/include/grpc/impl/codegen/slice.h
@@ -43,7 +43,7 @@
typedef struct grpc_slice grpc_slice;
-/* Slice API
+/** Slice API
A slice represents a contiguous reference counted array of bytes.
It is cheap to take references to a slice, and it is cheap to create a
@@ -63,14 +63,14 @@
uint32_t (*hash)(grpc_slice slice);
} grpc_slice_refcount_vtable;
-/* Reference count container for grpc_slice. Contains function pointers to
+/** Reference count container for grpc_slice. Contains function pointers to
increment and decrement reference counts. Implementations should cleanup
when the reference count drops to zero.
Typically client code should not touch this, and use grpc_slice_malloc,
grpc_slice_new, or grpc_slice_new_with_len instead. */
typedef struct grpc_slice_refcount {
const grpc_slice_refcount_vtable *vtable;
- /* If a subset of this slice is taken, use this pointer for the refcount.
+ /** If a subset of this slice is taken, use this pointer for the refcount.
Typically points back to the refcount itself, however iterning
implementations can use this to avoid a verification step on each hash
or equality check */
@@ -79,7 +79,7 @@
#define GRPC_SLICE_INLINED_SIZE (sizeof(size_t) + sizeof(uint8_t *) - 1)
-/* A grpc_slice s, if initialized, represents the byte range
+/** A grpc_slice s, if initialized, represents the byte range
s.bytes[0..s.length-1].
It can have an associated ref count which has a destruction routine to be run
@@ -104,23 +104,23 @@
#define GRPC_SLICE_BUFFER_INLINE_ELEMENTS 8
-/* Represents an expandable array of slices, to be interpreted as a
+/** Represents an expandable array of slices, to be interpreted as a
single item. */
typedef struct {
- /* This is for internal use only. External users (i.e any code outside grpc
+ /** This is for internal use only. External users (i.e any code outside grpc
* core) MUST NOT use this field */
grpc_slice *base_slices;
- /* slices in the array (Points to the first valid grpc_slice in the array) */
+ /** slices in the array (Points to the first valid grpc_slice in the array) */
grpc_slice *slices;
- /* the number of slices in the array */
+ /** the number of slices in the array */
size_t count;
- /* the number of slices allocated in the array. External users (i.e any code
+ /** the number of slices allocated in the array. External users (i.e any code
* outside grpc core) MUST NOT use this field */
size_t capacity;
- /* the combined length of all slices in the array */
+ /** the combined length of all slices in the array */
size_t length;
- /* inlined elements to avoid allocations */
+ /** inlined elements to avoid allocations */
grpc_slice inlined[GRPC_SLICE_BUFFER_INLINE_ELEMENTS];
} grpc_slice_buffer;
diff --git a/include/grpc/impl/codegen/status.h b/include/grpc/impl/codegen/status.h
index 29e4570..a2ad6b1 100644
--- a/include/grpc/impl/codegen/status.h
+++ b/include/grpc/impl/codegen/status.h
@@ -39,40 +39,40 @@
#endif
typedef enum {
- /* Not an error; returned on success */
+ /** Not an error; returned on success */
GRPC_STATUS_OK = 0,
- /* The operation was cancelled (typically by the caller). */
+ /** The operation was cancelled (typically by the caller). */
GRPC_STATUS_CANCELLED = 1,
- /* Unknown error. An example of where this error may be returned is
+ /** Unknown error. An example of where this error may be returned is
if a Status value received from another address space belongs to
an error-space that is not known in this address space. Also
errors raised by APIs that do not return enough error information
may be converted to this error. */
GRPC_STATUS_UNKNOWN = 2,
- /* Client specified an invalid argument. Note that this differs
+ /** Client specified an invalid argument. Note that this differs
from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments
that are problematic regardless of the state of the system
(e.g., a malformed file name). */
GRPC_STATUS_INVALID_ARGUMENT = 3,
- /* Deadline expired before operation could complete. For operations
+ /** Deadline expired before operation could complete. For operations
that change the state of the system, this error may be returned
even if the operation has completed successfully. For example, a
successful response from a server could have been delayed long
enough for the deadline to expire. */
GRPC_STATUS_DEADLINE_EXCEEDED = 4,
- /* Some requested entity (e.g., file or directory) was not found. */
+ /** Some requested entity (e.g., file or directory) was not found. */
GRPC_STATUS_NOT_FOUND = 5,
- /* Some entity that we attempted to create (e.g., file or directory)
+ /** Some entity that we attempted to create (e.g., file or directory)
already exists. */
GRPC_STATUS_ALREADY_EXISTS = 6,
- /* The caller does not have permission to execute the specified
+ /** The caller does not have permission to execute the specified
operation. PERMISSION_DENIED must not be used for rejections
caused by exhausting some resource (use RESOURCE_EXHAUSTED
instead for those errors). PERMISSION_DENIED must not be
@@ -80,15 +80,15 @@
instead for those errors). */
GRPC_STATUS_PERMISSION_DENIED = 7,
- /* The request does not have valid authentication credentials for the
+ /** The request does not have valid authentication credentials for the
operation. */
GRPC_STATUS_UNAUTHENTICATED = 16,
- /* Some resource has been exhausted, perhaps a per-user quota, or
+ /** Some resource has been exhausted, perhaps a per-user quota, or
perhaps the entire file system is out of space. */
GRPC_STATUS_RESOURCE_EXHAUSTED = 8,
- /* Operation was rejected because the system is not in a state
+ /** Operation was rejected because the system is not in a state
required for the operation's execution. For example, directory
to be deleted may be non-empty, an rmdir operation is applied to
a non-directory, etc.
@@ -109,14 +109,14 @@
read-modify-write on the same resource. */
GRPC_STATUS_FAILED_PRECONDITION = 9,
- /* The operation was aborted, typically due to a concurrency issue
+ /** The operation was aborted, typically due to a concurrency issue
like sequencer check failures, transaction aborts, etc.
See litmus test above for deciding between FAILED_PRECONDITION,
ABORTED, and UNAVAILABLE. */
GRPC_STATUS_ABORTED = 10,
- /* Operation was attempted past the valid range. E.g., seeking or
+ /** Operation was attempted past the valid range. E.g., seeking or
reading past end of file.
Unlike INVALID_ARGUMENT, this error indicates a problem that may
@@ -133,26 +133,31 @@
they are done. */
GRPC_STATUS_OUT_OF_RANGE = 11,
- /* Operation is not implemented or not supported/enabled in this service. */
+ /** Operation is not implemented or not supported/enabled in this service. */
GRPC_STATUS_UNIMPLEMENTED = 12,
- /* Internal errors. Means some invariants expected by underlying
+ /** Internal errors. Means some invariants expected by underlying
system has been broken. If you see one of these errors,
something is very broken. */
GRPC_STATUS_INTERNAL = 13,
- /* The service is currently unavailable. This is a most likely a
+ /** The service is currently unavailable. This is a most likely a
transient condition and may be corrected by retrying with
a backoff.
+ WARNING: Although data MIGHT not have been transmitted when this
+ status occurs, there is NOT A GUARANTEE that the server has not seen
+ anything. So in general it is unsafe to retry on this status code
+ if the call is non-idempotent.
+
See litmus test above for deciding between FAILED_PRECONDITION,
ABORTED, and UNAVAILABLE. */
GRPC_STATUS_UNAVAILABLE = 14,
- /* Unrecoverable data loss or corruption. */
+ /** Unrecoverable data loss or corruption. */
GRPC_STATUS_DATA_LOSS = 15,
- /* Force users to include a default branch: */
+ /** Force users to include a default branch: */
GRPC_STATUS__DO_NOT_USE = -1
} grpc_status_code;
diff --git a/include/grpc/impl/codegen/sync.h b/include/grpc/impl/codegen/sync.h
index 6a8e8a6..5a135fa 100644
--- a/include/grpc/impl/codegen/sync.h
+++ b/include/grpc/impl/codegen/sync.h
@@ -33,7 +33,7 @@
#ifndef GRPC_IMPL_CODEGEN_SYNC_H
#define GRPC_IMPL_CODEGEN_SYNC_H
-/* Synchronization primitives for GPR.
+/** Synchronization primitives for GPR.
The type gpr_mu provides a non-reentrant mutex (lock).
diff --git a/include/grpc/slice.h b/include/grpc/slice.h
index 9c4b158..19f546a 100644
--- a/include/grpc/slice.h
+++ b/include/grpc/slice.h
@@ -41,11 +41,11 @@
extern "C" {
#endif
-/* Increment the refcount of s. Requires slice is initialized.
+/** Increment the refcount of s. Requires slice is initialized.
Returns s. */
GPRAPI grpc_slice grpc_slice_ref(grpc_slice s);
-/* Decrement the ref count of s. If the ref count of s reaches zero, all
+/** Decrement the ref count of s. If the ref count of s reaches zero, all
slices sharing the ref count are destroyed, and considered no longer
initialized. If s is ultimately derived from a call to grpc_slice_new(start,
len, dest) where dest!=NULL , then (*dest)(start) is called, else if s is
@@ -53,15 +53,15 @@
where dest!=NULL , then (*dest)(start, len). Requires s initialized. */
GPRAPI void grpc_slice_unref(grpc_slice s);
-/* Copy slice - create a new slice that contains the same data as s */
+/** Copy slice - create a new slice that contains the same data as s */
GPRAPI grpc_slice grpc_slice_copy(grpc_slice s);
-/* Create a slice pointing at some data. Calls malloc to allocate a refcount
+/** Create a slice pointing at some data. Calls malloc to allocate a refcount
for the object, and arranges that destroy will be called with the pointer
passed in at destruction. */
GPRAPI grpc_slice grpc_slice_new(void *p, size_t len, void (*destroy)(void *));
-/* Equivalent to grpc_slice_new, but with a separate pointer that is
+/** Equivalent to grpc_slice_new, but with a separate pointer that is
passed to the destroy function. This function can be useful when
the data is part of a larger structure that must be destroyed when
the data is no longer needed. */
@@ -69,12 +69,12 @@
void (*destroy)(void *),
void *user_data);
-/* Equivalent to grpc_slice_new, but with a two argument destroy function that
+/** Equivalent to grpc_slice_new, but with a two argument destroy function that
also takes the slice length. */
GPRAPI grpc_slice grpc_slice_new_with_len(void *p, size_t len,
void (*destroy)(void *, size_t));
-/* Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc()
+/** Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc()
call.
Aborts if malloc() fails. */
GPRAPI grpc_slice grpc_slice_malloc(size_t length);
@@ -86,13 +86,13 @@
.data.inlined = {.length = (uint8_t)(len)}} \
: grpc_slice_malloc_large((len)))
-/* Intern a slice:
+/** Intern a slice:
The return value for two invocations of this function with the same sequence
of bytes is a slice which points to the same memory. */
GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice);
-/* Create a slice by copying a string.
+/** Create a slice by copying a string.
Does not preserve null terminators.
Equivalent to:
size_t len = strlen(source);
@@ -100,29 +100,29 @@
memcpy(slice->data, source, len); */
GPRAPI grpc_slice grpc_slice_from_copied_string(const char *source);
-/* Create a slice by copying a buffer.
+/** Create a slice by copying a buffer.
Equivalent to:
grpc_slice slice = grpc_slice_malloc(len);
memcpy(slice->data, source, len); */
GPRAPI grpc_slice grpc_slice_from_copied_buffer(const char *source, size_t len);
-/* Create a slice pointing to constant memory */
+/** Create a slice pointing to constant memory */
GPRAPI grpc_slice grpc_slice_from_static_string(const char *source);
-/* Create a slice pointing to constant memory */
+/** Create a slice pointing to constant memory */
GPRAPI grpc_slice grpc_slice_from_static_buffer(const void *source, size_t len);
-/* Return a result slice derived from s, which shares a ref count with \a s,
+/** Return a result slice derived from s, which shares a ref count with \a s,
where result.data==s.data+begin, and result.length==end-begin. The ref count
of \a s is increased by one. Do not assign result back to \a s.
Requires s initialized, begin <= end, begin <= s.length, and
end <= source->length. */
GPRAPI grpc_slice grpc_slice_sub(grpc_slice s, size_t begin, size_t end);
-/* The same as grpc_slice_sub, but without altering the ref count */
+/** The same as grpc_slice_sub, but without altering the ref count */
GPRAPI grpc_slice grpc_slice_sub_no_ref(grpc_slice s, size_t begin, size_t end);
-/* Splits s into two: modifies s to be s[0:split], and returns a new slice,
+/** Splits s into two: modifies s to be s[0:split], and returns a new slice,
sharing a refcount with s, that contains s[split:s.length].
Requires s intialized, split <= s.length */
GPRAPI grpc_slice grpc_slice_split_tail(grpc_slice *s, size_t split);
@@ -133,13 +133,13 @@
GRPC_SLICE_REF_BOTH = 1 + 2
} grpc_slice_ref_whom;
-/* The same as grpc_slice_split_tail, but with an option to skip altering
+/** The same as grpc_slice_split_tail, but with an option to skip altering
* refcounts (grpc_slice_split_tail_maybe_ref(..., true) is equivalent to
* grpc_slice_split_tail(...)) */
GPRAPI grpc_slice grpc_slice_split_tail_maybe_ref(grpc_slice *s, size_t split,
grpc_slice_ref_whom ref_whom);
-/* Splits s into two: modifies s to be s[split:s.length], and returns a new
+/** Splits s into two: modifies s to be s[split:s.length], and returns a new
slice, sharing a refcount with s, that contains s[0:split].
Requires s intialized, split <= s.length */
GPRAPI grpc_slice grpc_slice_split_head(grpc_slice *s, size_t split);
@@ -151,35 +151,35 @@
GPRAPI int grpc_slice_eq(grpc_slice a, grpc_slice b);
-/* Returns <0 if a < b, ==0 if a == b, >0 if a > b
+/** Returns <0 if a < b, ==0 if a == b, >0 if a > b
The order is arbitrary, and is not guaranteed to be stable across different
versions of the API. */
GPRAPI int grpc_slice_cmp(grpc_slice a, grpc_slice b);
GPRAPI int grpc_slice_str_cmp(grpc_slice a, const char *b);
GPRAPI int grpc_slice_buf_cmp(grpc_slice a, const void *b, size_t blen);
-/* return non-zero if the first blen bytes of a are equal to b */
+/** return non-zero if the first blen bytes of a are equal to b */
GPRAPI int grpc_slice_buf_start_eq(grpc_slice a, const void *b, size_t blen);
-/* return the index of the last instance of \a c in \a s, or -1 if not found */
+/** return the index of the last instance of \a c in \a s, or -1 if not found */
GPRAPI int grpc_slice_rchr(grpc_slice s, char c);
GPRAPI int grpc_slice_chr(grpc_slice s, char c);
-/* return the index of the first occurance of \a needle in \a haystack, or -1 if
- * it's not found */
+/** return the index of the first occurance of \a needle in \a haystack, or -1
+ if it's not found */
GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle);
GPRAPI uint32_t grpc_slice_hash(grpc_slice s);
-/* Do two slices point at the same memory, with the same length
+/** Do two slices point at the same memory, with the same length
If a or b is inlined, actually compares data */
GPRAPI int grpc_slice_is_equivalent(grpc_slice a, grpc_slice b);
-/* Return a slice pointing to newly allocated memory that has the same contents
+/** Return a slice pointing to newly allocated memory that has the same contents
* as \a s */
GPRAPI grpc_slice grpc_slice_dup(grpc_slice a);
-/* Return a copy of slice as a C string. Offers no protection against embedded
+/** Return a copy of slice as a C string. Offers no protection against embedded
NULL's. Returned string must be freed with gpr_free. */
GPRAPI char *grpc_slice_to_c_string(grpc_slice s);
diff --git a/include/grpc/slice_buffer.h b/include/grpc/slice_buffer.h
index cdbd747..0d59395 100644
--- a/include/grpc/slice_buffer.h
+++ b/include/grpc/slice_buffer.h
@@ -40,15 +40,15 @@
extern "C" {
#endif
-/* initialize a slice buffer */
+/** initialize a slice buffer */
GPRAPI void grpc_slice_buffer_init(grpc_slice_buffer *sb);
-/* destroy a slice buffer - unrefs any held elements */
+/** destroy a slice buffer - unrefs any held elements */
GPRAPI void grpc_slice_buffer_destroy(grpc_slice_buffer *sb);
-/* Add an element to a slice buffer - takes ownership of the slice.
+/** Add an element to a slice buffer - takes ownership of the slice.
This function is allowed to concatenate the passed in slice to the end of
some other slice if desired by the slice buffer. */
GPRAPI void grpc_slice_buffer_add(grpc_slice_buffer *sb, grpc_slice slice);
-/* add an element to a slice buffer - takes ownership of the slice and returns
+/** add an element to a slice buffer - takes ownership of the slice and returns
the index of the slice.
Guarantees that the slice will not be concatenated at the end of another
slice (i.e. the data for this slice will begin at the first byte of the
@@ -59,35 +59,35 @@
grpc_slice slice);
GPRAPI void grpc_slice_buffer_addn(grpc_slice_buffer *sb, grpc_slice *slices,
size_t n);
-/* add a very small (less than 8 bytes) amount of data to the end of a slice
+/** add a very small (less than 8 bytes) amount of data to the end of a slice
buffer: returns a pointer into which to add the data */
GPRAPI uint8_t *grpc_slice_buffer_tiny_add(grpc_slice_buffer *sb, size_t len);
-/* pop the last buffer, but don't unref it */
+/** pop the last buffer, but don't unref it */
GPRAPI void grpc_slice_buffer_pop(grpc_slice_buffer *sb);
-/* clear a slice buffer, unref all elements */
+/** clear a slice buffer, unref all elements */
GPRAPI void grpc_slice_buffer_reset_and_unref(grpc_slice_buffer *sb);
-/* swap the contents of two slice buffers */
+/** swap the contents of two slice buffers */
GPRAPI void grpc_slice_buffer_swap(grpc_slice_buffer *a, grpc_slice_buffer *b);
-/* move all of the elements of src into dst */
+/** move all of the elements of src into dst */
GPRAPI void grpc_slice_buffer_move_into(grpc_slice_buffer *src,
grpc_slice_buffer *dst);
-/* remove n bytes from the end of a slice buffer */
+/** remove n bytes from the end of a slice buffer */
GPRAPI void grpc_slice_buffer_trim_end(grpc_slice_buffer *src, size_t n,
grpc_slice_buffer *garbage);
-/* move the first n bytes of src into dst */
+/** move the first n bytes of src into dst */
GPRAPI void grpc_slice_buffer_move_first(grpc_slice_buffer *src, size_t n,
grpc_slice_buffer *dst);
-/* move the first n bytes of src into dst without adding references */
+/** move the first n bytes of src into dst without adding references */
GPRAPI void grpc_slice_buffer_move_first_no_ref(grpc_slice_buffer *src,
size_t n,
grpc_slice_buffer *dst);
-/* move the first n bytes of src into dst (copying them) */
+/** move the first n bytes of src into dst (copying them) */
GPRAPI void grpc_slice_buffer_move_first_into_buffer(grpc_exec_ctx *exec_ctx,
grpc_slice_buffer *src,
size_t n, void *dst);
-/* take the first slice in the slice buffer */
+/** take the first slice in the slice buffer */
GPRAPI grpc_slice grpc_slice_buffer_take_first(grpc_slice_buffer *src);
-/* undo the above with (a possibly different) \a slice */
+/** undo the above with (a possibly different) \a slice */
GPRAPI void grpc_slice_buffer_undo_take_first(grpc_slice_buffer *src,
grpc_slice slice);
diff --git a/include/grpc/support/alloc.h b/include/grpc/support/alloc.h
index 017d75a..99be2d1 100644
--- a/include/grpc/support/alloc.h
+++ b/include/grpc/support/alloc.h
@@ -44,26 +44,26 @@
typedef struct gpr_allocation_functions {
void *(*malloc_fn)(size_t size);
- void *(*zalloc_fn)(size_t size); /* if NULL, uses malloc_fn then memset */
+ void *(*zalloc_fn)(size_t size); /** if NULL, uses malloc_fn then memset */
void *(*realloc_fn)(void *ptr, size_t size);
void (*free_fn)(void *ptr);
} gpr_allocation_functions;
-/* malloc.
+/** malloc.
* If size==0, always returns NULL. Otherwise this function never returns NULL.
* The pointer returned is suitably aligned for any kind of variable it could
* contain.
*/
GPRAPI void *gpr_malloc(size_t size);
-/* like malloc, but zero all bytes before returning them */
+/** like malloc, but zero all bytes before returning them */
GPRAPI void *gpr_zalloc(size_t size);
-/* free */
+/** free */
GPRAPI void gpr_free(void *ptr);
-/* realloc, never returns NULL */
+/** realloc, never returns NULL */
GPRAPI void *gpr_realloc(void *p, size_t size);
-/* aligned malloc, never returns NULL, will align to 1 << alignment_log */
+/** aligned malloc, never returns NULL, will align to 1 << alignment_log */
GPRAPI void *gpr_malloc_aligned(size_t size, size_t alignment_log);
-/* free memory allocated by gpr_malloc_aligned */
+/** free memory allocated by gpr_malloc_aligned */
GPRAPI void gpr_free_aligned(void *ptr);
/** Request the family of allocation functions in \a functions be used. NOTE
diff --git a/include/grpc/support/cmdline.h b/include/grpc/support/cmdline.h
index 5b7bc82..5a83afb 100644
--- a/include/grpc/support/cmdline.h
+++ b/include/grpc/support/cmdline.h
@@ -40,7 +40,7 @@
extern "C" {
#endif
-/* Simple command line parser.
+/** Simple command line parser.
Supports flags that can be specified as -foo, --foo, --no-foo, -no-foo, etc
And integers, strings that can be specified as -foo=4, -foo blah, etc
@@ -68,32 +68,32 @@
typedef struct gpr_cmdline gpr_cmdline;
-/* Construct a command line parser: takes a short description of the tool
+/** Construct a command line parser: takes a short description of the tool
doing the parsing */
GPRAPI gpr_cmdline *gpr_cmdline_create(const char *description);
-/* Add an integer parameter, with a name (used on the command line) and some
+/** Add an integer parameter, with a name (used on the command line) and some
helpful text (used in the command usage) */
GPRAPI void gpr_cmdline_add_int(gpr_cmdline *cl, const char *name,
const char *help, int *value);
-/* The same, for a boolean flag */
+/** The same, for a boolean flag */
GPRAPI void gpr_cmdline_add_flag(gpr_cmdline *cl, const char *name,
const char *help, int *value);
-/* And for a string */
+/** And for a string */
GPRAPI void gpr_cmdline_add_string(gpr_cmdline *cl, const char *name,
const char *help, char **value);
-/* Set a callback for non-named arguments */
+/** Set a callback for non-named arguments */
GPRAPI void gpr_cmdline_on_extra_arg(
gpr_cmdline *cl, const char *name, const char *help,
void (*on_extra_arg)(void *user_data, const char *arg), void *user_data);
-/* Enable surviving failure: default behavior is to exit the process */
+/** Enable surviving failure: default behavior is to exit the process */
GPRAPI void gpr_cmdline_set_survive_failure(gpr_cmdline *cl);
-/* Parse the command line; returns 1 on success, on failure either dies
+/** Parse the command line; returns 1 on success, on failure either dies
(by default) or returns 0 if gpr_cmdline_set_survive_failure() has been
called */
GPRAPI int gpr_cmdline_parse(gpr_cmdline *cl, int argc, char **argv);
-/* Destroy the parser */
+/** Destroy the parser */
GPRAPI void gpr_cmdline_destroy(gpr_cmdline *cl);
-/* Get a string describing usage */
+/** Get a string describing usage */
GPRAPI char *gpr_cmdline_usage_string(gpr_cmdline *cl, const char *argv0);
#ifdef __cplusplus
diff --git a/include/grpc/support/cpu.h b/include/grpc/support/cpu.h
index 6734feb..0da02ad 100644
--- a/include/grpc/support/cpu.h
+++ b/include/grpc/support/cpu.h
@@ -40,13 +40,13 @@
extern "C" {
#endif
-/* Interface providing CPU information for currently running system */
+/** Interface providing CPU information for currently running system */
-/* Return the number of CPU cores on the current system. Will return 0 if
+/** Return the number of CPU cores on the current system. Will return 0 if
the information is not available. */
GPRAPI unsigned gpr_cpu_num_cores(void);
-/* Return the CPU on which the current thread is executing; N.B. This should
+/** Return the CPU on which the current thread is executing; N.B. This should
be considered advisory only - it is possible that the thread is switched
to a different CPU at any time. Returns a value in range
[0, gpr_cpu_num_cores() - 1] */
diff --git a/include/grpc/support/histogram.h b/include/grpc/support/histogram.h
index c545038..96db758 100644
--- a/include/grpc/support/histogram.h
+++ b/include/grpc/support/histogram.h
@@ -48,7 +48,7 @@
GPRAPI void gpr_histogram_destroy(gpr_histogram *h);
GPRAPI void gpr_histogram_add(gpr_histogram *h, double x);
-/* The following merges the second histogram into the first. It only works
+/** The following merges the second histogram into the first. It only works
if they have the same buckets and resolution. Returns 0 on failure, 1
on success */
GPRAPI int gpr_histogram_merge(gpr_histogram *dst, const gpr_histogram *src);
diff --git a/include/grpc/support/host_port.h b/include/grpc/support/host_port.h
index 1581954..ee786be 100644
--- a/include/grpc/support/host_port.h
+++ b/include/grpc/support/host_port.h
@@ -40,7 +40,7 @@
extern "C" {
#endif
-/* Given a host and port, creates a newly-allocated string of the form
+/** Given a host and port, creates a newly-allocated string of the form
"host:port" or "[ho:st]:port", depending on whether the host contains colons
like an IPv6 literal. If the host is already bracketed, then additional
brackets will not be added.
@@ -52,7 +52,7 @@
In the unlikely event of an error, returns -1 and sets *out to NULL. */
GPRAPI int gpr_join_host_port(char **out, const char *host, int port);
-/* Given a name in the form "host:port" or "[ho:st]:port", split into hostname
+/** Given a name in the form "host:port" or "[ho:st]:port", split into hostname
and port number, into newly allocated strings, which must later be
destroyed using gpr_free().
Return 1 on success, 0 on failure. Guarantees *host and *port == NULL on
diff --git a/include/grpc/support/log.h b/include/grpc/support/log.h
index 88346cc..917b011 100644
--- a/include/grpc/support/log.h
+++ b/include/grpc/support/log.h
@@ -44,7 +44,7 @@
extern "C" {
#endif
-/* GPR log API.
+/** GPR log API.
Usage (within grpc):
@@ -54,7 +54,7 @@
gpr_log(GPR_INFO, "hello world");
gpr_log(GPR_ERROR, "%d %s!!", argument1, argument2); */
-/* The severity of a log message - use the #defines below when calling into
+/** The severity of a log message - use the #defines below when calling into
gpr_log to additionally supply file and line data */
typedef enum gpr_log_severity {
GPR_LOG_SEVERITY_DEBUG,
@@ -64,15 +64,15 @@
#define GPR_LOG_VERBOSITY_UNSET -1
-/* Returns a string representation of the log severity */
+/** Returns a string representation of the log severity */
const char *gpr_log_severity_string(gpr_log_severity severity);
-/* Macros to build log contexts at various severity levels */
+/** Macros to build log contexts at various severity levels */
#define GPR_DEBUG __FILE__, __LINE__, GPR_LOG_SEVERITY_DEBUG
#define GPR_INFO __FILE__, __LINE__, GPR_LOG_SEVERITY_INFO
#define GPR_ERROR __FILE__, __LINE__, GPR_LOG_SEVERITY_ERROR
-/* Log a message. It's advised to use GPR_xxx above to generate the context
+/** Log a message. It's advised to use GPR_xxx above to generate the context
* for each message */
GPRAPI void gpr_log(const char *file, int line, gpr_log_severity severity,
const char *format, ...) GPR_PRINT_FORMAT_CHECK(4, 5);
@@ -80,12 +80,12 @@
GPRAPI void gpr_log_message(const char *file, int line,
gpr_log_severity severity, const char *message);
-/* Set global log verbosity */
+/** Set global log verbosity */
GPRAPI void gpr_set_log_verbosity(gpr_log_severity min_severity_to_print);
GPRAPI void gpr_log_verbosity_init();
-/* Log overrides: applications can use this API to intercept logging calls
+/** Log overrides: applications can use this API to intercept logging calls
and use their own implementations */
typedef struct {
@@ -98,7 +98,7 @@
typedef void (*gpr_log_func)(gpr_log_func_args *args);
GPRAPI void gpr_set_log_function(gpr_log_func func);
-/* abort() the process if x is zero, having written a line to the log.
+/** abort() the process if x is zero, having written a line to the log.
Intended for internal invariants. If the error can be recovered from,
without the possibility of corruption, or might best be reflected via
diff --git a/include/grpc/support/log_windows.h b/include/grpc/support/log_windows.h
index 943a8e9..b8a4078 100644
--- a/include/grpc/support/log_windows.h
+++ b/include/grpc/support/log_windows.h
@@ -40,7 +40,7 @@
extern "C" {
#endif
-/* Returns a string allocated with gpr_malloc that contains a UTF-8
+/** Returns a string allocated with gpr_malloc that contains a UTF-8
* formatted error message, corresponding to the error messageid.
* Use in conjunction with GetLastError() et al.
*/
diff --git a/include/grpc/support/string_util.h b/include/grpc/support/string_util.h
index 5ab983d..8b268a6 100644
--- a/include/grpc/support/string_util.h
+++ b/include/grpc/support/string_util.h
@@ -40,13 +40,13 @@
extern "C" {
#endif
-/* String utility functions */
+/** String utility functions */
-/* Returns a copy of src that can be passed to gpr_free().
+/** Returns a copy of src that can be passed to gpr_free().
If allocation fails or if src is NULL, returns NULL. */
GPRAPI char *gpr_strdup(const char *src);
-/* printf to a newly-allocated string. The set of supported formats may vary
+/** printf to a newly-allocated string. The set of supported formats may vary
between platforms.
On success, returns the number of bytes printed (excluding the final '\0'),
diff --git a/include/grpc/support/subprocess.h b/include/grpc/support/subprocess.h
index 2baa43e..dfb8098 100644
--- a/include/grpc/support/subprocess.h
+++ b/include/grpc/support/subprocess.h
@@ -42,13 +42,13 @@
typedef struct gpr_subprocess gpr_subprocess;
-/* .exe on windows, empty on unices */
+/** .exe on windows, empty on unices */
GPRAPI const char *gpr_subprocess_binary_extension();
GPRAPI gpr_subprocess *gpr_subprocess_create(int argc, const char **argv);
-/* if subprocess has not been joined, kill it */
+/** if subprocess has not been joined, kill it */
GPRAPI void gpr_subprocess_destroy(gpr_subprocess *p);
-/* returns exit status; can be called at most once */
+/** returns exit status; can be called at most once */
GPRAPI int gpr_subprocess_join(gpr_subprocess *p);
GPRAPI void gpr_subprocess_interrupt(gpr_subprocess *p);
diff --git a/include/grpc/support/sync.h b/include/grpc/support/sync.h
index 5cfeecb..7d727a0 100644
--- a/include/grpc/support/sync.h
+++ b/include/grpc/support/sync.h
@@ -41,49 +41,49 @@
extern "C" {
#endif
-/* --- Mutex interface ---
+/** --- Mutex interface ---
At most one thread may hold an exclusive lock on a mutex at any given time.
Actions taken by a thread that holds a mutex exclusively happen after
actions taken by all previous holders of the mutex. Variables of type
gpr_mu are uninitialized when first declared. */
-/* Initialize *mu. Requires: *mu uninitialized. */
+/** Initialize *mu. Requires: *mu uninitialized. */
GPRAPI void gpr_mu_init(gpr_mu *mu);
-/* Cause *mu no longer to be initialized, freeing any memory in use. Requires:
+/** Cause *mu no longer to be initialized, freeing any memory in use. Requires:
*mu initialized; no other concurrent operation on *mu. */
GPRAPI void gpr_mu_destroy(gpr_mu *mu);
-/* Wait until no thread has a lock on *mu, cause the calling thread to own an
+/** Wait until no thread has a lock on *mu, cause the calling thread to own an
exclusive lock on *mu, then return. May block indefinitely or crash if the
calling thread has a lock on *mu. Requires: *mu initialized. */
GPRAPI void gpr_mu_lock(gpr_mu *mu);
-/* Release an exclusive lock on *mu held by the calling thread. Requires: *mu
+/** Release an exclusive lock on *mu held by the calling thread. Requires: *mu
initialized; the calling thread holds an exclusive lock on *mu. */
GPRAPI void gpr_mu_unlock(gpr_mu *mu);
-/* Without blocking, attempt to acquire an exclusive lock on *mu for the
+/** Without blocking, attempt to acquire an exclusive lock on *mu for the
calling thread, then return non-zero iff success. Fail, if any thread holds
the lock; succeeds with high probability if no thread holds the lock.
Requires: *mu initialized. */
GPRAPI int gpr_mu_trylock(gpr_mu *mu);
-/* --- Condition variable interface ---
+/** --- Condition variable interface ---
A while-loop should be used with gpr_cv_wait() when waiting for conditions
to become true. See the example below. Variables of type gpr_cv are
uninitialized when first declared. */
-/* Initialize *cv. Requires: *cv uninitialized. */
+/** Initialize *cv. Requires: *cv uninitialized. */
GPRAPI void gpr_cv_init(gpr_cv *cv);
-/* Cause *cv no longer to be initialized, freeing any memory in use. Requires:
+/** Cause *cv no longer to be initialized, freeing any memory in use. Requires:
*cv initialized; no other concurrent operation on *cv.*/
GPRAPI void gpr_cv_destroy(gpr_cv *cv);
-/* Atomically release *mu and wait on *cv. When the calling thread is woken
+/** Atomically release *mu and wait on *cv. When the calling thread is woken
from *cv or the deadline abs_deadline is exceeded, execute gpr_mu_lock(mu)
and return whether the deadline was exceeded. Use
abs_deadline==gpr_inf_future for no deadline. abs_deadline can be either
@@ -92,83 +92,83 @@
holds an exclusive lock on *mu. */
GPRAPI int gpr_cv_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline);
-/* If any threads are waiting on *cv, wake at least one.
+/** If any threads are waiting on *cv, wake at least one.
Clients may treat this as an optimization of gpr_cv_broadcast()
for use in the case where waking more than one waiter is not useful.
Requires: *cv initialized. */
GPRAPI void gpr_cv_signal(gpr_cv *cv);
-/* Wake all threads waiting on *cv. Requires: *cv initialized. */
+/** Wake all threads waiting on *cv. Requires: *cv initialized. */
GPRAPI void gpr_cv_broadcast(gpr_cv *cv);
-/* --- One-time initialization ---
+/** --- One-time initialization ---
gpr_once must be declared with static storage class, and initialized with
GPR_ONCE_INIT. e.g.,
static gpr_once once_var = GPR_ONCE_INIT; */
-/* Ensure that (*init_routine)() has been called exactly once (for the
+/** Ensure that (*init_routine)() has been called exactly once (for the
specified gpr_once instance) and then return.
If multiple threads call gpr_once() on the same gpr_once instance, one of
them will call (*init_routine)(), and the others will block until that call
finishes.*/
GPRAPI void gpr_once_init(gpr_once *once, void (*init_routine)(void));
-/* --- One-time event notification ---
+/** --- One-time event notification ---
These operations act on a gpr_event, which should be initialized with
gpr_ev_init(), or with GPR_EVENT_INIT if static, e.g.,
static gpr_event event_var = GPR_EVENT_INIT;
It requires no destruction. */
-/* Initialize *ev. */
+/** Initialize *ev. */
GPRAPI void gpr_event_init(gpr_event *ev);
-/* Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
+/** Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
Requires: *ev initialized; value != NULL; no prior or concurrent calls to
gpr_event_set(ev, ...) since initialization. */
GPRAPI void gpr_event_set(gpr_event *ev, void *value);
-/* Return the value set by gpr_event_set(ev, ...), or NULL if no such call has
+/** Return the value set by gpr_event_set(ev, ...), or NULL if no such call has
completed. If the result is non-NULL, all operations that occurred prior to
the gpr_event_set(ev, ...) set will be visible after this call returns.
Requires: *ev initialized. This operation is faster than acquiring a mutex
on most platforms. */
GPRAPI void *gpr_event_get(gpr_event *ev);
-/* Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is
+/** Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is
exceeded, then return gpr_event_get(ev). Requires: *ev initialized. Use
abs_deadline==gpr_inf_future for no deadline. When the event has been
signalled before the call, this operation is faster than acquiring a mutex
on most platforms. */
GPRAPI void *gpr_event_wait(gpr_event *ev, gpr_timespec abs_deadline);
-/* --- Reference counting ---
+/** --- Reference counting ---
These calls act on the type gpr_refcount. It requires no destruction. */
-/* Initialize *r to value n. */
+/** Initialize *r to value n. */
GPRAPI void gpr_ref_init(gpr_refcount *r, int n);
-/* Increment the reference count *r. Requires *r initialized. */
+/** Increment the reference count *r. Requires *r initialized. */
GPRAPI void gpr_ref(gpr_refcount *r);
-/* Increment the reference count *r. Requires *r initialized.
+/** Increment the reference count *r. Requires *r initialized.
Crashes if refcount is zero */
GPRAPI void gpr_ref_non_zero(gpr_refcount *r);
-/* Increment the reference count *r by n. Requires *r initialized, n > 0. */
+/** Increment the reference count *r by n. Requires *r initialized, n > 0. */
GPRAPI void gpr_refn(gpr_refcount *r, int n);
-/* Decrement the reference count *r and return non-zero iff it has reached
+/** Decrement the reference count *r and return non-zero iff it has reached
zero. . Requires *r initialized. */
GPRAPI int gpr_unref(gpr_refcount *r);
-/* Return non-zero iff the reference count of *r is one, and thus is owned
+/** Return non-zero iff the reference count of *r is one, and thus is owned
by exactly one object. */
GPRAPI int gpr_ref_is_unique(gpr_refcount *r);
-/* --- Stats counters ---
+/** --- Stats counters ---
These calls act on the integral type gpr_stats_counter. It requires no
destruction. Static instances may be initialized with
@@ -176,16 +176,16 @@
Beware: These operations do not imply memory barriers. Do not use them to
synchronize other events. */
-/* Initialize *c to the value n. */
+/** Initialize *c to the value n. */
GPRAPI void gpr_stats_init(gpr_stats_counter *c, intptr_t n);
-/* *c += inc. Requires: *c initialized. */
+/** *c += inc. Requires: *c initialized. */
GPRAPI void gpr_stats_inc(gpr_stats_counter *c, intptr_t inc);
-/* Return *c. Requires: *c initialized. */
+/** Return *c. Requires: *c initialized. */
GPRAPI intptr_t gpr_stats_read(const gpr_stats_counter *c);
-/* ==================Example use of interface===================
+/** ==================Example use of interface===================
A producer-consumer queue of up to N integers,
illustrating the use of the calls in this interface. */
#if 0
diff --git a/include/grpc/support/thd.h b/include/grpc/support/thd.h
index 0514288..ba6cbb0 100644
--- a/include/grpc/support/thd.h
+++ b/include/grpc/support/thd.h
@@ -33,7 +33,7 @@
#ifndef GRPC_SUPPORT_THD_H
#define GRPC_SUPPORT_THD_H
-/* Thread interface for GPR.
+/** Thread interface for GPR.
Types
gpr_thd_id a thread identifier.
@@ -50,37 +50,37 @@
typedef uintptr_t gpr_thd_id;
-/* Thread creation options. */
+/** Thread creation options. */
typedef struct {
- int flags; /* Opaque field. Get and set with accessors below. */
+ int flags; /** Opaque field. Get and set with accessors below. */
} gpr_thd_options;
-/* Create a new thread running (*thd_body)(arg) and place its thread identifier
+/** Create a new thread running (*thd_body)(arg) and place its thread identifier
in *t, and return true. If there are insufficient resources, return false.
If options==NULL, default options are used.
The thread is immediately runnable, and exits when (*thd_body)() returns. */
GPRAPI int gpr_thd_new(gpr_thd_id *t, void (*thd_body)(void *arg), void *arg,
const gpr_thd_options *options);
-/* Return a gpr_thd_options struct with all fields set to defaults. */
+/** Return a gpr_thd_options struct with all fields set to defaults. */
GPRAPI gpr_thd_options gpr_thd_options_default(void);
-/* Set the thread to become detached on startup - this is the default. */
+/** Set the thread to become detached on startup - this is the default. */
GPRAPI void gpr_thd_options_set_detached(gpr_thd_options *options);
-/* Set the thread to become joinable - mutually exclusive with detached. */
+/** Set the thread to become joinable - mutually exclusive with detached. */
GPRAPI void gpr_thd_options_set_joinable(gpr_thd_options *options);
-/* Returns non-zero if the option detached is set. */
+/** Returns non-zero if the option detached is set. */
GPRAPI int gpr_thd_options_is_detached(const gpr_thd_options *options);
-/* Returns non-zero if the option joinable is set. */
+/** Returns non-zero if the option joinable is set. */
GPRAPI int gpr_thd_options_is_joinable(const gpr_thd_options *options);
-/* Returns the identifier of the current thread. */
+/** Returns the identifier of the current thread. */
GPRAPI gpr_thd_id gpr_thd_currentid(void);
-/* Blocks until the specified thread properly terminates.
+/** Blocks until the specified thread properly terminates.
Calling this on a detached thread has unpredictable results. */
GPRAPI void gpr_thd_join(gpr_thd_id t);
diff --git a/include/grpc/support/time.h b/include/grpc/support/time.h
index 66bcfca..2384f5e 100644
--- a/include/grpc/support/time.h
+++ b/include/grpc/support/time.h
@@ -43,11 +43,11 @@
extern "C" {
#endif
-/* Time constants. */
+/** Time constants. */
GPRAPI gpr_timespec
-gpr_time_0(gpr_clock_type type); /* The zero time interval. */
-GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /* The far future */
-GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /* The far past. */
+gpr_time_0(gpr_clock_type type); /** The zero time interval. */
+GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /** The far future */
+GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /** The far past. */
#define GPR_MS_PER_SEC 1000
#define GPR_US_PER_SEC 1000000
@@ -56,28 +56,28 @@
#define GPR_NS_PER_US 1000
#define GPR_US_PER_MS 1000
-/* initialize time subsystem */
+/** initialize time subsystem */
GPRAPI void gpr_time_init(void);
-/* Return the current time measured from the given clocks epoch. */
+/** Return the current time measured from the given clocks epoch. */
GPRAPI gpr_timespec gpr_now(gpr_clock_type clock);
-/* Convert a timespec from one clock to another */
+/** Convert a timespec from one clock to another */
GPRAPI gpr_timespec gpr_convert_clock_type(gpr_timespec t,
gpr_clock_type target_clock);
-/* Return -ve, 0, or +ve according to whether a < b, a == b, or a > b
+/** Return -ve, 0, or +ve according to whether a < b, a == b, or a > b
respectively. */
GPRAPI int gpr_time_cmp(gpr_timespec a, gpr_timespec b);
GPRAPI gpr_timespec gpr_time_max(gpr_timespec a, gpr_timespec b);
GPRAPI gpr_timespec gpr_time_min(gpr_timespec a, gpr_timespec b);
-/* Add and subtract times. Calculations saturate at infinities. */
+/** Add and subtract times. Calculations saturate at infinities. */
GPRAPI gpr_timespec gpr_time_add(gpr_timespec a, gpr_timespec b);
GPRAPI gpr_timespec gpr_time_sub(gpr_timespec a, gpr_timespec b);
-/* Return a timespec representing a given number of time units. INT64_MIN is
+/** Return a timespec representing a given number of time units. INT64_MIN is
interpreted as gpr_inf_past, and INT64_MAX as gpr_inf_future. */
GPRAPI gpr_timespec gpr_time_from_micros(int64_t x, gpr_clock_type clock_type);
GPRAPI gpr_timespec gpr_time_from_nanos(int64_t x, gpr_clock_type clock_type);
@@ -88,12 +88,12 @@
GPRAPI int32_t gpr_time_to_millis(gpr_timespec timespec);
-/* Return 1 if two times are equal or within threshold of each other,
+/** Return 1 if two times are equal or within threshold of each other,
0 otherwise */
GPRAPI int gpr_time_similar(gpr_timespec a, gpr_timespec b,
gpr_timespec threshold);
-/* Sleep until at least 'until' - an absolute timeout */
+/** Sleep until at least 'until' - an absolute timeout */
GPRAPI void gpr_sleep_until(gpr_timespec until);
GPRAPI double gpr_timespec_to_micros(gpr_timespec t);
diff --git a/include/grpc/support/tls.h b/include/grpc/support/tls.h
index 5365449..a48c73b 100644
--- a/include/grpc/support/tls.h
+++ b/include/grpc/support/tls.h
@@ -36,7 +36,7 @@
#include <grpc/support/port_platform.h>
-/* Thread local storage.
+/** Thread local storage.
A minimal wrapper that should be implementable across many compilers,
and implementable efficiently across most modern compilers.
diff --git a/include/grpc/support/tls_gcc.h b/include/grpc/support/tls_gcc.h
index a47275f..9667524 100644
--- a/include/grpc/support/tls_gcc.h
+++ b/include/grpc/support/tls_gcc.h
@@ -38,7 +38,7 @@
#include <grpc/support/log.h>
-/* Thread local storage based on gcc compiler primitives.
+/** Thread local storage based on gcc compiler primitives.
#include tls.h to use this - and see that file for documentation */
#ifndef NDEBUG
@@ -58,7 +58,7 @@
*((tls)->inited) = true; \
} while (0)
-/* It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */
+/** It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */
#define gpr_tls_destroy(tls) \
do { \
GPR_ASSERT(*((tls)->inited)); \
diff --git a/include/grpc/support/tls_msvc.h b/include/grpc/support/tls_msvc.h
index efc653b..4ef8eef 100644
--- a/include/grpc/support/tls_msvc.h
+++ b/include/grpc/support/tls_msvc.h
@@ -34,7 +34,7 @@
#ifndef GRPC_SUPPORT_TLS_MSVC_H
#define GRPC_SUPPORT_TLS_MSVC_H
-/* Thread local storage based on ms visual c compiler primitives.
+/** Thread local storage based on ms visual c compiler primitives.
#include tls.h to use this - and see that file for documentation */
struct gpr_msvc_thread_local {
diff --git a/include/grpc/support/tls_pthread.h b/include/grpc/support/tls_pthread.h
index e681da2..7cc6a40 100644
--- a/include/grpc/support/tls_pthread.h
+++ b/include/grpc/support/tls_pthread.h
@@ -37,7 +37,7 @@
#include <grpc/support/log.h> /* for GPR_ASSERT */
#include <pthread.h>
-/* Thread local storage based on pthread library calls.
+/** Thread local storage based on pthread library calls.
#include tls.h to use this - and see that file for documentation */
struct gpr_pthread_thread_local {
diff --git a/include/grpc/support/useful.h b/include/grpc/support/useful.h
index 9d8314e..c261fba 100644
--- a/include/grpc/support/useful.h
+++ b/include/grpc/support/useful.h
@@ -34,12 +34,12 @@
#ifndef GRPC_SUPPORT_USEFUL_H
#define GRPC_SUPPORT_USEFUL_H
-/* useful macros that don't belong anywhere else */
+/** useful macros that don't belong anywhere else */
#define GPR_MIN(a, b) ((a) < (b) ? (a) : (b))
#define GPR_MAX(a, b) ((a) > (b) ? (a) : (b))
#define GPR_CLAMP(a, min, max) ((a) < (min) ? (min) : (a) > (max) ? (max) : (a))
-/* rotl, rotr assume x is unsigned */
+/** rotl, rotr assume x is unsigned */
#define GPR_ROTL(x, n) (((x) << (n)) | ((x) >> (sizeof(x) * 8 - (n))))
#define GPR_ROTR(x, n) (((x) >> (n)) | ((x) << (sizeof(x) * 8 - (n))))
diff --git a/include/grpc/support/workaround_list.h b/include/grpc/support/workaround_list.h
index 6a8aa1f..ec47665 100644
--- a/include/grpc/support/workaround_list.h
+++ b/include/grpc/support/workaround_list.h
@@ -36,7 +36,7 @@
/* The list of IDs of server workarounds currently maintained by gRPC. For
* explanation and detailed descriptions of workarounds, see
- * /docs/workarounds.md
+ * /doc/workarounds.md
*/
typedef enum {
GRPC_WORKAROUND_ID_CRONET_COMPRESSION = 0,
diff --git a/package.json b/package.json
index e1499a0..1ed182c 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,7 @@
"lodash": "^4.15.0",
"nan": "^2.0.0",
"node-pre-gyp": "^0.6.0",
- "protobufjs": "^6.7.0"
+ "protobufjs": "^5.0.0"
},
"devDependencies": {
"async": "^2.0.1",
diff --git a/package.xml b/package.xml
index bb8617f..e560139 100644
--- a/package.xml
+++ b/package.xml
@@ -10,7 +10,7 @@
<email>grpc-packages@google.com</email>
<active>yes</active>
</lead>
- <date>2017-03-01</date>
+ <date>2017-05-05</date>
<time>16:06:07</time>
<version>
<release>1.4.0dev</release>
@@ -22,8 +22,7 @@
</stability>
<license>BSD</license>
<notes>
-- Added arg info macros #9751
-- Updated codegen to be consistent with protobuf #9492
+- Fixed some memory leaks #9559, #10996
</notes>
<contents>
<dir baseinstalldir="/" name="/">
@@ -52,6 +51,7 @@
<file baseinstalldir="/" name="src/php/ext/grpc/server.h" role="src" />
<file baseinstalldir="/" name="src/php/ext/grpc/server_credentials.h" role="src" />
<file baseinstalldir="/" name="src/php/ext/grpc/timeval.h" role="src" />
+ <file baseinstalldir="/" name="src/php/ext/grpc/version.h" role="src" />
<file baseinstalldir="/" name="include/grpc/support/alloc.h" role="src" />
<file baseinstalldir="/" name="include/grpc/support/atm.h" role="src" />
<file baseinstalldir="/" name="include/grpc/support/atm_gcc_atomic.h" role="src" />
@@ -1057,79 +1057,7 @@
<file baseinstalldir="/" name="third_party/boringssl/ssl/tls13_server.c" role="src" />
<file baseinstalldir="/" name="third_party/boringssl/ssl/tls_method.c" role="src" />
<file baseinstalldir="/" name="third_party/boringssl/ssl/tls_record.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_data.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_dns.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_getenv.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_getopt.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_inet_net_pton.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_iphlpapi.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_ipv6.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_library_init.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_llist.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_nowarn.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_platform.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_private.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_rules.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_setup.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_strcasecmp.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_strdup.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_version.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/bitncmp.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/config-win32.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/setup_once.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/ares_build.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/config_linux/ares_config.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/config_darwin/ares_config.h" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares__close_sockets.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares__get_hostent.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares__read_line.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares__timeval.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_cancel.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_create_query.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_data.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_destroy.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_expand_name.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_expand_string.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_fds.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_free_hostent.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_free_string.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_getenv.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_gethostbyaddr.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_gethostbyname.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_getnameinfo.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_getopt.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_getsock.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_init.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_library_init.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_llist.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_mkquery.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_nowarn.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_options.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_a_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_aaaa_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_mx_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_naptr_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_ns_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_ptr_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_soa_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_srv_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_parse_txt_reply.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_platform.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_process.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_query.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_search.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_send.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_strcasecmp.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_strdup.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_strerror.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_timeout.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_version.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/ares_writev.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/bitncmp.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/inet_net_pton.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/inet_ntop.c" role="src" />
- <file baseinstalldir="/" name="third_party/cares/cares/windows_port.c" role="src" />
+ <file name="LICENSE" role="doc" />
</dir>
</contents>
<dependencies>
@@ -1445,5 +1373,21 @@
- Updated codegen to be consistent with protobuf #9492
</notes>
</release>
+ <release>
+ <version>
+ <release>1.2.0</release>
+ <api>1.2.0</api>
+ </version>
+ <stability>
+ <release>stable</release>
+ <api>stable</api>
+ </stability>
+ <date>2017-03-20</date>
+ <license>BSD</license>
+ <notes>
+- Added arg info macros #9751
+- Updated codegen to be consistent with protobuf #9492
+ </notes>
+ </release>
</changelog>
</package>
diff --git a/src/core/ext/filters/client_channel/subchannel.c b/src/core/ext/filters/client_channel/subchannel.c
index 1af3393..dd14bf1 100644
--- a/src/core/ext/filters/client_channel/subchannel.c
+++ b/src/core/ext/filters/client_channel/subchannel.c
@@ -283,6 +283,7 @@
void grpc_subchannel_unref(grpc_exec_ctx *exec_ctx,
grpc_subchannel *c GRPC_SUBCHANNEL_REF_EXTRA_ARGS) {
gpr_atm old_refs;
+ // add a weak ref and subtract a strong ref (atomically)
old_refs = ref_mutate(c, (gpr_atm)1 - (gpr_atm)(1 << INTERNAL_REF_BITS),
1 REF_MUTATE_PURPOSE("STRONG_UNREF"));
if ((old_refs & STRONG_REF_MASK) == (1 << INTERNAL_REF_BITS)) {
@@ -656,7 +657,6 @@
gpr_free(sw_subchannel);
grpc_channel_stack_destroy(exec_ctx, stk);
gpr_free(con);
- GRPC_SUBCHANNEL_WEAK_UNREF(exec_ctx, c, "connecting");
return false;
}
diff --git a/src/core/ext/filters/client_channel/subchannel_index.c b/src/core/ext/filters/client_channel/subchannel_index.c
index f6ef4a8..b25dbfc 100644
--- a/src/core/ext/filters/client_channel/subchannel_index.c
+++ b/src/core/ext/filters/client_channel/subchannel_index.c
@@ -183,8 +183,11 @@
enter_ctx(exec_ctx);
grpc_subchannel *c = NULL;
+ bool need_to_unref_constructed;
while (c == NULL) {
+ need_to_unref_constructed = false;
+
// Compare and swap loop:
// - take a reference to the current index
gpr_mu_lock(&g_mu);
@@ -194,8 +197,11 @@
// - Check to see if a subchannel already exists
c = gpr_avl_get(index, key);
if (c != NULL) {
+ c = GRPC_SUBCHANNEL_REF_FROM_WEAK_REF(c, "index_register");
+ }
+ if (c != NULL) {
// yes -> we're done
- GRPC_SUBCHANNEL_WEAK_UNREF(exec_ctx, constructed, "index_register");
+ need_to_unref_constructed = true;
} else {
// no -> update the avl and compare/swap
gpr_avl updated =
@@ -219,6 +225,10 @@
leave_ctx(exec_ctx);
+ if (need_to_unref_constructed) {
+ GRPC_SUBCHANNEL_UNREF(exec_ctx, constructed, "index_register");
+ }
+
return c;
}
diff --git a/src/core/lib/iomgr/ev_epollsig_linux.c b/src/core/lib/iomgr/ev_epollsig_linux.c
index 52362a6..92c555b 100644
--- a/src/core/lib/iomgr/ev_epollsig_linux.c
+++ b/src/core/lib/iomgr/ev_epollsig_linux.c
@@ -65,9 +65,9 @@
#define GRPC_POLLSET_KICK_BROADCAST ((grpc_pollset_worker *)1)
-#define GRPC_POLLING_TRACE(fmt, ...) \
+#define GRPC_POLLING_TRACE(...) \
if (GRPC_TRACER_ON(grpc_polling_trace)) { \
- gpr_log(GPR_INFO, (fmt), __VA_ARGS__); \
+ gpr_log(GPR_INFO, __VA_ARGS__); \
}
/* Uncomment the following to enable extra checks on poll_object operations */
@@ -732,7 +732,7 @@
it right now. Note that since we do an anticipatory mpscq_pop every poll
loop, it's ok if we miss the wakeup here, as we'll get the work item when
the next poller enters anyway. */
- if (current_pollers > min_current_pollers_for_wakeup) {
+ if (current_pollers >= min_current_pollers_for_wakeup) {
GRPC_LOG_IF_ERROR("workqueue_wakeup_fd",
grpc_wakeup_fd_wakeup(&pi->workqueue_wakeup_fd));
}
@@ -1332,7 +1332,13 @@
gpr_mpscq_node *n = gpr_mpscq_pop(&pi->workqueue_items);
gpr_mu_unlock(&pi->workqueue_read_mu);
if (n != NULL) {
- if (gpr_atm_full_fetch_add(&pi->workqueue_item_count, -1) > 1) {
+ gpr_atm remaining =
+ gpr_atm_full_fetch_add(&pi->workqueue_item_count, -1) - 1;
+ GRPC_POLLING_TRACE(
+ "maybe_do_workqueue_work: pi: %p: got closure %p, remaining = "
+ "%" PRIdPTR,
+ pi, n, remaining);
+ if (remaining > 0) {
workqueue_maybe_wakeup(pi);
}
grpc_closure *c = (grpc_closure *)n;
@@ -1347,8 +1353,13 @@
/* n == NULL might mean there's work but it's not available to be popped
* yet - try to ensure another workqueue wakes up to check shortly if so
*/
+ GRPC_POLLING_TRACE(
+ "maybe_do_workqueue_work: pi: %p: more to do, but not yet", pi);
workqueue_maybe_wakeup(pi);
}
+ } else {
+ GRPC_POLLING_TRACE("maybe_do_workqueue_work: pi: %p: read already locked",
+ pi);
}
return false;
}
@@ -1411,7 +1422,10 @@
/* If we get some workqueue work to do, it might end up completing an item on
the completion queue, so there's no need to poll... so we skip that and
redo the complete loop to verify */
+ GRPC_POLLING_TRACE("pollset_work: pollset: %p, worker %p, pi %p", pollset,
+ worker, pi);
if (!maybe_do_workqueue_work(exec_ctx, pi)) {
+ GRPC_POLLING_TRACE("pollset_work: begins");
gpr_atm_no_barrier_fetch_add(&pi->poller_count, 1);
g_current_thread_polling_island = pi;
@@ -1472,6 +1486,7 @@
g_current_thread_polling_island = NULL;
gpr_atm_no_barrier_fetch_add(&pi->poller_count, -1);
+ GRPC_POLLING_TRACE("pollset_work: ends");
}
GPR_ASSERT(pi != NULL);
diff --git a/src/core/lib/iomgr/tcp_server_uv.c b/src/core/lib/iomgr/tcp_server_uv.c
index e924694..d446e53 100644
--- a/src/core/lib/iomgr/tcp_server_uv.c
+++ b/src/core/lib/iomgr/tcp_server_uv.c
@@ -56,6 +56,8 @@
int port;
/* linked list */
struct grpc_tcp_listener *next;
+
+ bool closed;
};
struct grpc_tcp_server {
@@ -77,6 +79,8 @@
/* shutdown callback */
grpc_closure *shutdown_complete;
+ bool shutdown;
+
grpc_resource_quota *resource_quota;
};
@@ -109,6 +113,7 @@
s->shutdown_starting.head = NULL;
s->shutdown_starting.tail = NULL;
s->shutdown_complete = shutdown_complete;
+ s->shutdown = false;
*server = s;
return GRPC_ERROR_NONE;
}
@@ -125,6 +130,7 @@
}
static void finish_shutdown(grpc_exec_ctx *exec_ctx, grpc_tcp_server *s) {
+ GPR_ASSERT(s->shutdown);
if (s->shutdown_complete != NULL) {
grpc_closure_sched(exec_ctx, s->shutdown_complete, GRPC_ERROR_NONE);
}
@@ -144,21 +150,31 @@
grpc_tcp_listener *sp = (grpc_tcp_listener *)handle->data;
grpc_exec_ctx exec_ctx = GRPC_EXEC_CTX_INIT;
sp->server->open_ports--;
- if (sp->server->open_ports == 0) {
+ if (sp->server->open_ports == 0 && sp->server->shutdown) {
finish_shutdown(&exec_ctx, sp->server);
}
grpc_exec_ctx_finish(&exec_ctx);
}
+static void close_listener(grpc_tcp_listener *sp) {
+ if (!sp->closed) {
+ sp->closed = true;
+ uv_close((uv_handle_t *)sp->handle, handle_close_callback);
+ }
+}
+
static void tcp_server_destroy(grpc_exec_ctx *exec_ctx, grpc_tcp_server *s) {
int immediately_done = 0;
grpc_tcp_listener *sp;
+ GPR_ASSERT(!s->shutdown);
+ s->shutdown = true;
+
if (s->open_ports == 0) {
immediately_done = 1;
}
for (sp = s->head; sp; sp = sp->next) {
- uv_close((uv_handle_t *)sp->handle, handle_close_callback);
+ close_listener(sp);
}
if (immediately_done) {
@@ -196,9 +212,14 @@
int err;
if (status < 0) {
- gpr_log(GPR_INFO, "Skipping on_accept due to error: %s",
- uv_strerror(status));
- return;
+ switch (status) {
+ case UV_EINTR:
+ case UV_EAGAIN:
+ return;
+ default:
+ close_listener(sp);
+ return;
+ }
}
client = gpr_malloc(sizeof(uv_tcp_t));
@@ -287,6 +308,7 @@
sp->handle = handle;
sp->port = port;
sp->port_index = port_index;
+ sp->closed = false;
handle->data = sp;
s->open_ports++;
GPR_ASSERT(sp->handle);
diff --git a/src/core/lib/iomgr/tcp_uv.c b/src/core/lib/iomgr/tcp_uv.c
index e715753..dc23e4f 100644
--- a/src/core/lib/iomgr/tcp_uv.c
+++ b/src/core/lib/iomgr/tcp_uv.c
@@ -88,12 +88,12 @@
#ifdef GRPC_TCP_REFCOUNT_DEBUG
#define TCP_UNREF(exec_ctx, tcp, reason) \
tcp_unref((exec_ctx), (tcp), (reason), __FILE__, __LINE__)
-#define TCP_REF(tcp, reason) \
- tcp_ref((exec_ctx), (tcp), (reason), __FILE__, __LINE__)
+#define TCP_REF(tcp, reason) tcp_ref((tcp), (reason), __FILE__, __LINE__)
static void tcp_unref(grpc_exec_ctx *exec_ctx, grpc_tcp *tcp,
const char *reason, const char *file, int line) {
- gpr_log(file, line, GPR_LOG_SEVERITY_DEBUG, "TCP unref %p : %s %d -> %d", tcp,
- reason, tcp->refcount.count, tcp->refcount.count - 1);
+ gpr_log(file, line, GPR_LOG_SEVERITY_DEBUG,
+ "TCP unref %p : %s %" PRIiPTR " -> %" PRIiPTR, tcp, reason,
+ tcp->refcount.count, tcp->refcount.count - 1);
if (gpr_unref(&tcp->refcount)) {
tcp_free(exec_ctx, tcp);
}
@@ -101,8 +101,9 @@
static void tcp_ref(grpc_tcp *tcp, const char *reason, const char *file,
int line) {
- gpr_log(file, line, GPR_LOG_SEVERITY_DEBUG, "TCP ref %p : %s %d -> %d", tcp,
- reason, tcp->refcount.count, tcp->refcount.count + 1);
+ gpr_log(file, line, GPR_LOG_SEVERITY_DEBUG,
+ "TCP ref %p : %s %" PRIiPTR " -> %" PRIiPTR, tcp, reason,
+ tcp->refcount.count, tcp->refcount.count + 1);
gpr_ref(&tcp->refcount);
}
#else
@@ -311,6 +312,7 @@
tcp->shutting_down = true;
uv_shutdown_t *req = &tcp->shutdown_req;
uv_shutdown(req, (uv_stream_t *)tcp->handle, shutdown_callback);
+ grpc_resource_user_shutdown(exec_ctx, tcp->resource_user);
}
GRPC_ERROR_UNREF(why);
}
diff --git a/src/core/lib/surface/completion_queue.c b/src/core/lib/surface/completion_queue.c
index b0a4b1f..de90594 100644
--- a/src/core/lib/surface/completion_queue.c
+++ b/src/core/lib/surface/completion_queue.c
@@ -582,9 +582,9 @@
cq_event_queue_push(&cqd->queue, storage);
gpr_atm_no_barrier_fetch_add(&cqd->things_queued_ever, 1);
- int shutdown = gpr_unref(&cqd->pending_events);
-
gpr_mu_lock(cqd->mu);
+
+ int shutdown = gpr_unref(&cqd->pending_events);
if (!shutdown) {
grpc_error *kick_error = cc->poller_vtable->kick(POLLSET_FROM_CQ(cc), NULL);
gpr_mu_unlock(cqd->mu);
diff --git a/src/cpp/server/server_builder.cc b/src/cpp/server/server_builder.cc
index 2ead048..6dca6a6 100644
--- a/src/cpp/server/server_builder.cc
+++ b/src/cpp/server/server_builder.cc
@@ -358,4 +358,14 @@
(*g_plugin_factory_list).push_back(CreatePlugin);
}
+ServerBuilder& ServerBuilder::EnableWorkaround(grpc_workaround_list id) {
+ switch (id) {
+ case GRPC_WORKAROUND_ID_CRONET_COMPRESSION:
+ return AddChannelArgument(GRPC_ARG_WORKAROUND_CRONET_COMPRESSION, 1);
+ default:
+ gpr_log(GPR_ERROR, "Workaround %u does not exist or is obsolete.", id);
+ return *this;
+ }
+}
+
} // namespace grpc
diff --git a/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs b/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs
index 3c368fb..8ed0c0b 100644
--- a/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs
@@ -117,7 +117,7 @@
{
var ctx = BatchContextSafeHandle.Create();
completionQueue.CompletionRegistry.RegisterBatchCompletion(ctx, (success, context) => callback(success));
- Native.grpcsharp_call_send_message(this, ctx, payload, new UIntPtr((ulong)payload.Length), writeFlags, sendEmptyInitialMetadata).CheckOk();
+ Native.grpcsharp_call_send_message(this, ctx, payload, new UIntPtr((ulong)payload.Length), writeFlags, sendEmptyInitialMetadata ? 1 : 0).CheckOk();
}
}
@@ -140,7 +140,7 @@
var optionalPayloadLength = optionalPayload != null ? new UIntPtr((ulong)optionalPayload.Length) : UIntPtr.Zero;
completionQueue.CompletionRegistry.RegisterBatchCompletion(ctx, (success, context) => callback(success));
var statusDetailBytes = MarshalUtils.GetBytesUTF8(status.Detail);
- Native.grpcsharp_call_send_status_from_server(this, ctx, status.StatusCode, statusDetailBytes, new UIntPtr((ulong)statusDetailBytes.Length), metadataArray, sendEmptyInitialMetadata,
+ Native.grpcsharp_call_send_status_from_server(this, ctx, status.StatusCode, statusDetailBytes, new UIntPtr((ulong)statusDetailBytes.Length), metadataArray, sendEmptyInitialMetadata ? 1 : 0,
optionalPayload, optionalPayloadLength, writeFlags).CheckOk();
}
}
diff --git a/src/csharp/Grpc.Core/Internal/NativeMethods.cs b/src/csharp/Grpc.Core/Internal/NativeMethods.cs
index a98861a..696987d 100644
--- a/src/csharp/Grpc.Core/Internal/NativeMethods.cs
+++ b/src/csharp/Grpc.Core/Internal/NativeMethods.cs
@@ -346,11 +346,11 @@
public delegate CallError grpcsharp_call_start_duplex_streaming_delegate(CallSafeHandle call,
BatchContextSafeHandle ctx, MetadataArraySafeHandle metadataArray, CallFlags metadataFlags);
public delegate CallError grpcsharp_call_send_message_delegate(CallSafeHandle call,
- BatchContextSafeHandle ctx, byte[] sendBuffer, UIntPtr sendBufferLen, WriteFlags writeFlags, bool sendEmptyInitialMetadata);
+ BatchContextSafeHandle ctx, byte[] sendBuffer, UIntPtr sendBufferLen, WriteFlags writeFlags, int sendEmptyInitialMetadata);
public delegate CallError grpcsharp_call_send_close_from_client_delegate(CallSafeHandle call,
BatchContextSafeHandle ctx);
public delegate CallError grpcsharp_call_send_status_from_server_delegate(CallSafeHandle call,
- BatchContextSafeHandle ctx, StatusCode statusCode, byte[] statusMessage, UIntPtr statusMessageLen, MetadataArraySafeHandle metadataArray, bool sendEmptyInitialMetadata,
+ BatchContextSafeHandle ctx, StatusCode statusCode, byte[] statusMessage, UIntPtr statusMessageLen, MetadataArraySafeHandle metadataArray, int sendEmptyInitialMetadata,
byte[] optionalSendBuffer, UIntPtr optionalSendBufferLen, WriteFlags writeFlags);
public delegate CallError grpcsharp_call_recv_message_delegate(CallSafeHandle call,
BatchContextSafeHandle ctx);
@@ -406,7 +406,7 @@
public delegate CallCredentialsSafeHandle grpcsharp_metadata_credentials_create_from_plugin_delegate(NativeMetadataInterceptor interceptor);
public delegate void grpcsharp_metadata_credentials_notify_from_plugin_delegate(IntPtr callbackPtr, IntPtr userData, MetadataArraySafeHandle metadataArray, StatusCode statusCode, string errorDetails);
- public delegate ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create_delegate(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, bool forceClientAuth);
+ public delegate ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create_delegate(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, int forceClientAuth);
public delegate void grpcsharp_server_credentials_release_delegate(IntPtr credentials);
public delegate ServerSafeHandle grpcsharp_server_create_delegate(ChannelArgsSafeHandle args);
diff --git a/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs b/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
index 24f686f..c14fa7c 100644
--- a/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
@@ -53,7 +53,7 @@
return Native.grpcsharp_ssl_server_credentials_create(pemRootCerts,
keyCertPairCertChainArray, keyCertPairPrivateKeyArray,
new UIntPtr((ulong)keyCertPairCertChainArray.Length),
- forceClientAuth);
+ forceClientAuth ? 1 : 0);
}
protected override bool ReleaseHandle()
diff --git a/src/csharp/build_packages_dotnetcli.bat b/src/csharp/build_packages_dotnetcli.bat
index aa8a8d3..d823942 100755
--- a/src/csharp/build_packages_dotnetcli.bat
+++ b/src/csharp/build_packages_dotnetcli.bat
@@ -51,11 +51,11 @@
@rem To be able to build, we also need to put grpc_csharp_ext to its normal location
xcopy /Y /I nativelibs\csharp_ext_windows_x64\grpc_csharp_ext.dll ..\..\cmake\build\x64\Release\
-%DOTNET% pack --configuration Release Grpc.Core --output ..\..\..\artifacts || goto :error
-%DOTNET% pack --configuration Release Grpc.Core.Testing --output ..\..\..\artifacts || goto :error
-%DOTNET% pack --configuration Release Grpc.Auth --output ..\..\..\artifacts || goto :error
-%DOTNET% pack --configuration Release Grpc.HealthCheck --output ..\..\..\artifacts || goto :error
-%DOTNET% pack --configuration Release Grpc.Reflection --output ..\..\..\artifacts || goto :error
+%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Core --output ..\..\..\artifacts || goto :error
+%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Core.Testing --output ..\..\..\artifacts || goto :error
+%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Auth --output ..\..\..\artifacts || goto :error
+%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.HealthCheck --output ..\..\..\artifacts || goto :error
+%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Reflection --output ..\..\..\artifacts || goto :error
%NUGET% pack Grpc.nuspec -Version %VERSION% -OutputDirectory ..\..\artifacts || goto :error
%NUGET% pack Grpc.Tools.nuspec -Version %VERSION% -OutputDirectory ..\..\artifacts
diff --git a/src/csharp/build_packages_dotnetcli.sh b/src/csharp/build_packages_dotnetcli.sh
index d339238..f79c97f 100755
--- a/src/csharp/build_packages_dotnetcli.sh
+++ b/src/csharp/build_packages_dotnetcli.sh
@@ -48,11 +48,11 @@
mkdir -p ../../libs/opt
cp nativelibs/csharp_ext_linux_x64/libgrpc_csharp_ext.so ../../libs/opt
-dotnet pack --configuration Release Grpc.Core --output ../../../artifacts
-dotnet pack --configuration Release Grpc.Core.Testing --output ../../../artifacts
-dotnet pack --configuration Release Grpc.Auth --output ../../../artifacts
-dotnet pack --configuration Release Grpc.HealthCheck --output ../../../artifacts
-dotnet pack --configuration Release Grpc.Reflection --output ../../../artifacts
+dotnet pack --configuration Release --include-symbols --include-source Grpc.Core --output ../../../artifacts
+dotnet pack --configuration Release --include-symbols --include-source Grpc.Core.Testing --output ../../../artifacts
+dotnet pack --configuration Release --include-symbols --include-source Grpc.Auth --output ../../../artifacts
+dotnet pack --configuration Release --include-symbols --include-source Grpc.HealthCheck --output ../../../artifacts
+dotnet pack --configuration Release --include-symbols --include-source Grpc.Reflection --output ../../../artifacts
nuget pack Grpc.nuspec -Version "1.4.0-dev" -OutputDirectory ../../artifacts
nuget pack Grpc.Tools.nuspec -Version "1.4.0-dev" -OutputDirectory ../../artifacts
diff --git a/src/node/index.js b/src/node/index.js
index 0da3440..2da77c3 100644
--- a/src/node/index.js
+++ b/src/node/index.js
@@ -70,8 +70,6 @@
* Buffers. Defaults to false
* - longsAsStrings: deserialize long values as strings instead of objects.
* Defaults to true
- * - enumsAsStrings: deserialize enum values as strings instead of numbers.
- * Defaults to true
* - deprecatedArgumentOrder: Use the beta method argument order for client
* methods, with optional arguments after the callback. Defaults to false.
* This option is only a temporary stopgap measure to smooth an API breakage.
@@ -105,10 +103,6 @@
switch (protobufjsVersion) {
case 6: return protobuf_js_6_common.loadObject(value, options);
case 5:
- var deprecation_message = 'Calling grpc.loadObject with an object ' +
- 'generated by ProtoBuf.js 5 is deprecated. Please upgrade to ' +
- 'ProtoBuf.js 6.';
- common.log(grpc.logVerbosity.INFO, deprecation_message);
return protobuf_js_5_common.loadObject(value, options);
default:
throw new Error('Unrecognized protobufjsVersion', protobufjsVersion);
@@ -117,19 +111,6 @@
var loadObject = exports.loadObject;
-function applyProtoRoot(filename, root) {
- if (_.isString(filename)) {
- return filename;
- }
- filename.root = path.resolve(filename.root) + '/';
- root.resolvePath = function(originPath, importPath, alreadyNormalized) {
- return ProtoBuf.util.path.resolve(filename.root,
- importPath,
- alreadyNormalized);
- };
- return filename.file;
-}
-
/**
* Load a gRPC object from a .proto file. The options object can provide the
* following options:
@@ -139,8 +120,6 @@
* Buffers. Defaults to false
* - longsAsStrings: deserialize long values as strings instead of objects.
* Defaults to true
- * - enumsAsStrings: deserialize enum values as strings instead of numbers.
- * Defaults to true
* - deprecatedArgumentOrder: Use the beta method argument order for client
* methods, with optional arguments after the callback. Defaults to false.
* This option is only a temporary stopgap measure to smooth an API breakage.
@@ -152,17 +131,31 @@
* @return {Object<string, *>} The resulting gRPC object
*/
exports.load = function load(filename, format, options) {
- /* Note: format is currently unused, because the API for loading a proto
- file or a JSON file is identical in Protobuf.js 6. In the future, there is
- still the possibility of adding other formats that would be loaded
- differently */
options = _.defaults(options, common.defaultGrpcOptions);
- options.protobufjs_version = 6;
- var root = new ProtoBuf.Root();
- var parse_options = {keepCase: !options.convertFieldsToCamelCase};
- return loadObject(root.loadSync(applyProtoRoot(filename, root),
- parse_options),
- options);
+ options.protobufjsVersion = 5;
+ if (!format) {
+ format = 'proto';
+ }
+ var convertFieldsToCamelCaseOriginal = ProtoBuf.convertFieldsToCamelCase;
+ if(options && options.hasOwnProperty('convertFieldsToCamelCase')) {
+ ProtoBuf.convertFieldsToCamelCase = options.convertFieldsToCamelCase;
+ }
+ var builder;
+ try {
+ switch(format) {
+ case 'proto':
+ builder = ProtoBuf.loadProtoFile(filename);
+ break;
+ case 'json':
+ builder = ProtoBuf.loadJsonFile(filename);
+ break;
+ default:
+ throw new Error('Unrecognized format "' + format + '"');
+ }
+ } finally {
+ ProtoBuf.convertFieldsToCamelCase = convertFieldsToCamelCaseOriginal;
+ }
+ return loadObject(builder.ns, options);
};
var log_template = _.template(
diff --git a/src/node/src/protobuf_js_5_common.js b/src/node/src/protobuf_js_5_common.js
index 62cf2f4..4041e05 100644
--- a/src/node/src/protobuf_js_5_common.js
+++ b/src/node/src/protobuf_js_5_common.js
@@ -45,8 +45,7 @@
* objects. Defaults to true
* @return {function(Buffer):cls} The deserialization function
*/
-exports.deserializeCls = function deserializeCls(cls, binaryAsBase64,
- longsAsStrings) {
+exports.deserializeCls = function deserializeCls(cls, options) {
/**
* Deserialize a buffer to a message object
* @param {Buffer} arg_buf The buffer to deserialize
@@ -55,7 +54,8 @@
return function deserialize(arg_buf) {
// Convert to a native object with binary fields as Buffers (first argument)
// and longs as strings (second argument)
- return cls.decode(arg_buf).toRaw(binaryAsBase64, longsAsStrings);
+ return cls.decode(arg_buf).toRaw(options.binaryAsBase64,
+ options.longsAsStrings);
};
};
@@ -128,10 +128,10 @@
responseType: method.resolvedResponseType,
requestSerialize: serializeCls(method.resolvedRequestType.build()),
requestDeserialize: deserializeCls(method.resolvedRequestType.build(),
- binaryAsBase64, longsAsStrings),
+ options),
responseSerialize: serializeCls(method.resolvedResponseType.build()),
responseDeserialize: deserializeCls(method.resolvedResponseType.build(),
- binaryAsBase64, longsAsStrings)
+ options)
};
}));
};
diff --git a/src/node/src/server.js b/src/node/src/server.js
index 08417a7..1d9cc7d 100644
--- a/src/node/src/server.js
+++ b/src/node/src/server.js
@@ -781,6 +781,11 @@
});
};
+var logAddProtoServiceDeprecationOnce = _.once(function() {
+ common.log(constants.logVerbosity.INFO,
+ 'Server#addProtoService is deprecated. Use addService instead');
+});
+
/**
* Add a proto service to the server, with a corresponding implementation
* @deprecated Use grpc.load and Server#addService instead
@@ -792,8 +797,7 @@
var options;
var protobuf_js_5_common = require('./protobuf_js_5_common');
var protobuf_js_6_common = require('./protobuf_js_6_common');
- common.log(constants.logVerbosity.INFO,
- 'Server#addProtoService is deprecated. Use addService instead');
+ logAddProtoServiceDeprecationOnce();
if (protobuf_js_5_common.isProbablyProtobufJs5(service)) {
options = _.defaults(service.grpc_options, common.defaultGrpcOptions);
this.addService(
diff --git a/src/node/test/common_test.js b/src/node/test/common_test.js
index e1ce864..b7c2c6a 100644
--- a/src/node/test/common_test.js
+++ b/src/node/test/common_test.js
@@ -37,16 +37,15 @@
var _ = require('lodash');
var common = require('../src/common');
-var protobuf_js_6_common = require('../src/protobuf_js_6_common');
+var protobuf_js_5_common = require('../src/protobuf_js_5_common');
-var serializeCls = protobuf_js_6_common.serializeCls;
-var deserializeCls = protobuf_js_6_common.deserializeCls;
+var serializeCls = protobuf_js_5_common.serializeCls;
+var deserializeCls = protobuf_js_5_common.deserializeCls;
var ProtoBuf = require('protobufjs');
-var messages_proto = new ProtoBuf.Root();
-messages_proto = messages_proto.loadSync(
- __dirname + '/test_messages.proto', {keepCase: true}).resolveAll();
+var messages_proto = ProtoBuf.loadProtoFile(
+ __dirname + '/test_messages.proto').build();
var default_options = common.defaultGrpcOptions;
@@ -101,6 +100,7 @@
var longNumDeserialize = deserializeCls(messages_proto.LongValues,
num_options);
var serialized = longSerialize({int_64: pos_value});
+ console.log(longDeserialize(serialized));
assert.strictEqual(typeof longDeserialize(serialized).int_64, 'string');
/* With the longsAsStrings option disabled, long values are represented as
* objects with 3 keys: low, high, and unsigned */
@@ -136,7 +136,8 @@
var serialized = sequenceSerialize({repeated_field: [10]});
assert.strictEqual(expected_serialize.compare(serialized), 0);
});
- it('should deserialize packed or unpacked repeated', function() {
+ // This tests a bug that was fixed in Protobuf.js 6
+ it.skip('should deserialize packed or unpacked repeated', function() {
var expectedDeserialize = {
bytes_field: new Buffer(''),
repeated_field: [10]
@@ -155,7 +156,8 @@
assert.deepEqual(unpackedDeserialized, expectedDeserialize);
});
});
-describe('Proto message oneof serialize and deserialize', function() {
+// This tests a bug that was fixed in Protobuf.js 6
+describe.skip('Proto message oneof serialize and deserialize', function() {
var oneofSerialize = serializeCls(messages_proto.OneOfValues);
var oneofDeserialize = deserializeCls(
messages_proto.OneOfValues, default_options);
@@ -193,7 +195,8 @@
assert.deepEqual(enumDeserialize(nameSerialized),
enumDeserialize(numberSerialized));
});
- it('Should deserialize as a string the enumsAsStrings option', function() {
+ // This tests a bug that was fixed in Protobuf.js 6
+ it.skip('Should correctly handle the enumsAsStrings option', function() {
var serialized = enumSerialize({enum_value: 'TWO'});
var nameDeserialized = enumDeserialize(serialized);
var numberDeserialized = enumIntDeserialize(serialized);
diff --git a/src/node/test/surface_test.js b/src/node/test/surface_test.js
index 783028f..d2f0511 100644
--- a/src/node/test/surface_test.js
+++ b/src/node/test/surface_test.js
@@ -43,9 +43,8 @@
var grpc = require('..');
-var math_proto = new ProtoBuf.Root();
-math_proto = math_proto.loadSync(__dirname +
- '/../../proto/math/math.proto', {keepCase: true});
+var math_proto = ProtoBuf.loadProtoFile(__dirname +
+ '/../../proto/math/math.proto');
var mathService = math_proto.lookup('math.Math');
var mathServiceAttrs = grpc.loadObject(
@@ -332,9 +331,7 @@
var server;
var client;
before(function() {
- var test_proto = new ProtoBuf.Root();
- test_proto = test_proto.loadSync(__dirname + '/echo_service.proto',
- {keepCase: true});
+ var test_proto = ProtoBuf.loadProtoFile(__dirname + '/echo_service.proto');
var echo_service = test_proto.lookup('EchoService');
var Client = grpc.loadObject(echo_service);
server = new grpc.Server();
@@ -357,6 +354,13 @@
done();
});
});
+ it('Should convert an undefined argument to default values', function(done) {
+ client.echo(undefined, function(error, response) {
+ assert.ifError(error);
+ assert.deepEqual(response, {value: '', value2: 0});
+ done();
+ });
+ });
});
describe('Generic client and server', function() {
function toString(val) {
@@ -457,9 +461,7 @@
var server;
var metadata;
before(function() {
- var test_proto = new ProtoBuf.Root();
- test_proto = test_proto.loadSync(__dirname + '/test_service.proto',
- {keepCase: true});
+ var test_proto = ProtoBuf.loadProtoFile(__dirname + '/test_service.proto');
var test_service = test_proto.lookup('TestService');
var Client = grpc.loadObject(test_service);
server = new grpc.Server();
@@ -560,9 +562,7 @@
var client;
var badArg = new Buffer([0xFF]);
before(function() {
- var test_proto = new ProtoBuf.Root();
- test_proto = test_proto.loadSync(__dirname + '/test_service.proto',
- {keepCase: true});
+ var test_proto = ProtoBuf.loadProtoFile(__dirname + '/test_service.proto');
var test_service = test_proto.lookup('TestService');
var malformed_test_service = {
unary: {
@@ -669,9 +669,7 @@
var client;
var server;
before(function() {
- var test_proto = new ProtoBuf.Root();
- test_proto = test_proto.loadSync(__dirname + '/test_service.proto',
- {keepCase: true});
+ var test_proto = ProtoBuf.loadProtoFile(__dirname + '/test_service.proto');
var test_service = test_proto.lookup('TestService');
var malformed_test_service = {
unary: {
@@ -772,16 +770,13 @@
});
});
describe('Other conditions', function() {
- var test_service;
var Client;
var client;
var server;
var port;
before(function() {
- var test_proto = new ProtoBuf.Root();
- test_proto = test_proto.loadSync(__dirname + '/test_service.proto',
- {keepCase: true});
- test_service = test_proto.lookup('TestService');
+ var test_proto = ProtoBuf.loadProtoFile(__dirname + '/test_service.proto');
+ var test_service = test_proto.lookup('TestService');
Client = grpc.loadObject(test_service);
server = new grpc.Server();
var trailer_metadata = new grpc.Metadata();
@@ -1121,15 +1116,12 @@
var proxy;
var proxy_impl;
- var test_service;
var Client;
var client;
var server;
before(function() {
- var test_proto = new ProtoBuf.Root();
- test_proto = test_proto.loadSync(__dirname + '/test_service.proto',
- {keepCase: true});
- test_service = test_proto.lookup('TestService');
+ var test_proto = ProtoBuf.loadProtoFile(__dirname + '/test_service.proto');
+ var test_service = test_proto.lookup('TestService');
server = new grpc.Server();
Client = grpc.loadObject(test_service);
server.addService(Client.service, {
diff --git a/src/php/README.md b/src/php/README.md
index f9f93ba..90c8cb3 100644
--- a/src/php/README.md
+++ b/src/php/README.md
@@ -174,6 +174,28 @@
```
+### Protobuf Runtime library
+
+There are two protobuf runtime libraries to choose from. They are idenfical in terms of APIs offered.
+
+1. C implementation (for better performance)
+
+``` sh
+$ sudo pecl install protobuf
+```
+
+2. PHP implementation (for easier installation)
+
+
+Add this to your `composer.json` file:
+
+```
+ "require": {
+ "google/protobuf": "^v3.3.0"
+ }
+```
+
+
### PHP Protoc Plugin
You need the gRPC PHP protoc plugin to generate the client stub classes.
diff --git a/src/php/ext/grpc/call.c b/src/php/ext/grpc/call.c
index d3fd884..94e0b73 100644
--- a/src/php/ext/grpc/call.c
+++ b/src/php/ext/grpc/call.c
@@ -125,7 +125,12 @@
php_grpc_add_next_index_stringl(inner_array, str_val,
GRPC_SLICE_LENGTH(elem->value), false);
add_assoc_zval(array, str_key, inner_array);
+ PHP_GRPC_FREE_STD_ZVAL(inner_array);
}
+ efree(str_key);
+#if PHP_MAJOR_VERSION >= 7
+ efree(str_val);
+#endif
}
return array;
}
@@ -256,8 +261,6 @@
object_init(result);
php_grpc_ulong index;
zval *recv_status;
- PHP_GRPC_MAKE_STD_ZVAL(recv_status);
- object_init(recv_status);
zval *value;
zval *inner_value;
zval *message_value;
@@ -439,7 +442,7 @@
grpc_completion_queue_pluck(completion_queue, call->wrapped,
gpr_inf_future(GPR_CLOCK_REALTIME), NULL);
#if PHP_MAJOR_VERSION >= 7
- zval recv_md;
+ zval *recv_md;
#endif
for (int i = 0; i < op_num; i++) {
switch(ops[i].op) {
@@ -460,8 +463,10 @@
array = grpc_parse_metadata_array(&recv_metadata TSRMLS_CC);
add_property_zval(result, "metadata", array);
#else
- recv_md = *grpc_parse_metadata_array(&recv_metadata);
- add_property_zval(result, "metadata", &recv_md);
+ recv_md = grpc_parse_metadata_array(&recv_metadata);
+ add_property_zval(result, "metadata", recv_md);
+ zval_ptr_dtor(recv_md);
+ PHP_GRPC_FREE_STD_ZVAL(recv_md);
#endif
PHP_GRPC_DELREF(array);
break;
@@ -475,12 +480,16 @@
}
break;
case GRPC_OP_RECV_STATUS_ON_CLIENT:
+ PHP_GRPC_MAKE_STD_ZVAL(recv_status);
+ object_init(recv_status);
#if PHP_MAJOR_VERSION < 7
array = grpc_parse_metadata_array(&recv_trailing_metadata TSRMLS_CC);
add_property_zval(recv_status, "metadata", array);
#else
- recv_md = *grpc_parse_metadata_array(&recv_trailing_metadata);
- add_property_zval(recv_status, "metadata", &recv_md);
+ recv_md = grpc_parse_metadata_array(&recv_trailing_metadata);
+ add_property_zval(recv_status, "metadata", recv_md);
+ zval_ptr_dtor(recv_md);
+ PHP_GRPC_FREE_STD_ZVAL(recv_md);
#endif
PHP_GRPC_DELREF(array);
add_property_long(recv_status, "code", status);
@@ -489,6 +498,9 @@
true);
gpr_free(status_details_text);
add_property_zval(result, "status", recv_status);
+#if PHP_MAJOR_VERSION >= 7
+ zval_ptr_dtor(recv_status);
+#endif
PHP_GRPC_DELREF(recv_status);
PHP_GRPC_FREE_STD_ZVAL(recv_status);
break;
diff --git a/src/php/ext/grpc/call_credentials.c b/src/php/ext/grpc/call_credentials.c
index 625c0c6..da7100f 100644
--- a/src/php/ext/grpc/call_credentials.c
+++ b/src/php/ext/grpc/call_credentials.c
@@ -172,34 +172,54 @@
object_init(arg);
php_grpc_add_property_string(arg, "service_url", context.service_url, true);
php_grpc_add_property_string(arg, "method_name", context.method_name, true);
- zval *retval;
- PHP_GRPC_MAKE_STD_ZVAL(retval);
+ zval *retval = NULL;
#if PHP_MAJOR_VERSION < 7
zval **params[1];
params[0] = &arg;
state->fci->params = params;
state->fci->retval_ptr_ptr = &retval;
#else
+ PHP_GRPC_MAKE_STD_ZVAL(retval);
state->fci->params = arg;
state->fci->retval = retval;
#endif
state->fci->param_count = 1;
+ PHP_GRPC_DELREF(arg);
+
/* call the user callback function */
zend_call_function(state->fci, state->fci_cache TSRMLS_CC);
grpc_status_code code = GRPC_STATUS_OK;
grpc_metadata_array metadata;
+ bool cleanup = true;
if (Z_TYPE_P(retval) != IS_ARRAY) {
+ cleanup = false;
code = GRPC_STATUS_INVALID_ARGUMENT;
} else if (!create_metadata_array(retval, &metadata)) {
- grpc_metadata_array_destroy(&metadata);
code = GRPC_STATUS_INVALID_ARGUMENT;
}
+ if (retval != NULL) {
+#if PHP_MAJOR_VERSION < 7
+ zval_ptr_dtor(&retval);
+#else
+ zval_ptr_dtor(arg);
+ zval_ptr_dtor(retval);
+ PHP_GRPC_FREE_STD_ZVAL(arg);
+ PHP_GRPC_FREE_STD_ZVAL(retval);
+#endif
+ }
+
/* Pass control back to core */
cb(user_data, metadata.metadata, metadata.count, code, NULL);
+ if (cleanup) {
+ for (int i = 0; i < metadata.count; i++) {
+ grpc_slice_unref(metadata.metadata[i].value);
+ }
+ grpc_metadata_array_destroy(&metadata);
+ }
}
/* Cleanup function for plugin creds API */
@@ -207,8 +227,10 @@
plugin_state *state = (plugin_state *)ptr;
efree(state->fci);
efree(state->fci_cache);
+#if PHP_MAJOR_VERSION < 7
PHP_GRPC_FREE_STD_ZVAL(state->fci->params);
PHP_GRPC_FREE_STD_ZVAL(state->fci->retval);
+#endif
efree(state);
}
diff --git a/src/php/ext/grpc/php_grpc.h b/src/php/ext/grpc/php_grpc.h
index 13083b0..51f9dd5 100644
--- a/src/php/ext/grpc/php_grpc.h
+++ b/src/php/ext/grpc/php_grpc.h
@@ -40,9 +40,6 @@
extern zend_module_entry grpc_module_entry;
#define phpext_grpc_ptr &grpc_module_entry
-#define PHP_GRPC_VERSION \
- "0.1.0" /* Replace with version number for your extension */
-
#ifdef PHP_WIN32
#define PHP_GRPC_API __declspec(dllexport)
#elif defined(__GNUC__) && __GNUC__ >= 4
@@ -56,10 +53,9 @@
#endif
#include "php.h"
-
#include "php7_wrapper.h"
-
#include "grpc/grpc.h"
+#include "version.h"
/* These are all function declarations */
/* Code that runs at module initialization */
diff --git a/src/php/ext/grpc/version.h b/src/php/ext/grpc/version.h
new file mode 100644
index 0000000..993ef2d
--- /dev/null
+++ b/src/php/ext/grpc/version.h
@@ -0,0 +1,40 @@
+/*
+ *
+ * Copyright 2015, Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ * * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+
+#ifndef VERSION_H
+#define VERSION_H
+
+#define PHP_GRPC_VERSION "1.4.0"
+
+#endif /* VERSION_H */
diff --git a/src/php/tests/qps/composer.json b/src/php/tests/qps/composer.json
index 0fc8709..8c1e7b6 100644
--- a/src/php/tests/qps/composer.json
+++ b/src/php/tests/qps/composer.json
@@ -1,7 +1,8 @@
{
"minimum-stability": "dev",
"require": {
- "grpc/grpc": "dev-master"
+ "grpc/grpc": "dev-master",
+ "google/protobuf": "^v3.3.0"
},
"autoload": {
"psr-4": {
diff --git a/templates/composer.json.template b/templates/composer.json.template
index 2d4cb11..a18624d 100644
--- a/templates/composer.json.template
+++ b/templates/composer.json.template
@@ -8,12 +8,15 @@
"homepage": "http://grpc.io",
"license": "BSD-3-Clause",
"require": {
- "php": ">=5.5.0",
- "google/protobuf": "^v3.3.0"
+ "php": ">=5.5.0"
},
"require-dev": {
"google/auth": "v0.9"
},
+ "suggest": {
+ "ext-protobuf": "For better performance, install the protobuf C extension.",
+ "google/protobuf": "To get started using grpc quickly, install the native protobuf library."
+ },
"autoload": {
"psr-4": {
"Grpc\\": "src/php/lib/Grpc/"
diff --git a/templates/config.m4.template b/templates/config.m4.template
index 13ff738..a6357b7 100644
--- a/templates/config.m4.template
+++ b/templates/config.m4.template
@@ -10,23 +10,21 @@
PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/include)
PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/src/php/ext/grpc)
PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/boringssl/include)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares/cares)
LIBS="-lpthread $LIBS"
+ CFLAGS="-Wall -Werror -Wno-parentheses-equality -Wno-unused-value -std=c11"
+ CXXFLAGS="-std=c++11"
GRPC_SHARED_LIBADD="-lpthread $GRPC_SHARED_LIBADD"
+ PHP_REQUIRE_CXX()
PHP_ADD_LIBRARY(pthread)
-
PHP_ADD_LIBRARY(dl,,GRPC_SHARED_LIBADD)
PHP_ADD_LIBRARY(dl)
case $host in
*darwin*)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares/config_darwin)
;;
*)
- PHP_ADD_INCLUDE(PHP_EXT_SRCDIR()/third_party/cares/config_linux)
PHP_ADD_LIBRARY(rt,,GRPC_SHARED_LIBADD)
PHP_ADD_LIBRARY(rt)
;;
@@ -43,10 +41,9 @@
% endfor
% endif
% endfor
- , $ext_shared, , -Wall -Werror ${"\\"}
- -Wno-parentheses-equality -Wno-unused-value -std=c11 ${"\\"}
- -fvisibility=hidden -DOPENSSL_NO_ASM -D_GNU_SOURCE -DWIN32_LEAN_AND_MEAN ${"\\"}
- -D_HAS_EXCEPTIONS=0 -DNOMINMAX)
+ , $ext_shared, , -fvisibility=hidden ${"\\"}
+ -DOPENSSL_NO_ASM -D_GNU_SOURCE -DWIN32_LEAN_AND_MEAN ${"\\"}
+ -D_HAS_EXCEPTIONS=0 -DNOMINMAX -DGRPC_ARES=0)
PHP_ADD_BUILD_DIR($ext_builddir/src/php/ext/grpc)
<%
diff --git a/templates/package.json.template b/templates/package.json.template
index 3bae8fd..551c25f 100644
--- a/templates/package.json.template
+++ b/templates/package.json.template
@@ -36,7 +36,7 @@
"lodash": "^4.15.0",
"nan": "^2.0.0",
"node-pre-gyp": "^0.6.0",
- "protobufjs": "^6.7.0"
+ "protobufjs": "^5.0.0"
},
"devDependencies": {
"async": "^2.0.1",
diff --git a/templates/package.xml.template b/templates/package.xml.template
index 8655cfa..394b815 100644
--- a/templates/package.xml.template
+++ b/templates/package.xml.template
@@ -12,7 +12,7 @@
<email>grpc-packages@google.com</email>
<active>yes</active>
</lead>
- <date>2017-03-01</date>
+ <date>2017-05-05</date>
<time>16:06:07</time>
<version>
<release>${settings.php_version.php()}</release>
@@ -24,8 +24,7 @@
</stability>
<license>BSD</license>
<notes>
- - Added arg info macros #9751
- - Updated codegen to be consistent with protobuf #9492
+ - Fixed some memory leaks #9559, #10996
</notes>
<contents>
<dir baseinstalldir="/" name="/">
@@ -43,6 +42,7 @@
% endfor
% endif
% endfor
+ <file name="LICENSE" role="doc" />
</dir>
</contents>
<dependencies>
@@ -358,5 +358,21 @@
- Updated codegen to be consistent with protobuf #9492
</notes>
</release>
+ <release>
+ <version>
+ <release>1.2.0</release>
+ <api>1.2.0</api>
+ </version>
+ <stability>
+ <release>stable</release>
+ <api>stable</api>
+ </stability>
+ <date>2017-03-20</date>
+ <license>BSD</license>
+ <notes>
+ - Added arg info macros #9751
+ - Updated codegen to be consistent with protobuf #9492
+ </notes>
+ </release>
</changelog>
</package>
diff --git a/templates/src/csharp/build_packages_dotnetcli.bat.template b/templates/src/csharp/build_packages_dotnetcli.bat.template
index 3db1e0a..8624c34 100755
--- a/templates/src/csharp/build_packages_dotnetcli.bat.template
+++ b/templates/src/csharp/build_packages_dotnetcli.bat.template
@@ -53,11 +53,11 @@
@rem To be able to build, we also need to put grpc_csharp_ext to its normal location
xcopy /Y /I nativelibs\csharp_ext_windows_x64\grpc_csharp_ext.dll ..\..\cmake\build\x64\Release${"\\"}
- %%DOTNET% pack --configuration Release Grpc.Core --output ..\..\..\artifacts || goto :error
- %%DOTNET% pack --configuration Release Grpc.Core.Testing --output ..\..\..\artifacts || goto :error
- %%DOTNET% pack --configuration Release Grpc.Auth --output ..\..\..\artifacts || goto :error
- %%DOTNET% pack --configuration Release Grpc.HealthCheck --output ..\..\..\artifacts || goto :error
- %%DOTNET% pack --configuration Release Grpc.Reflection --output ..\..\..\artifacts || goto :error
+ %%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Core --output ..\..\..\artifacts || goto :error
+ %%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Core.Testing --output ..\..\..\artifacts || goto :error
+ %%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Auth --output ..\..\..\artifacts || goto :error
+ %%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.HealthCheck --output ..\..\..\artifacts || goto :error
+ %%DOTNET% pack --configuration Release --include-symbols --include-source Grpc.Reflection --output ..\..\..\artifacts || goto :error
%%NUGET% pack Grpc.nuspec -Version %VERSION% -OutputDirectory ..\..\artifacts || goto :error
%%NUGET% pack Grpc.Tools.nuspec -Version %VERSION% -OutputDirectory ..\..\artifacts
diff --git a/templates/src/csharp/build_packages_dotnetcli.sh.template b/templates/src/csharp/build_packages_dotnetcli.sh.template
index 65afec5..bff497c 100755
--- a/templates/src/csharp/build_packages_dotnetcli.sh.template
+++ b/templates/src/csharp/build_packages_dotnetcli.sh.template
@@ -50,11 +50,11 @@
mkdir -p ../../libs/opt
cp nativelibs/csharp_ext_linux_x64/libgrpc_csharp_ext.so ../../libs/opt
- dotnet pack --configuration Release Grpc.Core --output ../../../artifacts
- dotnet pack --configuration Release Grpc.Core.Testing --output ../../../artifacts
- dotnet pack --configuration Release Grpc.Auth --output ../../../artifacts
- dotnet pack --configuration Release Grpc.HealthCheck --output ../../../artifacts
- dotnet pack --configuration Release Grpc.Reflection --output ../../../artifacts
+ dotnet pack --configuration Release --include-symbols --include-source Grpc.Core --output ../../../artifacts
+ dotnet pack --configuration Release --include-symbols --include-source Grpc.Core.Testing --output ../../../artifacts
+ dotnet pack --configuration Release --include-symbols --include-source Grpc.Auth --output ../../../artifacts
+ dotnet pack --configuration Release --include-symbols --include-source Grpc.HealthCheck --output ../../../artifacts
+ dotnet pack --configuration Release --include-symbols --include-source Grpc.Reflection --output ../../../artifacts
nuget pack Grpc.nuspec -Version "${settings.csharp_version}" -OutputDirectory ../../artifacts
nuget pack Grpc.Tools.nuspec -Version "${settings.csharp_version}" -OutputDirectory ../../artifacts
diff --git a/templates/src/php/ext/grpc/version.h.template b/templates/src/php/ext/grpc/version.h.template
new file mode 100644
index 0000000..828ea69
--- /dev/null
+++ b/templates/src/php/ext/grpc/version.h.template
@@ -0,0 +1,42 @@
+%YAML 1.2
+--- |
+ /*
+ *
+ * Copyright 2015, Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ * * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+
+ #ifndef VERSION_H
+ #define VERSION_H
+
+ #define PHP_GRPC_VERSION "${settings.php_version.php_composer()}"
+
+ #endif /* VERSION_H */
diff --git a/tools/dockerfile/grpc_artifact_linux_armv6/Dockerfile b/tools/dockerfile/grpc_artifact_linux_armv6/Dockerfile
new file mode 100644
index 0000000..b085dd0
--- /dev/null
+++ b/tools/dockerfile/grpc_artifact_linux_armv6/Dockerfile
@@ -0,0 +1,39 @@
+# Copyright 2017, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+# Docker file for building gRPC Raspbian binaries
+
+FROM quay.io/grpc/raspbian_armv6
+
+# Place any extra build instructions between these commands
+# Recommend modifying upstream docker image (quay.io/grpc/raspbian_armv6)
+# for build steps because running them under QEMU is very slow
+# (https://github.com/kpayson64/armv7hf-debian-qemu)
+# RUN [ "cross-build-start" ]
+# RUN [ "cross-build-end" ]
diff --git a/tools/dockerfile/grpc_artifact_linux_armv7/Dockerfile b/tools/dockerfile/grpc_artifact_linux_armv7/Dockerfile
new file mode 100644
index 0000000..d7759a6
--- /dev/null
+++ b/tools/dockerfile/grpc_artifact_linux_armv7/Dockerfile
@@ -0,0 +1,39 @@
+# Copyright 2017, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+# Docker file for building gRPC Raspbian binaries
+
+FROM quay.io/grpc/raspbian_armv7
+
+# Place any extra build instructions between these commands
+# Recommend modifying upstream docker image (quay.io/grpc/raspbian_armv7)
+# for build steps because running them under QEMU is very slow
+# (https://github.com/kpayson64/armv7hf-debian-qemu)
+# RUN [ "cross-build-start" ]
+# RUN [ "cross-build-end" ]
diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++
index b7531bc..b6f2857 100644
--- a/tools/doxygen/Doxyfile.c++
+++ b/tools/doxygen/Doxyfile.c++
@@ -794,6 +794,7 @@
doc/stress_test_framework.md \
doc/unit_testing.md \
doc/wait-for-ready.md \
+doc/workarounds.md \
include/grpc++/alarm.h \
include/grpc++/channel.h \
include/grpc++/client_context.h \
diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal
index c8ebb0d..5242172 100644
--- a/tools/doxygen/Doxyfile.c++.internal
+++ b/tools/doxygen/Doxyfile.c++.internal
@@ -794,6 +794,7 @@
doc/stress_test_framework.md \
doc/unit_testing.md \
doc/wait-for-ready.md \
+doc/workarounds.md \
include/grpc++/alarm.h \
include/grpc++/channel.h \
include/grpc++/client_context.h \
diff --git a/tools/doxygen/Doxyfile.core b/tools/doxygen/Doxyfile.core
index 74e76bf..c5ae421 100644
--- a/tools/doxygen/Doxyfile.core
+++ b/tools/doxygen/Doxyfile.core
@@ -794,6 +794,7 @@
doc/stress_test_framework.md \
doc/unit_testing.md \
doc/wait-for-ready.md \
+doc/workarounds.md \
include/grpc/byte_buffer.h \
include/grpc/byte_buffer_reader.h \
include/grpc/census.h \
diff --git a/tools/doxygen/Doxyfile.core.internal b/tools/doxygen/Doxyfile.core.internal
index d5eeebe..eb0883b 100644
--- a/tools/doxygen/Doxyfile.core.internal
+++ b/tools/doxygen/Doxyfile.core.internal
@@ -794,6 +794,7 @@
doc/stress_test_framework.md \
doc/unit_testing.md \
doc/wait-for-ready.md \
+doc/workarounds.md \
include/grpc/byte_buffer.h \
include/grpc/byte_buffer_reader.h \
include/grpc/census.h \
diff --git a/tools/run_tests/artifacts/artifact_targets.py b/tools/run_tests/artifacts/artifact_targets.py
index 5a71b96..e3658ac 100644
--- a/tools/run_tests/artifacts/artifact_targets.py
+++ b/tools/run_tests/artifacts/artifact_targets.py
@@ -41,7 +41,7 @@
def create_docker_jobspec(name, dockerfile_dir, shell_command, environ={},
flake_retries=0, timeout_retries=0, timeout_seconds=30*60,
- docker_base_image=None):
+ docker_base_image=None, extra_docker_args=None):
"""Creates jobspec for a task running under docker."""
environ = environ.copy()
environ['RUN_COMMAND'] = shell_command
@@ -56,6 +56,8 @@
if docker_base_image is not None:
docker_env['DOCKER_BASE_IMAGE'] = docker_base_image
+ if extra_docker_args is not None:
+ docker_env['EXTRA_DOCKER_ARGS'] = extra_docker_args
jobspec = jobset.JobSpec(
cmdline=['tools/run_tests/dockerize/build_and_run_docker.sh'] + docker_args,
environ=docker_env,
@@ -115,7 +117,22 @@
def build_jobspec(self):
environ = {}
- if self.platform == 'linux':
+ if self.platform == 'linux_extra':
+ # Raspberry Pi build
+ environ['PYTHON'] = '/usr/local/bin/python{}'.format(self.py_version)
+ environ['PIP'] = '/usr/local/bin/pip{}'.format(self.py_version)
+ # https://github.com/resin-io-projects/armv7hf-debian-qemu/issues/9
+ # A QEMU bug causes submodule update to hang, so we copy directly
+ environ['RELATIVE_COPY_PATH'] = '.'
+ extra_args = ' --entrypoint=/usr/bin/qemu-arm-static '
+ return create_docker_jobspec(self.name,
+ 'tools/dockerfile/grpc_artifact_linux_{}'.format(self.arch),
+ 'tools/run_tests/artifacts/build_artifact_python.sh',
+ environ=environ,
+ timeout_seconds=60*60*5,
+ docker_base_image='quay.io/grpc/raspbian_{}'.format(self.arch),
+ extra_docker_args=extra_args)
+ elif self.platform == 'linux':
if self.arch == 'x86':
environ['SETARCH_CMD'] = 'linux32'
# Inside the manylinux container, the python installations are located in
@@ -349,6 +366,14 @@
PythonArtifact('linux', 'x86', 'cp34-cp34m'),
PythonArtifact('linux', 'x86', 'cp35-cp35m'),
PythonArtifact('linux', 'x86', 'cp36-cp36m'),
+ PythonArtifact('linux_extra', 'armv7', '2.7'),
+ PythonArtifact('linux_extra', 'armv7', '3.4'),
+ PythonArtifact('linux_extra', 'armv7', '3.5'),
+ PythonArtifact('linux_extra', 'armv7', '3.6'),
+ PythonArtifact('linux_extra', 'armv6', '2.7'),
+ PythonArtifact('linux_extra', 'armv6', '3.4'),
+ PythonArtifact('linux_extra', 'armv6', '3.5'),
+ PythonArtifact('linux_extra', 'armv6', '3.6'),
PythonArtifact('linux', 'x64', 'cp27-cp27m'),
PythonArtifact('linux', 'x64', 'cp27-cp27mu'),
PythonArtifact('linux', 'x64', 'cp34-cp34m'),
diff --git a/tools/run_tests/dockerize/build_and_run_docker.sh b/tools/run_tests/dockerize/build_and_run_docker.sh
index 8c25c86..6189e9a 100755
--- a/tools/run_tests/dockerize/build_and_run_docker.sh
+++ b/tools/run_tests/dockerize/build_and_run_docker.sh
@@ -74,8 +74,9 @@
-v "$git_root:/var/local/jenkins/grpc:ro" \
-w /var/local/git/grpc \
--name=$CONTAINER_NAME \
+ $EXTRA_DOCKER_ARGS \
$DOCKER_IMAGE_NAME \
- bash -l "/var/local/jenkins/grpc/$DOCKER_RUN_SCRIPT" || FAILED="true"
+ /bin/bash -l "/var/local/jenkins/grpc/$DOCKER_RUN_SCRIPT" || FAILED="true"
# Copy output artifacts
if [ "$OUTPUT_DIR" != "" ]
diff --git a/tools/run_tests/run_tests.py b/tools/run_tests/run_tests.py
index 1a16b09..568774c 100755
--- a/tools/run_tests/run_tests.py
+++ b/tools/run_tests/run_tests.py
@@ -1440,6 +1440,9 @@
return True
except subprocess.CalledProcessError, e:
return False
+ except OSError, e:
+ # For languages other than C and Windows the binary won't exist
+ return False
# returns a list of things that failed (or an empty list on success)
@@ -1459,7 +1462,7 @@
suite_name=args.report_suite_name)
return []
- if not args.travis and not _has_epollexclusive() and 'epollex' in _POLLING_STRATEGIES[platform_string()]:
+ if not args.travis and not _has_epollexclusive() and platform_string() in _POLLING_STRATEGIES and 'epollex' in _POLLING_STRATEGIES[platform_string()]:
print('\n\nOmitting EPOLLEXCLUSIVE tests\n\n')
_POLLING_STRATEGIES[platform_string()].remove('epollex')