From d9c6760b396ff30884129d4fbc3daaf20f9e93ae Mon Sep 17 00:00:00 2001 From: Jan Tattermusch Date: Fri, 28 Apr 2017 12:21:23 +0200 Subject: [PATCH 01/38] include sources and symbols in C# nugets --- src/csharp/build_packages_dotnetcli.bat | 10 +++++----- src/csharp/build_packages_dotnetcli.sh | 10 +++++----- .../src/csharp/build_packages_dotnetcli.bat.template | 10 +++++----- .../src/csharp/build_packages_dotnetcli.sh.template | 10 +++++----- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/csharp/build_packages_dotnetcli.bat b/src/csharp/build_packages_dotnetcli.bat index cc9c6d11a5c..d823e958fa8 100755 --- a/src/csharp/build_packages_dotnetcli.bat +++ b/src/csharp/build_packages_dotnetcli.bat @@ -60,11 +60,11 @@ xcopy /Y /I ..\..\architecture=x64,language=protoc,platform=macos\artifacts\* pr @rem To be able to build, we also need to put grpc_csharp_ext to its normal location xcopy /Y /I nativelibs\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 57e8fd4895b..242c743b27d 100755 --- a/src/csharp/build_packages_dotnetcli.sh +++ b/src/csharp/build_packages_dotnetcli.sh @@ -64,11 +64,11 @@ dotnet restore Grpc.sln mkdir -p ../../libs/opt cp nativelibs/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.3.0" -OutputDirectory ../../artifacts nuget pack Grpc.Tools.nuspec -Version "1.3.0" -OutputDirectory ../../artifacts diff --git a/templates/src/csharp/build_packages_dotnetcli.bat.template b/templates/src/csharp/build_packages_dotnetcli.bat.template index 91808e0d266..5f6ffb97544 100755 --- a/templates/src/csharp/build_packages_dotnetcli.bat.template +++ b/templates/src/csharp/build_packages_dotnetcli.bat.template @@ -62,11 +62,11 @@ @rem To be able to build, we also need to put grpc_csharp_ext to its normal location xcopy /Y /I nativelibs\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 374b236f93c..d37f4eb4f4e 100755 --- a/templates/src/csharp/build_packages_dotnetcli.sh.template +++ b/templates/src/csharp/build_packages_dotnetcli.sh.template @@ -66,11 +66,11 @@ mkdir -p ../../libs/opt cp nativelibs/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 From 19792108ae693b9741ba43fb6d57cb771f27d8ee Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Tue, 2 May 2017 11:24:03 -0700 Subject: [PATCH 02/38] PHP: release 1.3, disable cares deps --- build.yaml | 1 - config.m4 | 56 +------------------- package.xml | 94 +++++++--------------------------- templates/config.m4.template | 6 +-- templates/package.xml.template | 21 ++++++-- 5 files changed, 38 insertions(+), 140 deletions(-) diff --git a/build.yaml b/build.yaml index 8e44ea43aa7..1b349d8b496 100644 --- a/build.yaml +++ b/build.yaml @@ -4471,7 +4471,6 @@ php_config_m4: deps: - grpc - gpr - - ares - boringssl headers: - src/php/ext/grpc/byte_buffer.h diff --git a/config.m4 b/config.m4 index 74b60c9241c..f80a205534a 100644 --- a/config.m4 +++ b/config.m4 @@ -8,8 +8,6 @@ if test "$PHP_GRPC" != "no"; then 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" @@ -21,10 +19,8 @@ if test "$PHP_GRPC" != "no"; then 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) ;; @@ -626,59 +622,10 @@ if test "$PHP_GRPC" != "no"; then 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) + -D_HAS_EXCEPTIONS=0 -DNOMINMAX -DGRPC_ARES=0) PHP_ADD_BUILD_DIR($ext_builddir/src/php/ext/grpc) @@ -771,6 +718,5 @@ if test "$PHP_GRPC" != "no"; then 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/package.xml b/package.xml index bad95d55762..c06660b8b36 100644 --- a/package.xml +++ b/package.xml @@ -10,7 +10,7 @@ grpc-packages@google.com yes - 2017-03-01 + 2017-05-02 1.3.1RC1 @@ -22,8 +22,7 @@ BSD -- Added arg info macros #9751 -- Updated codegen to be consistent with protobuf #9492 +- gRPC Core 1.3 uptake @@ -1027,79 +1026,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -1412,6 +1338,22 @@ Update to wrap gRPC C Core version 0.10.0 BSD - Added arg info macros #9751 +- Updated codegen to be consistent with protobuf #9492 + + + + + 1.2.0 + 1.2.0 + + + stable + stable + + 2017-03-20 + BSD + +- Added arg info macros #9751 - Updated codegen to be consistent with protobuf #9492 diff --git a/templates/config.m4.template b/templates/config.m4.template index 13ff7389e68..38d86e6c3c9 100644 --- a/templates/config.m4.template +++ b/templates/config.m4.template @@ -10,8 +10,6 @@ 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" @@ -23,10 +21,8 @@ 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) ;; @@ -46,7 +42,7 @@ , $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) + -D_HAS_EXCEPTIONS=0 -DNOMINMAX -DGRPC_ARES=0) PHP_ADD_BUILD_DIR($ext_builddir/src/php/ext/grpc) <% diff --git a/templates/package.xml.template b/templates/package.xml.template index 8655cfa1d94..463931ba7d0 100644 --- a/templates/package.xml.template +++ b/templates/package.xml.template @@ -12,7 +12,7 @@ grpc-packages@google.com yes - 2017-03-01 + 2017-05-02 ${settings.php_version.php()} @@ -24,8 +24,7 @@ BSD - - Added arg info macros #9751 - - Updated codegen to be consistent with protobuf #9492 + - gRPC Core 1.3 uptake @@ -355,6 +354,22 @@ BSD - Added arg info macros #9751 + - Updated codegen to be consistent with protobuf #9492 + + + + + 1.2.0 + 1.2.0 + + + stable + stable + + 2017-03-20 + BSD + + - Added arg info macros #9751 - Updated codegen to be consistent with protobuf #9492 From b1c69e4697c8a365ac8911ac0e40d0b7bcfb1bbb Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Tue, 2 May 2017 14:01:35 -0700 Subject: [PATCH 03/38] Switch Protobuf.js dependency back to version 5 --- package.json | 2 +- src/node/index.js | 53 +++++++++++++--------------- src/node/src/protobuf_js_5_common.js | 10 +++--- src/node/src/server.js | 8 +++-- src/node/test/common_test.js | 21 ++++++----- src/node/test/surface_test.js | 42 +++++++++------------- templates/package.json.template | 2 +- 7 files changed, 66 insertions(+), 72 deletions(-) diff --git a/package.json b/package.json index 0af43dd132f..1864339bac5 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/src/node/index.js b/src/node/index.js index 071bfd7927b..08489f9ca54 100644 --- a/src/node/index.js +++ b/src/node/index.js @@ -99,10 +99,6 @@ exports.loadObject = function loadObject(value, options) { 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); @@ -111,19 +107,6 @@ exports.loadObject = function loadObject(value, options) { 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: @@ -133,8 +116,6 @@ function applyProtoRoot(filename, root) { * 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. @@ -146,17 +127,31 @@ function applyProtoRoot(filename, root) { * @return {Object} 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 62cf2f4acaa..4041e05390f 100644 --- a/src/node/src/protobuf_js_5_common.js +++ b/src/node/src/protobuf_js_5_common.js @@ -45,8 +45,7 @@ var client = require('./client'); * 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 @@ exports.deserializeCls = function deserializeCls(cls, binaryAsBase64, 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 @@ exports.getProtobufServiceAttrs = function getProtobufServiceAttrs(service, 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 3450abed08f..25640a03743 100644 --- a/src/node/src/server.js +++ b/src/node/src/server.js @@ -779,6 +779,11 @@ Server.prototype.addService = function(service, implementation) { }); }; +var logAddProtoServiceDeprecationOnce = _.once(function() { + common.log(grpc.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 @@ -790,8 +795,7 @@ Server.prototype.addProtoService = function(service, implementation) { var options; var protobuf_js_5_common = require('./protobuf_js_5_common'); var protobuf_js_6_common = require('./protobuf_js_6_common'); - common.log(grpc.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 e1ce864f975..b7c2c6a8d66 100644 --- a/src/node/test/common_test.js +++ b/src/node/test/common_test.js @@ -37,16 +37,15 @@ var assert = require('assert'); 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 @@ describe('Proto message long int serialize and deserialize', function() { 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 @@ describe('Proto message bytes serialize and deserialize', function() { 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 @@ describe('Proto message bytes serialize and deserialize', function() { 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 @@ describe('Proto message enum serialize and deserialize', function() { 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 783028fa99f..d2f0511af2d 100644 --- a/src/node/test/surface_test.js +++ b/src/node/test/surface_test.js @@ -43,9 +43,8 @@ var ProtoBuf = require('protobufjs'); 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 @@ describe('Echo service', function() { 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 @@ describe('Echo service', function() { 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 @@ describe('Echo metadata', function() { 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 @@ describe('Client malformed response handling', function() { 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 @@ describe('Server serialization failure handling', function() { 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('Server serialization failure handling', function() { }); }); 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 @@ describe('Call propagation', function() { 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/templates/package.json.template b/templates/package.json.template index 3bae8fde430..551c25f0423 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", From 5a5cfad2ec7d107c0430d54b96d0421721538bf8 Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Tue, 2 May 2017 16:35:16 -0700 Subject: [PATCH 04/38] Fix a bit of documentation that doesn't apply to Protobuf.js 5 --- src/node/index.js | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/node/index.js b/src/node/index.js index 08489f9ca54..fb313ac88b5 100644 --- a/src/node/index.js +++ b/src/node/index.js @@ -64,8 +64,6 @@ grpc.setDefaultRootsPem(fs.readFileSync(SSL_ROOTS_PATH, 'ascii')); * 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. From 572cd7e5a4630d47d3c3608c23d914e503c8f249 Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Thu, 4 May 2017 10:02:44 -0700 Subject: [PATCH 05/38] Update version to 1.3.1 --- BUILD | 2 +- CMakeLists.txt | 2 +- Makefile | 4 ++-- build.yaml | 2 +- gRPC-Core.podspec | 2 +- gRPC-ProtoRPC.podspec | 2 +- gRPC-RxLibrary.podspec | 2 +- gRPC.podspec | 2 +- package.json | 2 +- package.xml | 4 ++-- src/cpp/common/version_cc.cc | 2 +- src/csharp/Grpc.Core/Version.csproj.include | 2 +- src/csharp/Grpc.Core/VersionInfo.cs | 2 +- src/csharp/build_packages_dotnetcli.bat | 2 +- src/csharp/build_packages_dotnetcli.sh | 4 ++-- src/node/health_check/package.json | 4 ++-- src/node/tools/package.json | 2 +- src/objective-c/!ProtoCompiler-gRPCPlugin.podspec | 2 +- src/objective-c/GRPCClient/private/version.h | 2 +- src/python/grpcio/grpc_version.py | 2 +- src/python/grpcio_health_checking/grpc_version.py | 2 +- src/python/grpcio_reflection/grpc_version.py | 2 +- src/python/grpcio_tests/grpc_version.py | 2 +- src/ruby/lib/grpc/version.rb | 2 +- src/ruby/tools/version.rb | 2 +- tools/distrib/python/grpcio_tools/grpc_version.py | 2 +- tools/doxygen/Doxyfile.c++ | 2 +- tools/doxygen/Doxyfile.c++.internal | 2 +- 28 files changed, 32 insertions(+), 32 deletions(-) diff --git a/BUILD b/BUILD index f3942aec58c..da572181f27 100644 --- a/BUILD +++ b/BUILD @@ -42,7 +42,7 @@ g_stands_for = "gentle" core_version = "3.0.0" -version = "1.3.1-pre1" +version = "1.3.1" grpc_cc_library( name = "gpr", diff --git a/CMakeLists.txt b/CMakeLists.txt index e940ef63c04..51c272998f3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -39,7 +39,7 @@ cmake_minimum_required(VERSION 2.8) set(PACKAGE_NAME "grpc") -set(PACKAGE_VERSION "1.3.1-pre1") +set(PACKAGE_VERSION "1.3.1") set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}") set(PACKAGE_TARNAME "${PACKAGE_NAME}-${PACKAGE_VERSION}") set(PACKAGE_BUGREPORT "https://github.com/grpc/grpc/issues/") diff --git a/Makefile b/Makefile index bc28e4ecbe1..293a45902df 100644 --- a/Makefile +++ b/Makefile @@ -420,8 +420,8 @@ Q = @ endif CORE_VERSION = 3.0.0 -CPP_VERSION = 1.3.1-pre1 -CSHARP_VERSION = 1.3.1-pre1 +CPP_VERSION = 1.3.1 +CSHARP_VERSION = 1.3.1 CPPFLAGS_NO_ARCH += $(addprefix -I, $(INCLUDES)) $(addprefix -D, $(DEFINES)) CPPFLAGS += $(CPPFLAGS_NO_ARCH) $(ARCH_FLAGS) diff --git a/build.yaml b/build.yaml index 8e44ea43aa7..14abc8284db 100644 --- a/build.yaml +++ b/build.yaml @@ -14,7 +14,7 @@ settings: '#10': See the expand_version.py for all the quirks here core_version: 3.0.0 g_stands_for: gentle - version: 1.3.1-pre1 + version: 1.3.1 filegroups: - name: census public_headers: diff --git a/gRPC-Core.podspec b/gRPC-Core.podspec index 6b70a8560b8..561db476c29 100644 --- a/gRPC-Core.podspec +++ b/gRPC-Core.podspec @@ -37,7 +37,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-Core' - version = '1.3.1-pre1' + version = '1.3.1' s.version = version s.summary = 'Core cross-platform gRPC library, written in C' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-ProtoRPC.podspec b/gRPC-ProtoRPC.podspec index 73974b38bdf..4a83345237b 100644 --- a/gRPC-ProtoRPC.podspec +++ b/gRPC-ProtoRPC.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-ProtoRPC' - version = '1.3.1-pre1' + version = '1.3.1' s.version = version s.summary = 'RPC library for Protocol Buffers, based on gRPC' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-RxLibrary.podspec b/gRPC-RxLibrary.podspec index fbdeff5dfd4..83ecb613e1c 100644 --- a/gRPC-RxLibrary.podspec +++ b/gRPC-RxLibrary.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-RxLibrary' - version = '1.3.1-pre1' + version = '1.3.1' s.version = version s.summary = 'Reactive Extensions library for iOS/OSX.' s.homepage = 'http://www.grpc.io' diff --git a/gRPC.podspec b/gRPC.podspec index 738042ba869..29d3cb23b2b 100644 --- a/gRPC.podspec +++ b/gRPC.podspec @@ -35,7 +35,7 @@ Pod::Spec.new do |s| s.name = 'gRPC' - version = '1.3.1-pre1' + version = '1.3.1' s.version = version s.summary = 'gRPC client library for iOS/OSX' s.homepage = 'http://www.grpc.io' diff --git a/package.json b/package.json index 1864339bac5..51b6863ae34 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "grpc", - "version": "1.3.1-pre1", + "version": "1.3.1", "author": "Google Inc.", "description": "gRPC Library for Node", "homepage": "http://www.grpc.io/", diff --git a/package.xml b/package.xml index bad95d55762..fe50a96ad14 100644 --- a/package.xml +++ b/package.xml @@ -13,8 +13,8 @@ 2017-03-01 - 1.3.1RC1 - 1.3.1RC1 + 1.3.1 + 1.3.1 beta diff --git a/src/cpp/common/version_cc.cc b/src/cpp/common/version_cc.cc index 8d6445ed505..de0bafaff5e 100644 --- a/src/cpp/common/version_cc.cc +++ b/src/cpp/common/version_cc.cc @@ -37,5 +37,5 @@ #include namespace grpc { -grpc::string Version() { return "1.3.1-pre1"; } +grpc::string Version() { return "1.3.1"; } } diff --git a/src/csharp/Grpc.Core/Version.csproj.include b/src/csharp/Grpc.Core/Version.csproj.include index fb0fdbbabc4..25d3ca2e3b4 100755 --- a/src/csharp/Grpc.Core/Version.csproj.include +++ b/src/csharp/Grpc.Core/Version.csproj.include @@ -1,7 +1,7 @@ - 1.3.1-pre1 + 1.3.1 3.2.0 diff --git a/src/csharp/Grpc.Core/VersionInfo.cs b/src/csharp/Grpc.Core/VersionInfo.cs index dfe8c06e65d..2376485c684 100644 --- a/src/csharp/Grpc.Core/VersionInfo.cs +++ b/src/csharp/Grpc.Core/VersionInfo.cs @@ -53,6 +53,6 @@ namespace Grpc.Core /// /// Current version of gRPC C# /// - public const string CurrentVersion = "1.3.1-pre1"; + public const string CurrentVersion = "1.3.1"; } } diff --git a/src/csharp/build_packages_dotnetcli.bat b/src/csharp/build_packages_dotnetcli.bat index 2080685379f..1ed0ffa87c4 100755 --- a/src/csharp/build_packages_dotnetcli.bat +++ b/src/csharp/build_packages_dotnetcli.bat @@ -28,7 +28,7 @@ @rem OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @rem Current package versions -set VERSION=1.3.1-pre1 +set VERSION=1.3.1 @rem Adjust the location of nuget.exe set NUGET=C:\nuget\nuget.exe diff --git a/src/csharp/build_packages_dotnetcli.sh b/src/csharp/build_packages_dotnetcli.sh index ac6cc4e5879..4091ce7f9ad 100755 --- a/src/csharp/build_packages_dotnetcli.sh +++ b/src/csharp/build_packages_dotnetcli.sh @@ -70,7 +70,7 @@ dotnet pack --configuration Release --include-symbols --include-source Grpc.Auth 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.3.1-pre1" -OutputDirectory ../../artifacts -nuget pack Grpc.Tools.nuspec -Version "1.3.1-pre1" -OutputDirectory ../../artifacts +nuget pack Grpc.nuspec -Version "1.3.1" -OutputDirectory ../../artifacts +nuget pack Grpc.Tools.nuspec -Version "1.3.1" -OutputDirectory ../../artifacts (cd ../../artifacts && zip csharp_nugets_dotnetcli.zip *.nupkg) diff --git a/src/node/health_check/package.json b/src/node/health_check/package.json index e7b50362fc5..b94518260f6 100644 --- a/src/node/health_check/package.json +++ b/src/node/health_check/package.json @@ -1,6 +1,6 @@ { "name": "grpc-health-check", - "version": "1.3.1-pre1", + "version": "1.3.1", "author": "Google Inc.", "description": "Health check service for use with gRPC", "repository": { @@ -15,7 +15,7 @@ } ], "dependencies": { - "grpc": "^1.3.1-pre1", + "grpc": "^1.3.1", "lodash": "^3.9.3", "google-protobuf": "^3.0.0" }, diff --git a/src/node/tools/package.json b/src/node/tools/package.json index 9fefd433d55..4556c127d99 100644 --- a/src/node/tools/package.json +++ b/src/node/tools/package.json @@ -1,6 +1,6 @@ { "name": "grpc-tools", - "version": "1.3.1-pre1", + "version": "1.3.1", "author": "Google Inc.", "description": "Tools for developing with gRPC on Node.js", "homepage": "http://www.grpc.io/", diff --git a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec index a0df2597e22..0312a381dce 100644 --- a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec +++ b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec @@ -42,7 +42,7 @@ Pod::Spec.new do |s| # exclamation mark ensures that other "regular" pods will be able to find it as it'll be installed # before them. s.name = '!ProtoCompiler-gRPCPlugin' - v = '1.3.1-pre1' + v = '1.3.1' s.version = v s.summary = 'The gRPC ProtoC plugin generates Objective-C files from .proto services.' s.description = <<-DESC diff --git a/src/objective-c/GRPCClient/private/version.h b/src/objective-c/GRPCClient/private/version.h index 83fe9e46d9c..7861e0a733e 100644 --- a/src/objective-c/GRPCClient/private/version.h +++ b/src/objective-c/GRPCClient/private/version.h @@ -38,4 +38,4 @@ // `tools/buildgen/generate_projects.sh`. -#define GRPC_OBJC_VERSION_STRING @"1.3.1-pre1" +#define GRPC_OBJC_VERSION_STRING @"1.3.1" diff --git a/src/python/grpcio/grpc_version.py b/src/python/grpcio/grpc_version.py index c0422372e80..495af70240f 100644 --- a/src/python/grpcio/grpc_version.py +++ b/src/python/grpcio/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio/grpc_version.py.template`!!! -VERSION='1.3.1rc1' +VERSION='1.3.1' diff --git a/src/python/grpcio_health_checking/grpc_version.py b/src/python/grpcio_health_checking/grpc_version.py index da7546381f9..c0dae962d02 100644 --- a/src/python/grpcio_health_checking/grpc_version.py +++ b/src/python/grpcio_health_checking/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_health_checking/grpc_version.py.template`!!! -VERSION='1.3.1rc1' +VERSION='1.3.1' diff --git a/src/python/grpcio_reflection/grpc_version.py b/src/python/grpcio_reflection/grpc_version.py index 367773f0889..bc9fb1f4afb 100644 --- a/src/python/grpcio_reflection/grpc_version.py +++ b/src/python/grpcio_reflection/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_reflection/grpc_version.py.template`!!! -VERSION='1.3.1rc1' +VERSION='1.3.1' diff --git a/src/python/grpcio_tests/grpc_version.py b/src/python/grpcio_tests/grpc_version.py index ce78dc93f22..1a2281b177f 100644 --- a/src/python/grpcio_tests/grpc_version.py +++ b/src/python/grpcio_tests/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_tests/grpc_version.py.template`!!! -VERSION='1.3.1rc1' +VERSION='1.3.1' diff --git a/src/ruby/lib/grpc/version.rb b/src/ruby/lib/grpc/version.rb index b6825fa1191..1e723a935e3 100644 --- a/src/ruby/lib/grpc/version.rb +++ b/src/ruby/lib/grpc/version.rb @@ -29,5 +29,5 @@ # GRPC contains the General RPC module. module GRPC - VERSION = '1.3.1.pre1' + VERSION = '1.3.1' end diff --git a/src/ruby/tools/version.rb b/src/ruby/tools/version.rb index e02b87e5da0..d9109372afa 100644 --- a/src/ruby/tools/version.rb +++ b/src/ruby/tools/version.rb @@ -29,6 +29,6 @@ module GRPC module Tools - VERSION = '1.3.1.pre1' + VERSION = '1.3.1' end end diff --git a/tools/distrib/python/grpcio_tools/grpc_version.py b/tools/distrib/python/grpcio_tools/grpc_version.py index ca1d268f890..9a12f6b84c3 100644 --- a/tools/distrib/python/grpcio_tools/grpc_version.py +++ b/tools/distrib/python/grpcio_tools/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/tools/distrib/python/grpcio_tools/grpc_version.py.template`!!! -VERSION='1.3.1rc1' +VERSION='1.3.1' diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index debd50638f0..8fa5b3ede59 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.1-pre1 +PROJECT_NUMBER = 1.3.1 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal index 7064e6641ba..d620f99ff1c 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.1-pre1 +PROJECT_NUMBER = 1.3.1 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a From d809a15ec4913c7a8cd38d679a78b3edcb716b69 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Wed, 3 May 2017 14:49:41 -0700 Subject: [PATCH 06/38] cpp doc nits --- doc/PROTOCOL-WEB.md | 2 +- doc/compression.md | 4 +- doc/cpp-style-guide.md | 3 +- doc/fail_fast.md | 2 +- doc/service_config.md | 4 +- doc/stress_test_framework.md | 2 +- ...alth_check_service_server_builder_option.h | 4 +- .../ext/proto_server_reflection_plugin.h | 4 +- include/grpc++/generic/generic_stub.h | 6 +- .../grpc++/health_check_service_interface.h | 18 +-- include/grpc++/impl/codegen/async_stream.h | 6 +- .../grpc++/impl/codegen/async_unary_call.h | 2 +- include/grpc++/impl/codegen/call.h | 4 +- include/grpc++/impl/codegen/call_hook.h | 3 +- include/grpc++/impl/codegen/client_context.h | 5 +- .../grpc++/impl/codegen/client_unary_call.h | 2 +- .../grpc++/impl/codegen/completion_queue.h | 3 +- .../impl/codegen/completion_queue_tag.h | 8 +- include/grpc++/impl/codegen/config.h | 6 +- .../grpc++/impl/codegen/method_handler_impl.h | 24 ++-- include/grpc++/impl/codegen/rpc_method.h | 1 + .../grpc++/impl/codegen/rpc_service_method.h | 8 +- .../impl/codegen/security/auth_context.h | 2 +- include/grpc++/impl/codegen/server_context.h | 8 +- include/grpc++/impl/codegen/service_type.h | 1 + .../grpc++/impl/codegen/status_code_enum.h | 6 + include/grpc++/impl/codegen/string_ref.h | 16 +-- include/grpc++/impl/codegen/stub_options.h | 1 + include/grpc++/impl/codegen/sync_stream.h | 4 +- include/grpc++/impl/codegen/time.h | 19 ++- include/grpc++/impl/server_builder_plugin.h | 14 +-- include/grpc++/resource_quota.h | 1 + .../grpc++/security/auth_metadata_processor.h | 22 ++-- include/grpc++/security/credentials.h | 18 +-- include/grpc++/security/server_credentials.h | 16 +-- include/grpc++/support/error_details.h | 16 +-- include/grpc++/test/mock_stream.h | 40 +++--- .../grpc++/test/server_context_test_spouse.h | 8 +- include/grpc/census.h | 98 +++++++-------- include/grpc/grpc.h | 2 +- include/grpc/grpc_security.h | 116 +++++++++--------- include/grpc/grpc_security_constants.h | 18 +-- include/grpc/impl/codegen/atm.h | 2 +- include/grpc/impl/codegen/atm_windows.h | 8 +- .../grpc/impl/codegen/byte_buffer_reader.h | 4 +- include/grpc/impl/codegen/compression_types.h | 2 +- include/grpc/impl/codegen/gpr_slice.h | 3 +- include/grpc/impl/codegen/gpr_types.h | 12 +- include/grpc/impl/codegen/grpc_types.h | 63 ++++++---- include/grpc/impl/codegen/propagation_bits.h | 4 +- include/grpc/impl/codegen/slice.h | 22 ++-- include/grpc/impl/codegen/status.h | 41 ++++--- include/grpc/impl/codegen/sync.h | 2 +- include/grpc/slice.h | 49 ++++---- include/grpc/slice_buffer.h | 30 ++--- include/grpc/support/alloc.h | 14 +-- include/grpc/support/cmdline.h | 20 +-- include/grpc/support/cpu.h | 6 +- include/grpc/support/histogram.h | 2 +- include/grpc/support/host_port.h | 4 +- include/grpc/support/log.h | 16 +-- include/grpc/support/log_windows.h | 2 +- include/grpc/support/string_util.h | 6 +- include/grpc/support/subprocess.h | 6 +- include/grpc/support/sync.h | 62 +++++----- include/grpc/support/thd.h | 22 ++-- include/grpc/support/time.h | 24 ++-- include/grpc/support/tls.h | 2 +- include/grpc/support/tls_gcc.h | 4 +- include/grpc/support/tls_msvc.h | 2 +- include/grpc/support/tls_pthread.h | 2 +- include/grpc/support/useful.h | 4 +- 72 files changed, 508 insertions(+), 479 deletions(-) diff --git a/doc/PROTOCOL-WEB.md b/doc/PROTOCOL-WEB.md index 6bb280894ab..5f37df9b0f3 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 de245d90fee..ee22bc3f127 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 @@ unsupported condition as well as the supported ones. The returned 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 a1f91353fe9..8211703d02b 100644 --- a/doc/cpp-style-guide.md +++ b/doc/cpp-style-guide.md @@ -5,5 +5,4 @@ The majority of gRPC's C++ requirements are drawn from the [Google C++ style 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 2dd5561fc67..ff3d235397d 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 8039fcad095..e790180f355 100644 --- a/doc/service_config.md +++ b/doc/service_config.md @@ -131,8 +131,8 @@ functionality is introduced. # 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 [nameresolver](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 18f545e090e..2212d9842c4 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/include/grpc++/ext/health_check_service_server_builder_option.h b/include/grpc++/ext/health_check_service_server_builder_option.h index 4861daacd40..a27841af01d 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 @@ namespace grpc { 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 hc); ~HealthCheckServiceServerBuilderOption() override {} diff --git a/include/grpc++/ext/proto_server_reflection_plugin.h b/include/grpc++/ext/proto_server_reflection_plugin.h index 66f39eb8760..6497bba905c 100644 --- a/include/grpc++/ext/proto_server_reflection_plugin.h +++ b/include/grpc++/ext/proto_server_reflection_plugin.h @@ -59,8 +59,8 @@ class ProtoServerReflectionPlugin : public ::grpc::ServerBuilderPlugin { std::shared_ptr 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 02c00d0d45c..3c11e550018 100644 --- a/include/grpc++/generic/generic_stub.h +++ b/include/grpc++/generic/generic_stub.h @@ -43,14 +43,14 @@ class CompletionQueue; typedef ClientAsyncReaderWriter 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 channel) : channel_(channel) {} - // begin a call to a named method + /// begin a call to a named method std::unique_ptr Call( ClientContext* context, const grpc::string& method, CompletionQueue* cq, void* tag); diff --git a/include/grpc++/health_check_service_interface.h b/include/grpc++/health_check_service_interface.h index 0eed7026839..8323e9e5542 100644 --- a/include/grpc++/health_check_service_interface.h +++ b/include/grpc++/health_check_service_interface.h @@ -41,26 +41,26 @@ namespace grpc { 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. +/// 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 f97d824bafe..39f0ebd86fa 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -155,7 +155,7 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface { ClientAsyncReader(call, context, request, tag); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncReader)); } @@ -235,7 +235,7 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { ClientAsyncWriter(call, context, response, tag); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncWriter)); } @@ -338,7 +338,7 @@ class ClientAsyncReaderWriter final ClientAsyncReaderWriter(call, context, tag); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncReaderWriter)); } diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h index a147a6acbf8..ea2da421984 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -71,7 +71,7 @@ class ClientAsyncResponseReader final ClientAsyncResponseReader(call, context, request); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncResponseReader)); } diff --git a/include/grpc++/impl/codegen/call.h b/include/grpc++/impl/codegen/call.h index 9fe2bbb75e7..bbd0fc2dc80 100644 --- a/include/grpc++/impl/codegen/call.h +++ b/include/grpc++/impl/codegen/call.h @@ -634,10 +634,10 @@ class SneakyCallOpSet : public CallOpSet { } }; -// 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 6a8258233db..812c4a91e70 100644 --- a/include/grpc++/impl/codegen/call_hook.h +++ b/include/grpc++/impl/codegen/call_hook.h @@ -39,7 +39,8 @@ namespace grpc { class CallOpSetInterface; class Call; -/// Channel and Server implement this to allow them to hook performing ops +/// 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 3c50e6ba9d4..c17ce201867 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -151,6 +151,7 @@ namespace testing { class InteropClientContextInspector; } // namespace testing +/// Gives access to client side RPC configuration. class ClientContext { public: ClientContext(); @@ -325,8 +326,8 @@ class ClientContext { }; 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 4bf35ae7785..b923498db87 100644 --- a/include/grpc++/impl/codegen/client_unary_call.h +++ b/include/grpc++/impl/codegen/client_unary_call.h @@ -47,7 +47,7 @@ class ClientContext; class CompletionQueue; class RpcMethod; -// Wrapper that performs a blocking unary call +/// Wrapper that performs a blocking unary call template 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 c8ab726b0f4..57333d71581 100644 --- a/include/grpc++/impl/codegen/completion_queue.h +++ b/include/grpc++/impl/codegen/completion_queue.h @@ -159,7 +159,8 @@ class CompletionQueue : private GrpcLibraryCodegen { /// 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 19a08500cf8..0affc818e87 100644 --- a/include/grpc++/impl/codegen/completion_queue_tag.h +++ b/include/grpc++/impl/codegen/completion_queue_tag.h @@ -40,10 +40,10 @@ namespace grpc { 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 a43bf65f913..79352eee3c6 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 83b569ce74f..8dfaf5883c2 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 RpcMethodHandler : public MethodHandler { public: @@ -77,7 +77,7 @@ class RpcMethodHandler : public MethodHandler { } private: - // Application provided rpc handler function. + /// Application provided rpc handler function. std::function func_; @@ -85,7 +85,7 @@ class RpcMethodHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided client streaming handler. +/// A wrapper class of an application provided client streaming handler. template class ClientStreamingHandler : public MethodHandler { public: @@ -125,7 +125,7 @@ class ClientStreamingHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided server streaming handler. +/// A wrapper class of an application provided server streaming handler. template class ServerStreamingHandler : public MethodHandler { public: @@ -166,13 +166,13 @@ class ServerStreamingHandler : public MethodHandler { 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 TemplatedBidiStreamingHandler : public MethodHandler { public: @@ -249,7 +249,7 @@ class SplitServerStreamingHandler ServerSplitStreamer, false>(func) {} }; -// Handle unknown method by returning UNIMPLEMENTED error. +/// Handle unknown method by returning UNIMPLEMENTED error. class UnknownMethodHandler : public MethodHandler { public: template diff --git a/include/grpc++/impl/codegen/rpc_method.h b/include/grpc++/impl/codegen/rpc_method.h index 48974280747..ca7527507c0 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 eb8f9a1096e..96bb739c994 100644 --- a/include/grpc++/impl/codegen/rpc_service_method.h +++ b/include/grpc++/impl/codegen/rpc_service_method.h @@ -52,7 +52,7 @@ namespace grpc { 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 @@ class MethodHandler { 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 75f24823467..e83877bcaf9 100644 --- a/include/grpc++/impl/codegen/security/auth_context.h +++ b/include/grpc++/impl/codegen/security/auth_context.h @@ -99,7 +99,7 @@ class AuthContext { 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 ada304d5719..07e3710b4bc 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -91,7 +91,7 @@ class InteropServerContextInspector; class ServerContextTestSpouse; } // namespace testing -// Interface of server side rpc context. +/// Interface of server side rpc context. class ServerContext { public: ServerContext(); // for async calls @@ -106,9 +106,9 @@ class ServerContext { void AddInitialMetadata(const grpc::string& key, const grpc::string& value); 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 diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index bd65ea009e2..0df90678b18 100644 --- a/include/grpc++/impl/codegen/service_type.h +++ b/include/grpc++/impl/codegen/service_type.h @@ -61,6 +61,7 @@ class ServerAsyncStreamingInterface { virtual void BindCall(Call* call) = 0; }; +/// Desriptor of an RPC service and its various RPC methods class Service { public: Service() : server_(nullptr) {} diff --git a/include/grpc++/impl/codegen/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h index 9a90a18e2a5..2eb97e83c11 100644 --- a/include/grpc++/impl/codegen/status_code_enum.h +++ b/include/grpc++/impl/codegen/status_code_enum.h @@ -136,6 +136,12 @@ enum StatusCode { /// 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 003793823c0..4ed11b1b6ce 100644 --- a/include/grpc++/impl/codegen/string_ref.h +++ b/include/grpc++/impl/codegen/string_ref.h @@ -55,14 +55,14 @@ namespace grpc { /// compatibility. class string_ref { public: - // types + /// types typedef const char* const_iterator; typedef std::reverse_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 @@ class string_ref { 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 @@ class string_ref { 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 @@ class string_ref { 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 8e966a8dbf3..41aef19ab09 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 a010924cefe..34b814e9e39 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -516,7 +516,7 @@ class ServerReaderWriterInterface : public ServerStreamingInterface, public WriterInterface, public ReaderInterface {}; -// Actual implementation of bi-directional streaming +/// Actual implementation of bi-directional streaming namespace internal { template class ServerReaderWriterBody final { @@ -576,7 +576,7 @@ class ServerReaderWriterBody final { }; } // namespace internal -// class to represent the user API for a bidirectional streaming call +/// class to represent the user API for a bidirectional streaming call template class ServerReaderWriter final : public ServerReaderWriterInterface { public: diff --git a/include/grpc++/impl/codegen/time.h b/include/grpc++/impl/codegen/time.h index e090ece7567..81ca7bb3dec 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: - - 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. +/** 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. */ - template class TimePoint { public: diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h index 61632e32fa4..76972328074 100644 --- a/include/grpc++/impl/server_builder_plugin.h +++ b/include/grpc++/impl/server_builder_plugin.h @@ -48,19 +48,19 @@ class ServerBuilderPlugin { 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 68a514658d9..da14088ebb4 100644 --- a/include/grpc++/resource_quota.h +++ b/include/grpc++/resource_quota.h @@ -47,6 +47,7 @@ namespace grpc { /// 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 1ae32d0f6c8..35369231464 100644 --- a/include/grpc++/security/auth_metadata_processor.h +++ b/include/grpc++/security/auth_metadata_processor.h @@ -49,19 +49,19 @@ class AuthMetadataProcessor { 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 59861b78d86..8d9d181fde0 100644 --- a/include/grpc++/security/credentials.h +++ b/include/grpc++/security/credentials.h @@ -204,23 +204,23 @@ std::shared_ptr InsecureChannelCredentials(); /// Credentials for a channel using Cronet. std::shared_ptr 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 229bab8d849..4676b04c5d0 100644 --- a/include/grpc++/security/server_credentials.h +++ b/include/grpc++/security/server_credentials.h @@ -46,13 +46,13 @@ struct grpc_server; 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& processor) = 0; @@ -70,7 +70,7 @@ class ServerCredentials { /// 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 @@ struct SslServerCredentialsOptions { }; grpc::string pem_root_certs; std::vector 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++/support/error_details.h b/include/grpc++/support/error_details.h index 411175fb46c..d4324d35cf4 100644 --- a/include/grpc++/support/error_details.h +++ b/include/grpc++/support/error_details.h @@ -44,16 +44,16 @@ class Status; 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 f2de9472d6b..f6e94a48b3d 100644 --- a/include/grpc++/test/mock_stream.h +++ b/include/grpc++/test/mock_stream.h @@ -50,14 +50,14 @@ class MockClientReader : public ClientReaderInterface { 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 @@ class MockClientWriter : public ClientWriterInterface { 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 @@ class MockClientReaderWriter : public ClientReaderWriterInterface { 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 MockClientAsyncResponseReader @@ -113,11 +113,11 @@ class MockClientAsyncReader : public ClientAsyncReaderInterface { 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 @@ class MockClientAsyncWriter : public ClientAsyncWriterInterface { 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 @@ class MockClientAsyncReaderWriter 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 bac0db7bdc5..5bd07e7aec6 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(key, value)); @@ -70,7 +70,7 @@ class ServerContextTestSpouse { } private: - ServerContext* ctx_; // not owned + ServerContext* ctx_; /// not owned std::multimap client_metadata_storage_; }; diff --git a/include/grpc/census.h b/include/grpc/census.h index 822c42c0a46..68cefd86a11 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 @@ CENSUSAPI int census_enabled(void); 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 @@ typedef struct { 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 @@ CENSUSAPI census_context *census_context_create( 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 @@ typedef struct { 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 int census_context_get_tag(const census_context *context, 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 @@ CENSUSAPI int census_trace_mask(const census_context *context); /** 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 @@ CENSUSAPI void census_set_trace_mask(int trace_mask); 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 @@ CENSUSAPI void census_trace_print(census_context *context, uint32_t type, /** 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 @@ CENSUSAPI int census_get_trace_record(census_trace_record *trace_record); /** 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 @@ CENSUSAPI void census_trace_scan_end(); 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 void census_trace_scan_end(); 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 1eeb075927d..a36367fa8f9 100644 --- a/include/grpc/grpc.h +++ b/include/grpc/grpc.h @@ -287,7 +287,7 @@ GRPCAPI grpc_channel *grpc_lame_client_channel_create( /** 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 5d3cc4fd674..4f355068822 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 @@ typedef struct grpc_auth_property_iterator { 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 @@ GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void); 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 @@ typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)( 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 @@ GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create( 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 @@ GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create( 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 grpc_call_credentials *grpc_google_compute_engine_credentials_create( 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 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key, 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 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key, 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 @@ typedef void (*grpc_credentials_plugin_metadata_cb)( 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 @@ typedef struct { 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 @@ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create( 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 @@ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex( 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 @@ typedef void (*grpc_process_auth_metadata_done_cb)( 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 da05c5a97b3..d7ac0b27458 100644 --- a/include/grpc/grpc_security_constants.h +++ b/include/grpc/grpc_security_constants.h @@ -45,30 +45,30 @@ extern "C" { #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 @@ typedef enum { 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 @@ typedef enum { 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 @@ typedef enum { 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 4bd572d6d18..d348f32f678 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 a533651f6f9..fa842a30484 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 typedef intptr_t gpr_atm; @@ -64,7 +64,7 @@ static __inline void gpr_atm_no_barrier_store(gpr_atm *p, gpr_atm value) { } 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 int gpr_atm_full_cas(gpr_atm *p, gpr_atm o, gpr_atm n) { 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_no_barrier_fetch_add(gpr_atm *p, } 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 85a48641408..354a28a14e2 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; 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 a563711e326..953b51d9c46 100644 --- a/include/grpc/impl/codegen/compression_types.h +++ b/include/grpc/impl/codegen/compression_types.h @@ -67,7 +67,7 @@ extern "C" { "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 c62e976b8f4..3797645442e 100644 --- a/include/grpc/impl/codegen/gpr_slice.h +++ b/include/grpc/impl/codegen/gpr_slice.h @@ -33,7 +33,8 @@ #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 +/** 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 diff --git a/include/grpc/impl/codegen/gpr_types.h b/include/grpc/impl/codegen/gpr_types.h index 34d8156b615..ee4425233d0 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 b2c38b2c924..dccbd6dbd69 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -50,7 +50,7 @@ extern "C" { 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 { @@ -162,7 +162,9 @@ typedef struct { /** 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. */ @@ -182,7 +184,7 @@ typedef struct { /** 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 @@ -206,7 +208,7 @@ typedef struct { /** 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? @@ -256,20 +258,24 @@ typedef struct { /** 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" @@ -285,9 +291,13 @@ typedef struct { * 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" @@ -334,12 +344,12 @@ typedef enum grpc_call_error { 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. */ @@ -350,7 +360,7 @@ typedef enum grpc_call_error { /** 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 */ @@ -373,7 +383,8 @@ typedef enum grpc_call_error { /** A single metadata element */ typedef struct grpc_metadata { - /* the key, value values are expected to line up with grpc_mdelem: if changing + /** 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; @@ -507,7 +518,7 @@ typedef struct grpc_op { 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; @@ -547,10 +558,10 @@ typedef struct grpc_op { /** 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; @@ -594,9 +605,9 @@ typedef enum { #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 4b645587648..f58edb0e8b8 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 @@ extern "C" { /** 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 b89a3f7910a..5c01c87cb81 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 @@ typedef struct grpc_slice_refcount_vtable { 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 @@ typedef struct grpc_slice_refcount { #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 @@ struct grpc_slice { #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 29e4570f7ce..a2ad6b19e66 100644 --- a/include/grpc/impl/codegen/status.h +++ b/include/grpc/impl/codegen/status.h @@ -39,40 +39,40 @@ extern "C" { #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 @@ typedef enum { 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 @@ typedef enum { 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 @@ typedef enum { 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 6a8e8a644f9..5a135fab4c7 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 9c4b158ae8d..bd54bc81501 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 @@ GPRAPI grpc_slice grpc_slice_ref(grpc_slice s); 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 @@ GPRAPI grpc_slice grpc_slice_new_with_user_data(void *p, size_t len, 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 @@ GPRAPI grpc_slice grpc_slice_malloc_large(size_t length); .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 @@ GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice); 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 @@ typedef enum { 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,36 @@ GPRAPI int grpc_slice_default_eq_impl(grpc_slice a, grpc_slice b); 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 +/** 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 cdbd74776c6..0d593954dcc 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 @@ GPRAPI size_t grpc_slice_buffer_add_indexed(grpc_slice_buffer *sb, 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 017d75a3d0e..99be2d161af 100644 --- a/include/grpc/support/alloc.h +++ b/include/grpc/support/alloc.h @@ -44,26 +44,26 @@ extern "C" { 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 5b7bc825949..5a83afb464e 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 @@ extern "C" { 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 6734feb391b..0da02ada222 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 c5450385284..96db758878c 100644 --- a/include/grpc/support/histogram.h +++ b/include/grpc/support/histogram.h @@ -48,7 +48,7 @@ GPRAPI gpr_histogram *gpr_histogram_create(double resolution, 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 15819543a91..ee786beb191 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 @@ extern "C" { 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 88346cc9f43..917b01183ac 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 @@ extern "C" { 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 @@ typedef enum gpr_log_severity { #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(const char *file, int line, gpr_log_severity severity, 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 struct { 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 943a8e908b3..b8a40784643 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 5ab983d15df..8b268a60066 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 2baa43ece2b..dfb80989dcf 100644 --- a/include/grpc/support/subprocess.h +++ b/include/grpc/support/subprocess.h @@ -42,13 +42,13 @@ extern "C" { 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 5cfeecb6017..7d727a0cfc2 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 @@ GPRAPI void gpr_cv_destroy(gpr_cv *cv); 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 @@ GPRAPI int gpr_ref_is_unique(gpr_refcount *r); 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 05142887932..ba6cbb0cb04 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 @@ extern "C" { 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 66bcfca6ed1..2384f5e9063 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 @@ GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /* The far past. */ #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 gpr_timespec gpr_time_from_hours(int64_t x, gpr_clock_type clock_type); 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 5365449f0da..a48c73b26f3 100644 --- a/include/grpc/support/tls.h +++ b/include/grpc/support/tls.h @@ -36,7 +36,7 @@ #include -/* 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 a47275f6f4a..9667524d34b 100644 --- a/include/grpc/support/tls_gcc.h +++ b/include/grpc/support/tls_gcc.h @@ -38,7 +38,7 @@ #include -/* 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 @@ struct gpr_gcc_thread_local { *((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 efc653b4e45..4ef8eeff0dc 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 e681da2ecd8..7cc6a406459 100644 --- a/include/grpc/support/tls_pthread.h +++ b/include/grpc/support/tls_pthread.h @@ -37,7 +37,7 @@ #include /* for GPR_ASSERT */ #include -/* 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 9d8314e4bef..c261fbaa14e 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)))) From a9f1e2566d084b8f428887523859312f78f511f4 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Fri, 5 May 2017 13:52:42 -0700 Subject: [PATCH 07/38] address comments --- doc/service_config.md | 2 +- include/grpc++/health_check_service_interface.h | 1 + include/grpc++/resource_quota.h | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/service_config.md b/doc/service_config.md index e790180f355..99d985f3bfe 100644 --- a/doc/service_config.md +++ b/doc/service_config.md @@ -131,7 +131,7 @@ functionality is introduced. # Architecture -A service config is associated with a server name. The [nameresolver](naming.md) +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. diff --git a/include/grpc++/health_check_service_interface.h b/include/grpc++/health_check_service_interface.h index 8323e9e5542..c1b43199a60 100644 --- a/include/grpc++/health_check_service_interface.h +++ b/include/grpc++/health_check_service_interface.h @@ -60,6 +60,7 @@ class HealthCheckServiceInterface { /// NOT thread safe. void EnableDefaultHealthCheckService(bool enable); +/// Returns whether the default health checking service is enabled. /// NOT thread safe. bool DefaultHealthCheckServiceEnabled(); diff --git a/include/grpc++/resource_quota.h b/include/grpc++/resource_quota.h index da14088ebb4..1199ae93810 100644 --- a/include/grpc++/resource_quota.h +++ b/include/grpc++/resource_quota.h @@ -47,7 +47,7 @@ namespace grpc { /// all attached entities below the ResourceQuota bound. class ResourceQuota final : private GrpcLibraryCodegen { public: - // \param name - a unique name for this ResourceQuota. + /// \param name - a unique name for this ResourceQuota. explicit ResourceQuota(const grpc::string& name); ResourceQuota(); ~ResourceQuota(); From a1137ce51fce3d3e2dd5b1916b76a0f27071c2d1 Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Tue, 9 May 2017 14:21:12 -0700 Subject: [PATCH 08/38] Improve how UV TCP servers and endpoints are shut down --- src/core/lib/iomgr/tcp_server_uv.c | 32 +++++++++++++++++++++++++----- src/core/lib/iomgr/tcp_uv.c | 14 +++++++------ 2 files changed, 35 insertions(+), 11 deletions(-) diff --git a/src/core/lib/iomgr/tcp_server_uv.c b/src/core/lib/iomgr/tcp_server_uv.c index e9246948f5b..d446e5312ad 100644 --- a/src/core/lib/iomgr/tcp_server_uv.c +++ b/src/core/lib/iomgr/tcp_server_uv.c @@ -56,6 +56,8 @@ struct grpc_tcp_listener { int port; /* linked list */ struct grpc_tcp_listener *next; + + bool closed; }; struct grpc_tcp_server { @@ -77,6 +79,8 @@ struct grpc_tcp_server { /* shutdown callback */ grpc_closure *shutdown_complete; + bool shutdown; + grpc_resource_quota *resource_quota; }; @@ -109,6 +113,7 @@ grpc_error *grpc_tcp_server_create(grpc_exec_ctx *exec_ctx, 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 @@ void grpc_tcp_server_shutdown_starting_add(grpc_tcp_server *s, } 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 @@ static void handle_close_callback(uv_handle_t *handle) { 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 @@ static void on_connect(uv_stream_t *server, int status) { 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 @@ static grpc_error *add_socket_to_server(grpc_tcp_server *s, uv_tcp_t *handle, 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 8e8db9f7b45..b9ca1a3690e 100644 --- a/src/core/lib/iomgr/tcp_uv.c +++ b/src/core/lib/iomgr/tcp_uv.c @@ -88,12 +88,12 @@ static void tcp_free(grpc_exec_ctx *exec_ctx, grpc_tcp *tcp) { #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_unref(grpc_exec_ctx *exec_ctx, grpc_tcp *tcp, 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 @@ static void uv_endpoint_shutdown(grpc_exec_ctx *exec_ctx, grpc_endpoint *ep, 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); } From 0f02908e67d637acfff579c2a97be20ebfca1b00 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Fri, 5 May 2017 14:47:38 -0700 Subject: [PATCH 09/38] address comments --- include/grpc++/generic/generic_stub.h | 6 +- include/grpc++/grpc++.h | 4 + include/grpc++/impl/codegen/async_stream.h | 280 +++++++++++++++++- .../grpc++/impl/codegen/async_unary_call.h | 77 ++++- include/grpc++/impl/codegen/call_hook.h | 4 +- include/grpc++/impl/codegen/client_context.h | 28 +- include/grpc++/impl/codegen/server_context.h | 119 ++++++-- .../grpc++/impl/codegen/status_code_enum.h | 1 - include/grpc++/impl/codegen/sync_stream.h | 219 ++++++++++++-- include/grpc++/impl/server_builder_plugin.h | 4 + 10 files changed, 677 insertions(+), 65 deletions(-) diff --git a/include/grpc++/generic/generic_stub.h b/include/grpc++/generic/generic_stub.h index 3c11e550018..fdd23772043 100644 --- a/include/grpc++/generic/generic_stub.h +++ b/include/grpc++/generic/generic_stub.h @@ -50,7 +50,11 @@ class GenericStub final { explicit GenericStub(std::shared_ptr channel) : channel_(channel) {} - /// begin a call to a named method + /// Begin a call to a named method \a method usign \a context. + /// A tag \a tag will be deliever 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 0). std::unique_ptr Call( ClientContext* context, const grpc::string& method, CompletionQueue* cq, void* tag); diff --git a/include/grpc++/grpc++.h b/include/grpc++/grpc++.h index daecfea4069..978b172346c 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++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index 39f0ebd86fa..5a685cbe554 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -58,11 +58,31 @@ class ClientAsyncStreamingInterface { /// \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. + /// + /// 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 \a + /// WritesDone. + /// * there are no more messages to be received from the server (which can + /// be known implicitly by the calling code, or known explicitly from an + /// earlier call to \a 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[out] status To be updated with the operation status. /// \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; }; @@ -82,6 +102,9 @@ class AsyncReaderInterface { /// /// \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; }; @@ -140,10 +163,16 @@ template class ClientAsyncReaderInterface : public ClientAsyncStreamingInterface, public AsyncReaderInterface {}; +/// 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 ClientAsyncReader final : public ClientAsyncReaderInterface { 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 static ClientAsyncReader* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -155,11 +184,19 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface { ClientAsyncReader(call, context, request, tag); } - /// always allocated against a call arena, no memory free required + // always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { 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_); @@ -168,6 +205,7 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface { call_.PerformOps(&meta_ops_); } + /// See the \a AsyncReaderInterface.Read method for semantics of this method. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -177,6 +215,11 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface { 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 +257,26 @@ template class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface { public: - /// Signal the client is done with the writes. + /// Signal the client is done with the writes (half-close the client stream). /// Thread-safe with respect to \a Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; +/// Async API to 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 ClientAsyncWriter final : public ClientAsyncWriterInterface { 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 static ClientAsyncWriter* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -235,11 +288,19 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { ClientAsyncWriter(call, context, response, tag); } - /// always allocated against a call arena, no memory free required + // always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { 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_); @@ -248,6 +309,8 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&meta_ops_); } + /// See the \a AsyncWriterInterface.Write(const W& msg, void* tag) + /// method for semantics of this method. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); // TODO(ctiller): don't assert @@ -255,6 +318,9 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&write_ops_); } + /// See the + /// \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) + /// method for semantics of this method. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -266,12 +332,21 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&write_ops_); } + /// See the \a ClientAsyncWriterInterface.WritesDone method for semantics of + /// this method. void WritesDone(void* tag) override { write_ops_.set_output_tag(tag); write_ops_.ClientSendClose(); 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 +385,33 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { 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, +/// abnd the server-to-client message stream has messages of type \a R. template class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface, public AsyncReaderInterface { public: - /// Signal the client is done with the writes. + /// Signal the client is done with the writes (half-close the client stream). /// Thread-safe with respect to \a 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 ClientAsyncReaderWriter final : public ClientAsyncReaderWriterInterface { 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, @@ -338,11 +423,18 @@ class ClientAsyncReaderWriter final ClientAsyncReaderWriter(call, context, tag); } - /// always allocated against a call arena, no memory free required + // always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { 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_); @@ -351,6 +443,8 @@ class ClientAsyncReaderWriter final call_.PerformOps(&meta_ops_); } + /// See \a AsyncReaderInterface.Read method for semantics + /// of this method. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -360,6 +454,8 @@ class ClientAsyncReaderWriter final call_.PerformOps(&read_ops_); } + /// See \a AsyncWriterInterface.Write(const W& msg, void* tag) method for + /// semantics of this method. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); // TODO(ctiller): don't assert @@ -367,6 +463,8 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) + /// method for semantics of this method. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -378,12 +476,18 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See \a ClientAsyncReaderWriterInterface.WritesDone method for semantics + /// of this method. void WritesDone(void* tag) override { write_ops_.set_output_tag(tag); write_ops_.ClientSendClose(); 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 +526,66 @@ template class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, public AsyncReaderInterface { 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 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), repsonse 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 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 ServerAsyncReader final : public ServerAsyncReaderInterface { public: explicit ServerAsyncReader(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// 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. + /// + /// 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_); @@ -446,12 +599,21 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { call_.PerformOps(&meta_ops_); } + /// See the \a AsyncReaderInterface.Read method for semantics. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); read_ops_.RecvMessage(msg); 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 +634,12 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { 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,6 +671,24 @@ template class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, public AsyncWriterInterface { 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 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), repsonse 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 @@ -520,12 +706,24 @@ class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, 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 ServerAsyncWriter final : public ServerAsyncWriterInterface { public: explicit ServerAsyncWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// Request notification of the sending the 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. + /// + /// 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_); @@ -539,6 +737,7 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { call_.PerformOps(&meta_ops_); } + /// See the \a AsyncWriterInterface.Write(const W &msg, void *tag) method for semantics. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&write_ops_); @@ -547,6 +746,7 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { call_.PerformOps(&write_ops_); } + /// See the \a AsyncWriterInterface.Write(const W &msg, WriteOptions options, void *tag) method for semantics. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -559,6 +759,13 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { 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 +776,13 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { 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,6 +820,24 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, public AsyncWriterInterface, public AsyncReaderInterface { 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 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), repsonse 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 @@ -623,6 +855,9 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, 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 ServerAsyncReaderWriter final : public ServerAsyncReaderWriterInterface { @@ -630,6 +865,16 @@ class ServerAsyncReaderWriter final explicit ServerAsyncReaderWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// Request notification of the sending the 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. + /// + /// 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_); @@ -643,12 +888,14 @@ class ServerAsyncReaderWriter final call_.PerformOps(&meta_ops_); } + /// See the \a AsyncReaderInterface.Read method for semantics. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); read_ops_.RecvMessage(msg); call_.PerformOps(&read_ops_); } + /// See the \a AsyncWriterInterface.Write(const W& msg, void* tag) method for semantics. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&write_ops_); @@ -657,6 +904,7 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See the \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) method for semantics. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -667,6 +915,13 @@ class ServerAsyncReaderWriter final 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 +932,13 @@ class ServerAsyncReaderWriter final 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 ea2da421984..15179e53d6e 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -55,10 +55,17 @@ class ClientAsyncResponseReaderInterface { 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 ClientAsyncResponseReader final : public ClientAsyncResponseReaderInterface { 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 static ClientAsyncResponseReader* Create(ChannelInterface* channel, CompletionQueue* cq, @@ -71,11 +78,24 @@ class ClientAsyncResponseReader final ClientAsyncResponseReader(call, context, request); } - /// always allocated against a call arena, no memory free required + // always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncResponseReader)); } + /// 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. + /// + /// Once a completion has been notified, the initial metadata read from + /// the server will be accessable through the \a ClientContext used to + /// construct this object. + /// + /// \param[in] tag Tag identifying this request. + /// 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 +104,24 @@ class ClientAsyncResponseReader final call_.PerformOps(&meta_buf_); } + /// 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. + /// + /// 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 +161,23 @@ class ClientAsyncResponseReader final 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 ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { public: explicit ServerAsyncResponseWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// Request notification of the sending the 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. + /// + /// 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 +191,21 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { 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 +226,17 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { 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_hook.h b/include/grpc++/impl/codegen/call_hook.h index 812c4a91e70..85a5f86ab7b 100644 --- a/include/grpc++/impl/codegen/call_hook.h +++ b/include/grpc++/impl/codegen/call_hook.h @@ -39,8 +39,8 @@ namespace grpc { class CallOpSetInterface; class Call; -/// An interface that Channel and Server implement 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 c17ce201867..31bd0d258a6 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -151,7 +151,20 @@ namespace testing { class InteropClientContextInspector; } // namespace testing -/// Gives access to client side RPC configuration. +/// 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(); @@ -223,13 +236,24 @@ class ClientContext { 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 not 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 + /// If set, grpc is free the 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 + /// See grpc/doc/wait-for-ready.md. + /// If set, if an RPC 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; diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index 07e3710b4bc..beaad1c6fa1 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -91,63 +91,129 @@ class InteropServerContextInspector; 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 Initial 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 parameter to the see \a grpc::Server +/// constructor. +/// +/// \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, it must be + /// base64-encoding (see https://tools.ietf.org/html/rfc4648#section-4) and \a + /// meta_key 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, it must be + /// base64-encoding (see https://tools.ietf.org/html/rfc4648#section-4) and \a + /// meta_key must end in "-bin". void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); - /// IsCancelled is always safe to call when using sync API + /// 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 + /// 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& 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& cost_data); + /// Return the authentication context for this server call. + /// + /// \see grpc::AuthContext. std::shared_ptr auth_context() const { if (auth_context_.get() == nullptr) { auth_context_ = CreateAuthContext(call_); @@ -155,24 +221,25 @@ class ServerContext { 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 +272,14 @@ class ServerContext { 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/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h index 2eb97e83c11..a60cdef60e8 100644 --- a/include/grpc++/impl/codegen/status_code_enum.h +++ b/include/grpc++/impl/codegen/status_code_enum.h @@ -141,7 +141,6 @@ enum StatusCode { /// 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/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index 34b814e9e39..ecde15fac9f 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -50,16 +50,28 @@ class ClientStreamingInterface { 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 \a + /// 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 Read that + /// returned "false" /// /// This function will return either: /// - when all incoming messages have been read and the server has returned /// status. - /// - OR when the server has returned a non-OK status. + /// - when the server has returned a non-OK status. + /// - OR when the call failed for some reason and the library generated a + /// 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 +80,12 @@ class ServerStreamingInterface { 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 +95,10 @@ class ReaderInterface { 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,7 +117,7 @@ class WriterInterface { public: virtual ~WriterInterface() {} - /// Blocking write \a msg to the stream with WriteOptions \a options. + /// Block to write \a msg to the stream with WriteOptions \a options. /// This is thread-safe with respect to \a Read /// /// \param msg The message to be written to the stream. @@ -109,7 +126,7 @@ class WriterInterface { /// \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. + /// Block to write \a msg to the stream with default write options. /// This is thread-safe with respect to \a Read /// /// \param msg The message to be written to the stream. @@ -141,17 +158,21 @@ template class ClientReaderInterface : public ClientStreamingInterface, public ReaderInterface { 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 ClientReader final : public ClientReaderInterface { 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 ClientReader(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, const W& request) @@ -172,6 +193,13 @@ class ClientReader final : public ClientReaderInterface { 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_); @@ -181,11 +209,17 @@ class ClientReader final : public ClientReaderInterface { cq_.Pluck(&ops); /// status ignored } + /// See the \a ReaderInterface.NextMessageSize for semantics. bool NextMessageSize(uint32_t* sz) override { *sz = call_.max_receive_message_size(); 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> ops; if (!context_->initial_metadata_received_) { @@ -196,6 +230,11 @@ class ClientReader final : public ClientReaderInterface { 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 ops; Status status; @@ -211,23 +250,30 @@ class ClientReader final : public ClientReaderInterface { 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 ClientWriterInterface : public ClientStreamingInterface, public WriterInterface { public: - /// Half close writing from the client. - /// Block until currently-pending writes are completed. + /// 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 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 ClientWriter : public ClientWriterInterface { 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 ClientWriter(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, R* response) @@ -248,6 +294,13 @@ class ClientWriter : public ClientWriterInterface { } } + /// 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 +310,12 @@ class ClientWriter : public ClientWriterInterface { 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::Write; bool Write(const W& msg, WriteOptions options) override { CallOpSet { return cq_.Pluck(&ops); } + /// See the \a ClientWriterInterface.WritesDone method for semantics. bool WritesDone() override { CallOpSet ops; ops.ClientSendClose(); @@ -287,7 +347,11 @@ class ClientWriter : public ClientWriterInterface { 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 +372,39 @@ class ClientWriter : public ClientWriterInterface { 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 ClientReaderWriterInterface : public ClientStreamingInterface, public WriterInterface, public ReaderInterface { 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. + /// 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 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 ClientReaderWriter final : public ClientReaderWriterInterface { 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 +421,13 @@ class ClientReaderWriter final : public ClientReaderWriterInterface { } } + /// 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 +442,10 @@ class ClientReaderWriter final : public ClientReaderWriterInterface { 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> ops; if (!context_->initial_metadata_received_) { @@ -371,6 +456,11 @@ class ClientReaderWriter final : public ClientReaderWriterInterface { 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::Write; bool Write(const W& msg, WriteOptions options) override { CallOpSet { return cq_.Pluck(&ops); } + /// See the ClientWriterInterface.WritesDone method for semantics. bool WritesDone() override { CallOpSet ops; ops.ClientSendClose(); @@ -401,6 +492,11 @@ class ClientReaderWriter final : public ClientReaderWriterInterface { 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 ops; if (!context_->initial_metadata_received_) { @@ -424,11 +520,18 @@ template class ServerReaderInterface : public ServerStreamingInterface, public ReaderInterface {}; +/// 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 ServerReader final : public ServerReaderInterface { 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_); @@ -443,11 +546,13 @@ class ServerReader final : public ServerReaderInterface { call_->cq()->Pluck(&ops); } + /// See the \a ReaderInterface.NextMessageSize method. bool NextMessageSize(uint32_t* sz) override { *sz = call_->max_receive_message_size(); return true; } + /// See the \a ReaderInterface.Read method for semantics. bool Read(R* msg) override { CallOpSet> ops; ops.RecvMessage(msg); @@ -465,11 +570,18 @@ template class ServerWriterInterface : public ServerStreamingInterface, public WriterInterface {}; +/// 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 ServerWriter final : public ServerWriterInterface { 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 +596,11 @@ class ServerWriter final : public ServerWriterInterface { 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::Write; bool Write(const W& msg, WriteOptions options) override { if (options.is_last_message()) { @@ -576,20 +693,32 @@ class ServerReaderWriterBody final { }; } // 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 ServerReaderWriter final : public ServerReaderWriterInterface { 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(); } + /// See the \a ReaderInterface.NextMessageSize method for semantics bool NextMessageSize(uint32_t* sz) override { return body_.NextMessageSize(sz); } + /// See the \a ReaderInterface.Read method for semantics 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::Write; bool Write(const W& msg, WriteOptions options) override { return body_.Write(msg, options); @@ -615,12 +744,27 @@ class ServerUnaryStreamer final 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 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 +773,13 @@ class ServerUnaryStreamer final return body_.Read(request); } + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a 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::Write; bool Write(const ResponseType& response, WriteOptions options) override { if (write_done_ || !read_done_) { @@ -656,12 +807,27 @@ class ServerSplitStreamer final 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 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 +836,13 @@ class ServerSplitStreamer final return body_.Read(request); } + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a 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::Write; bool Write(const ResponseType& response, WriteOptions options) override { return read_done_ && body_.Write(response, options); diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h index 76972328074..8ce16d66780 100644 --- a/include/grpc++/impl/server_builder_plugin.h +++ b/include/grpc++/impl/server_builder_plugin.h @@ -43,6 +43,10 @@ namespace grpc { class ServerInitializer; class ChannelArguments; +/// A builder class for the creation and startup of \a grpc::Server instances. +/// This is 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() {} From e9595bad1469475e066d7ef5f038c54abbac1e5c Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Tue, 9 May 2017 15:43:58 -0700 Subject: [PATCH 10/38] PHP: fixed some memory leaks --- package.xml | 5 +++-- src/php/ext/grpc/call.c | 26 +++++++++++++++++++------- src/php/ext/grpc/call_credentials.c | 28 +++++++++++++++++++++++++--- templates/package.xml.template | 5 +++-- 4 files changed, 50 insertions(+), 14 deletions(-) diff --git a/package.xml b/package.xml index 0a655ccc8af..12b9b6cd2c1 100644 --- a/package.xml +++ b/package.xml @@ -10,7 +10,7 @@ grpc-packages@google.com yes - 2017-05-02 + 2017-05-05 1.3.1 @@ -22,7 +22,7 @@ BSD -- gRPC Core 1.3 uptake +- Fixed some memory leaks #9559, #10996 @@ -1026,6 +1026,7 @@ + diff --git a/src/php/ext/grpc/call.c b/src/php/ext/grpc/call.c index 48a374fa08e..86bd40e03d0 100644 --- a/src/php/ext/grpc/call.c +++ b/src/php/ext/grpc/call.c @@ -125,7 +125,12 @@ zval *grpc_parse_metadata_array(grpc_metadata_array 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 @@ PHP_METHOD(Call, startBatch) { 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 @@ PHP_METHOD(Call, startBatch) { 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 @@ PHP_METHOD(Call, startBatch) { 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 @@ PHP_METHOD(Call, startBatch) { } 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 @@ PHP_METHOD(Call, startBatch) { 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 625c0c62ae3..da7100f24a5 100644 --- a/src/php/ext/grpc/call_credentials.c +++ b/src/php/ext/grpc/call_credentials.c @@ -172,34 +172,54 @@ void plugin_get_metadata(void *ptr, grpc_auth_metadata_context context, 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 @@ void plugin_destroy_state(void *ptr) { 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/templates/package.xml.template b/templates/package.xml.template index 463931ba7d0..394b8154eea 100644 --- a/templates/package.xml.template +++ b/templates/package.xml.template @@ -12,7 +12,7 @@ grpc-packages@google.com yes - 2017-05-02 + 2017-05-05 ${settings.php_version.php()} @@ -24,7 +24,7 @@ BSD - - gRPC Core 1.3 uptake + - Fixed some memory leaks #9559, #10996 @@ -42,6 +42,7 @@ % endfor % endif % endfor + From cdc0d03b2d868027f7b0158422885d58cc7b17ab Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 9 May 2017 16:04:10 -0700 Subject: [PATCH 11/38] Add EnableWorkaround API to enable server workarounds --- include/grpc++/server_builder.h | 6 ++++++ src/cpp/server/server_builder.cc | 15 +++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h index 7ac23349c84..7d34592dbb2 100644 --- a/include/grpc++/server_builder.h +++ b/include/grpc++/server_builder.h @@ -184,6 +184,11 @@ class ServerBuilder { static void InternalAddPluginFactory( std::unique_ptr (*CreatePlugin)()); + /// Enable a server workaround. Do not use unless you know what the workaround + /// does. For explanation and detailed descriptions of workarounds, see + /// docs/workarounds.md. + ServerBuilder& EnableWorkaround(uint32_t id); + private: friend class ::grpc::testing::ServerBuilderPluginTest; @@ -226,6 +231,7 @@ class ServerBuilder { std::vector> options_; std::vector> services_; std::vector ports_; + std::vector enabled_workarounds_; SyncServerSettings sync_server_settings_; diff --git a/src/cpp/server/server_builder.cc b/src/cpp/server/server_builder.cc index 2ead048a1ff..67a7846da54 100644 --- a/src/cpp/server/server_builder.cc +++ b/src/cpp/server/server_builder.cc @@ -39,6 +39,7 @@ #include #include #include +#include #include "src/cpp/server/thread_pool_interface.h" @@ -198,6 +199,10 @@ std::unique_ptr ServerBuilder::BuildAndStart() { args.SetInt(GRPC_ARG_MAX_SEND_MESSAGE_LENGTH, max_send_message_size_); } + for (auto workaround : enabled_workarounds_) { + args.SetInt(workaround, 1); + } + args.SetInt(GRPC_COMPRESSION_CHANNEL_ENABLED_ALGORITHMS_BITSET, enabled_compression_algorithms_bitset_); if (maybe_default_compression_level_.is_set) { @@ -358,4 +363,14 @@ void ServerBuilder::InternalAddPluginFactory( (*g_plugin_factory_list).push_back(CreatePlugin); } +void ServerBuilder::EnableWorkaround(uint32_t id) { + switch (id) { + case GRPC_WORKAROUND_ID_CRONET_COMPRESSION: + enabled_workarounds_.push_back(GRPC_ARG_WORKAROUND_CRONET_COMPRESSION); + break; + default: + gpr_log(GPR_ERROR, "Workaround %u is not exist or obsolete.", id); + } +} + } // namespace grpc From e22bd48cd93cf4c0b777e124631f14bb21073c6c Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 9 May 2017 16:24:31 -0700 Subject: [PATCH 12/38] Add cpp test --- test/cpp/server/server_builder_test.cc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/test/cpp/server/server_builder_test.cc b/test/cpp/server/server_builder_test.cc index 1d9eda17b40..68b2f656bca 100644 --- a/test/cpp/server/server_builder_test.cc +++ b/test/cpp/server/server_builder_test.cc @@ -40,6 +40,8 @@ #include "src/proto/grpc/testing/echo.grpc.pb.h" #include "test/core/util/port.h" +#include + namespace grpc { namespace { @@ -87,6 +89,15 @@ TEST(ServerBuilderTest, CreateServerRepeatedPortWithDisallowedReusePort) { nullptr); } +TEST(ServerBuilderTest, CreateServerOnePortWithCronetCompressionWorkaround) { + ServerBuilder() + .RegisterService(&g_service) + .AddListeningPort(g_port, InsecureServerCredentials()) + .EnableWorkaround(GRPC_WORKAROUND_ID_CRONET_COMPRESSION) + .BuildAndStart() + ->Shutdown(); +} + } // namespace } // namespace grpc From b1a80c751d99996bc3e48390081b3b0dfcfbc4e0 Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 9 May 2017 16:50:54 -0700 Subject: [PATCH 13/38] bug fixes --- include/grpc/impl/codegen/grpc_types.h | 2 +- src/cpp/server/server_builder.cc | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index a183e1382dc..37452e24c59 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -297,7 +297,7 @@ each time recvmsg (or equivalent) is called */ If 0 or unset, the balancer calls will have no deadline. */ #define GRPC_ARG_GRPCLB_CALL_TIMEOUT_MS "grpc.grpclb_timeout_ms" /** If non-zero, grpc server's cronet compression workaround will be enabled */ -#define GRPC_ARG_WORKAROUND_CRONET_COMPRESSION "grpc.socket_factory" +#define GRPC_ARG_WORKAROUND_CRONET_COMPRESSION "grpc.workaround.cronet_compression" /** \} */ /** Result of a grpc call. If the caller satisfies the prerequisites of a diff --git a/src/cpp/server/server_builder.cc b/src/cpp/server/server_builder.cc index 67a7846da54..92aa30c240e 100644 --- a/src/cpp/server/server_builder.cc +++ b/src/cpp/server/server_builder.cc @@ -363,7 +363,7 @@ void ServerBuilder::InternalAddPluginFactory( (*g_plugin_factory_list).push_back(CreatePlugin); } -void ServerBuilder::EnableWorkaround(uint32_t id) { +ServerBuilder& ServerBuilder::EnableWorkaround(uint32_t id) { switch (id) { case GRPC_WORKAROUND_ID_CRONET_COMPRESSION: enabled_workarounds_.push_back(GRPC_ARG_WORKAROUND_CRONET_COMPRESSION); @@ -371,6 +371,8 @@ void ServerBuilder::EnableWorkaround(uint32_t id) { default: gpr_log(GPR_ERROR, "Workaround %u is not exist or obsolete.", id); } + + return *this; } } // namespace grpc From f5b3db9c224a30b348acac88b379f5bea891808b Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 9 May 2017 17:12:24 -0700 Subject: [PATCH 14/38] Use AddChannelArgument method --- include/grpc++/server_builder.h | 1 - src/cpp/server/server_builder.cc | 12 +++--------- 2 files changed, 3 insertions(+), 10 deletions(-) diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h index 7d34592dbb2..ca9ea1bcfc4 100644 --- a/include/grpc++/server_builder.h +++ b/include/grpc++/server_builder.h @@ -231,7 +231,6 @@ class ServerBuilder { std::vector> options_; std::vector> services_; std::vector ports_; - std::vector enabled_workarounds_; SyncServerSettings sync_server_settings_; diff --git a/src/cpp/server/server_builder.cc b/src/cpp/server/server_builder.cc index 92aa30c240e..1da7836e453 100644 --- a/src/cpp/server/server_builder.cc +++ b/src/cpp/server/server_builder.cc @@ -199,10 +199,6 @@ std::unique_ptr ServerBuilder::BuildAndStart() { args.SetInt(GRPC_ARG_MAX_SEND_MESSAGE_LENGTH, max_send_message_size_); } - for (auto workaround : enabled_workarounds_) { - args.SetInt(workaround, 1); - } - args.SetInt(GRPC_COMPRESSION_CHANNEL_ENABLED_ALGORITHMS_BITSET, enabled_compression_algorithms_bitset_); if (maybe_default_compression_level_.is_set) { @@ -366,13 +362,11 @@ void ServerBuilder::InternalAddPluginFactory( ServerBuilder& ServerBuilder::EnableWorkaround(uint32_t id) { switch (id) { case GRPC_WORKAROUND_ID_CRONET_COMPRESSION: - enabled_workarounds_.push_back(GRPC_ARG_WORKAROUND_CRONET_COMPRESSION); - break; + return AddChannelArgument(GRPC_ARG_WORKAROUND_CRONET_COMPRESSION, 1); default: - gpr_log(GPR_ERROR, "Workaround %u is not exist or obsolete.", id); + gpr_log(GPR_ERROR, "Workaround %u does not exist or obsolete.", id); + return *this; } - - return *this; } } // namespace grpc From 0afa9abb790d3f6a966616e0e4a248105d766379 Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Tue, 9 May 2017 19:08:26 -0700 Subject: [PATCH 15/38] Bump to 1.3.2-pre1 --- CMakeLists.txt | 2 +- Makefile | 4 ++-- build.yaml | 2 +- gRPC-Core.podspec | 2 +- gRPC-ProtoRPC.podspec | 2 +- gRPC-RxLibrary.podspec | 2 +- gRPC.podspec | 2 +- package.json | 2 +- package.xml | 4 ++-- src/cpp/common/version_cc.cc | 2 +- src/csharp/Grpc.Core/Version.csproj.include | 2 +- src/csharp/Grpc.Core/VersionInfo.cs | 4 ++-- src/csharp/build_packages_dotnetcli.bat | 2 +- src/csharp/build_packages_dotnetcli.sh | 4 ++-- src/node/health_check/package.json | 4 ++-- src/node/tools/package.json | 2 +- src/objective-c/!ProtoCompiler-gRPCPlugin.podspec | 2 +- src/objective-c/GRPCClient/private/version.h | 2 +- src/php/composer.json | 2 +- src/python/grpcio/grpc_version.py | 2 +- src/python/grpcio_health_checking/grpc_version.py | 2 +- src/python/grpcio_reflection/grpc_version.py | 2 +- src/python/grpcio_tests/grpc_version.py | 2 +- src/ruby/lib/grpc/version.rb | 2 +- src/ruby/tools/version.rb | 2 +- tools/distrib/python/grpcio_tools/grpc_version.py | 2 +- tools/doxygen/Doxyfile.c++ | 2 +- tools/doxygen/Doxyfile.c++.internal | 2 +- 28 files changed, 33 insertions(+), 33 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 51c272998f3..f73da9109eb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -39,7 +39,7 @@ cmake_minimum_required(VERSION 2.8) set(PACKAGE_NAME "grpc") -set(PACKAGE_VERSION "1.3.1") +set(PACKAGE_VERSION "1.3.2-pre1") set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}") set(PACKAGE_TARNAME "${PACKAGE_NAME}-${PACKAGE_VERSION}") set(PACKAGE_BUGREPORT "https://github.com/grpc/grpc/issues/") diff --git a/Makefile b/Makefile index 293a45902df..5ec70e6416c 100644 --- a/Makefile +++ b/Makefile @@ -420,8 +420,8 @@ Q = @ endif CORE_VERSION = 3.0.0 -CPP_VERSION = 1.3.1 -CSHARP_VERSION = 1.3.1 +CPP_VERSION = 1.3.2-pre1 +CSHARP_VERSION = 1.3.2-pre1 CPPFLAGS_NO_ARCH += $(addprefix -I, $(INCLUDES)) $(addprefix -D, $(DEFINES)) CPPFLAGS += $(CPPFLAGS_NO_ARCH) $(ARCH_FLAGS) diff --git a/build.yaml b/build.yaml index 37e17251242..3542f249ca4 100644 --- a/build.yaml +++ b/build.yaml @@ -14,7 +14,7 @@ settings: '#10': See the expand_version.py for all the quirks here core_version: 3.0.0 g_stands_for: gentle - version: 1.3.1 + version: 1.3.2-pre1 filegroups: - name: census public_headers: diff --git a/gRPC-Core.podspec b/gRPC-Core.podspec index 561db476c29..625743d1902 100644 --- a/gRPC-Core.podspec +++ b/gRPC-Core.podspec @@ -37,7 +37,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-Core' - version = '1.3.1' + version = '1.3.2-pre1' s.version = version s.summary = 'Core cross-platform gRPC library, written in C' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-ProtoRPC.podspec b/gRPC-ProtoRPC.podspec index 4a83345237b..d387ec6a38b 100644 --- a/gRPC-ProtoRPC.podspec +++ b/gRPC-ProtoRPC.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-ProtoRPC' - version = '1.3.1' + version = '1.3.2-pre1' s.version = version s.summary = 'RPC library for Protocol Buffers, based on gRPC' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-RxLibrary.podspec b/gRPC-RxLibrary.podspec index 83ecb613e1c..03a04e15e80 100644 --- a/gRPC-RxLibrary.podspec +++ b/gRPC-RxLibrary.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-RxLibrary' - version = '1.3.1' + version = '1.3.2-pre1' s.version = version s.summary = 'Reactive Extensions library for iOS/OSX.' s.homepage = 'http://www.grpc.io' diff --git a/gRPC.podspec b/gRPC.podspec index 29d3cb23b2b..e633f694e8f 100644 --- a/gRPC.podspec +++ b/gRPC.podspec @@ -35,7 +35,7 @@ Pod::Spec.new do |s| s.name = 'gRPC' - version = '1.3.1' + version = '1.3.2-pre1' s.version = version s.summary = 'gRPC client library for iOS/OSX' s.homepage = 'http://www.grpc.io' diff --git a/package.json b/package.json index 51b6863ae34..e7a19347331 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "grpc", - "version": "1.3.1", + "version": "1.3.2-pre1", "author": "Google Inc.", "description": "gRPC Library for Node", "homepage": "http://www.grpc.io/", diff --git a/package.xml b/package.xml index 0a655ccc8af..6886e390fc3 100644 --- a/package.xml +++ b/package.xml @@ -13,8 +13,8 @@ 2017-05-02 - 1.3.1 - 1.3.1 + 1.3.2RC1 + 1.3.2RC1 beta diff --git a/src/cpp/common/version_cc.cc b/src/cpp/common/version_cc.cc index de0bafaff5e..4ff046ab18a 100644 --- a/src/cpp/common/version_cc.cc +++ b/src/cpp/common/version_cc.cc @@ -37,5 +37,5 @@ #include namespace grpc { -grpc::string Version() { return "1.3.1"; } +grpc::string Version() { return "1.3.2-pre1"; } } diff --git a/src/csharp/Grpc.Core/Version.csproj.include b/src/csharp/Grpc.Core/Version.csproj.include index 25d3ca2e3b4..503693bb8a6 100755 --- a/src/csharp/Grpc.Core/Version.csproj.include +++ b/src/csharp/Grpc.Core/Version.csproj.include @@ -1,7 +1,7 @@ - 1.3.1 + 1.3.2-pre1 3.2.0 diff --git a/src/csharp/Grpc.Core/VersionInfo.cs b/src/csharp/Grpc.Core/VersionInfo.cs index 2376485c684..fcac3c7e647 100644 --- a/src/csharp/Grpc.Core/VersionInfo.cs +++ b/src/csharp/Grpc.Core/VersionInfo.cs @@ -48,11 +48,11 @@ namespace Grpc.Core /// /// Current AssemblyFileVersion of gRPC C# assemblies /// - public const string CurrentAssemblyFileVersion = "1.3.1.0"; + public const string CurrentAssemblyFileVersion = "1.3.2.0"; /// /// Current version of gRPC C# /// - public const string CurrentVersion = "1.3.1"; + public const string CurrentVersion = "1.3.2-pre1"; } } diff --git a/src/csharp/build_packages_dotnetcli.bat b/src/csharp/build_packages_dotnetcli.bat index 1ed0ffa87c4..9e837ba1661 100755 --- a/src/csharp/build_packages_dotnetcli.bat +++ b/src/csharp/build_packages_dotnetcli.bat @@ -28,7 +28,7 @@ @rem OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @rem Current package versions -set VERSION=1.3.1 +set VERSION=1.3.2-pre1 @rem Adjust the location of nuget.exe set NUGET=C:\nuget\nuget.exe diff --git a/src/csharp/build_packages_dotnetcli.sh b/src/csharp/build_packages_dotnetcli.sh index 4091ce7f9ad..a87673cb515 100755 --- a/src/csharp/build_packages_dotnetcli.sh +++ b/src/csharp/build_packages_dotnetcli.sh @@ -70,7 +70,7 @@ dotnet pack --configuration Release --include-symbols --include-source Grpc.Auth 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.3.1" -OutputDirectory ../../artifacts -nuget pack Grpc.Tools.nuspec -Version "1.3.1" -OutputDirectory ../../artifacts +nuget pack Grpc.nuspec -Version "1.3.2-pre1" -OutputDirectory ../../artifacts +nuget pack Grpc.Tools.nuspec -Version "1.3.2-pre1" -OutputDirectory ../../artifacts (cd ../../artifacts && zip csharp_nugets_dotnetcli.zip *.nupkg) diff --git a/src/node/health_check/package.json b/src/node/health_check/package.json index b94518260f6..3067f02c6c0 100644 --- a/src/node/health_check/package.json +++ b/src/node/health_check/package.json @@ -1,6 +1,6 @@ { "name": "grpc-health-check", - "version": "1.3.1", + "version": "1.3.2-pre1", "author": "Google Inc.", "description": "Health check service for use with gRPC", "repository": { @@ -15,7 +15,7 @@ } ], "dependencies": { - "grpc": "^1.3.1", + "grpc": "^1.3.2-pre1", "lodash": "^3.9.3", "google-protobuf": "^3.0.0" }, diff --git a/src/node/tools/package.json b/src/node/tools/package.json index 4556c127d99..61efa203528 100644 --- a/src/node/tools/package.json +++ b/src/node/tools/package.json @@ -1,6 +1,6 @@ { "name": "grpc-tools", - "version": "1.3.1", + "version": "1.3.2-pre1", "author": "Google Inc.", "description": "Tools for developing with gRPC on Node.js", "homepage": "http://www.grpc.io/", diff --git a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec index 0312a381dce..0b7b40adeb1 100644 --- a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec +++ b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec @@ -42,7 +42,7 @@ Pod::Spec.new do |s| # exclamation mark ensures that other "regular" pods will be able to find it as it'll be installed # before them. s.name = '!ProtoCompiler-gRPCPlugin' - v = '1.3.1' + v = '1.3.2-pre1' s.version = v s.summary = 'The gRPC ProtoC plugin generates Objective-C files from .proto services.' s.description = <<-DESC diff --git a/src/objective-c/GRPCClient/private/version.h b/src/objective-c/GRPCClient/private/version.h index 7861e0a733e..9cdb7e05189 100644 --- a/src/objective-c/GRPCClient/private/version.h +++ b/src/objective-c/GRPCClient/private/version.h @@ -38,4 +38,4 @@ // `tools/buildgen/generate_projects.sh`. -#define GRPC_OBJC_VERSION_STRING @"1.3.1" +#define GRPC_OBJC_VERSION_STRING @"1.3.2-pre1" diff --git a/src/php/composer.json b/src/php/composer.json index 0084b949502..3b7ba4162cb 100644 --- a/src/php/composer.json +++ b/src/php/composer.json @@ -2,7 +2,7 @@ "name": "grpc/grpc-dev", "description": "gRPC library for PHP - for Developement use only", "license": "BSD-3-Clause", - "version": "1.3.1", + "version": "1.3.2", "require": { "php": ">=5.5.0", "google/protobuf": "^v3.1.0" diff --git a/src/python/grpcio/grpc_version.py b/src/python/grpcio/grpc_version.py index 495af70240f..89dabad8072 100644 --- a/src/python/grpcio/grpc_version.py +++ b/src/python/grpcio/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio/grpc_version.py.template`!!! -VERSION='1.3.1' +VERSION='1.3.2rc1' diff --git a/src/python/grpcio_health_checking/grpc_version.py b/src/python/grpcio_health_checking/grpc_version.py index c0dae962d02..aebb6a9e4f5 100644 --- a/src/python/grpcio_health_checking/grpc_version.py +++ b/src/python/grpcio_health_checking/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_health_checking/grpc_version.py.template`!!! -VERSION='1.3.1' +VERSION='1.3.2rc1' diff --git a/src/python/grpcio_reflection/grpc_version.py b/src/python/grpcio_reflection/grpc_version.py index bc9fb1f4afb..c3a35877716 100644 --- a/src/python/grpcio_reflection/grpc_version.py +++ b/src/python/grpcio_reflection/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_reflection/grpc_version.py.template`!!! -VERSION='1.3.1' +VERSION='1.3.2rc1' diff --git a/src/python/grpcio_tests/grpc_version.py b/src/python/grpcio_tests/grpc_version.py index 1a2281b177f..32dc29b5f74 100644 --- a/src/python/grpcio_tests/grpc_version.py +++ b/src/python/grpcio_tests/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_tests/grpc_version.py.template`!!! -VERSION='1.3.1' +VERSION='1.3.2rc1' diff --git a/src/ruby/lib/grpc/version.rb b/src/ruby/lib/grpc/version.rb index 1e723a935e3..4a9f170f36a 100644 --- a/src/ruby/lib/grpc/version.rb +++ b/src/ruby/lib/grpc/version.rb @@ -29,5 +29,5 @@ # GRPC contains the General RPC module. module GRPC - VERSION = '1.3.1' + VERSION = '1.3.2.pre1' end diff --git a/src/ruby/tools/version.rb b/src/ruby/tools/version.rb index d9109372afa..e7f1525a959 100644 --- a/src/ruby/tools/version.rb +++ b/src/ruby/tools/version.rb @@ -29,6 +29,6 @@ module GRPC module Tools - VERSION = '1.3.1' + VERSION = '1.3.2.pre1' end end diff --git a/tools/distrib/python/grpcio_tools/grpc_version.py b/tools/distrib/python/grpcio_tools/grpc_version.py index 9a12f6b84c3..e833bde0dc5 100644 --- a/tools/distrib/python/grpcio_tools/grpc_version.py +++ b/tools/distrib/python/grpcio_tools/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/tools/distrib/python/grpcio_tools/grpc_version.py.template`!!! -VERSION='1.3.1' +VERSION='1.3.2rc1' diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index 8fa5b3ede59..9dc23e8a041 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.1 +PROJECT_NUMBER = 1.3.2-pre1 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal index d620f99ff1c..f244c8c8742 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.1 +PROJECT_NUMBER = 1.3.2-pre1 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a From 448a11d616b0fc97bba94aba7f15597ce204a401 Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Wed, 10 May 2017 15:23:29 -0700 Subject: [PATCH 16/38] Bump to version 1.3.2 --- CMakeLists.txt | 2 +- Makefile | 4 ++-- build.yaml | 2 +- gRPC-Core.podspec | 2 +- gRPC-ProtoRPC.podspec | 2 +- gRPC-RxLibrary.podspec | 2 +- gRPC.podspec | 2 +- package.json | 2 +- package.xml | 4 ++-- src/cpp/common/version_cc.cc | 2 +- src/csharp/Grpc.Core/Version.csproj.include | 2 +- src/csharp/Grpc.Core/VersionInfo.cs | 2 +- src/csharp/build_packages_dotnetcli.bat | 2 +- src/csharp/build_packages_dotnetcli.sh | 4 ++-- src/node/health_check/package.json | 4 ++-- src/node/tools/package.json | 2 +- src/objective-c/!ProtoCompiler-gRPCPlugin.podspec | 2 +- src/objective-c/GRPCClient/private/version.h | 2 +- src/python/grpcio/grpc_version.py | 2 +- src/python/grpcio_health_checking/grpc_version.py | 2 +- src/python/grpcio_reflection/grpc_version.py | 2 +- src/python/grpcio_tests/grpc_version.py | 2 +- src/ruby/lib/grpc/version.rb | 2 +- src/ruby/tools/version.rb | 2 +- tools/distrib/python/grpcio_tools/grpc_version.py | 2 +- tools/doxygen/Doxyfile.c++ | 2 +- tools/doxygen/Doxyfile.c++.internal | 2 +- 27 files changed, 31 insertions(+), 31 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index f73da9109eb..680ee8b8291 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -39,7 +39,7 @@ cmake_minimum_required(VERSION 2.8) set(PACKAGE_NAME "grpc") -set(PACKAGE_VERSION "1.3.2-pre1") +set(PACKAGE_VERSION "1.3.2") set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}") set(PACKAGE_TARNAME "${PACKAGE_NAME}-${PACKAGE_VERSION}") set(PACKAGE_BUGREPORT "https://github.com/grpc/grpc/issues/") diff --git a/Makefile b/Makefile index 5ec70e6416c..6a8037fca4b 100644 --- a/Makefile +++ b/Makefile @@ -420,8 +420,8 @@ Q = @ endif CORE_VERSION = 3.0.0 -CPP_VERSION = 1.3.2-pre1 -CSHARP_VERSION = 1.3.2-pre1 +CPP_VERSION = 1.3.2 +CSHARP_VERSION = 1.3.2 CPPFLAGS_NO_ARCH += $(addprefix -I, $(INCLUDES)) $(addprefix -D, $(DEFINES)) CPPFLAGS += $(CPPFLAGS_NO_ARCH) $(ARCH_FLAGS) diff --git a/build.yaml b/build.yaml index 3542f249ca4..d18be48d7af 100644 --- a/build.yaml +++ b/build.yaml @@ -14,7 +14,7 @@ settings: '#10': See the expand_version.py for all the quirks here core_version: 3.0.0 g_stands_for: gentle - version: 1.3.2-pre1 + version: 1.3.2 filegroups: - name: census public_headers: diff --git a/gRPC-Core.podspec b/gRPC-Core.podspec index 625743d1902..8f0530ebb3b 100644 --- a/gRPC-Core.podspec +++ b/gRPC-Core.podspec @@ -37,7 +37,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-Core' - version = '1.3.2-pre1' + version = '1.3.2' s.version = version s.summary = 'Core cross-platform gRPC library, written in C' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-ProtoRPC.podspec b/gRPC-ProtoRPC.podspec index d387ec6a38b..9b783b9ce0e 100644 --- a/gRPC-ProtoRPC.podspec +++ b/gRPC-ProtoRPC.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-ProtoRPC' - version = '1.3.2-pre1' + version = '1.3.2' s.version = version s.summary = 'RPC library for Protocol Buffers, based on gRPC' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-RxLibrary.podspec b/gRPC-RxLibrary.podspec index 03a04e15e80..39e053a5212 100644 --- a/gRPC-RxLibrary.podspec +++ b/gRPC-RxLibrary.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-RxLibrary' - version = '1.3.2-pre1' + version = '1.3.2' s.version = version s.summary = 'Reactive Extensions library for iOS/OSX.' s.homepage = 'http://www.grpc.io' diff --git a/gRPC.podspec b/gRPC.podspec index e633f694e8f..8b43a1fe113 100644 --- a/gRPC.podspec +++ b/gRPC.podspec @@ -35,7 +35,7 @@ Pod::Spec.new do |s| s.name = 'gRPC' - version = '1.3.2-pre1' + version = '1.3.2' s.version = version s.summary = 'gRPC client library for iOS/OSX' s.homepage = 'http://www.grpc.io' diff --git a/package.json b/package.json index e7a19347331..a2b4633fc98 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "grpc", - "version": "1.3.2-pre1", + "version": "1.3.2", "author": "Google Inc.", "description": "gRPC Library for Node", "homepage": "http://www.grpc.io/", diff --git a/package.xml b/package.xml index 4d3b939a5b5..f0d277b25ab 100644 --- a/package.xml +++ b/package.xml @@ -13,8 +13,8 @@ 2017-05-05 - 1.3.2RC1 - 1.3.2RC1 + 1.3.2 + 1.3.2 beta diff --git a/src/cpp/common/version_cc.cc b/src/cpp/common/version_cc.cc index 4ff046ab18a..6bcfbba7715 100644 --- a/src/cpp/common/version_cc.cc +++ b/src/cpp/common/version_cc.cc @@ -37,5 +37,5 @@ #include namespace grpc { -grpc::string Version() { return "1.3.2-pre1"; } +grpc::string Version() { return "1.3.2"; } } diff --git a/src/csharp/Grpc.Core/Version.csproj.include b/src/csharp/Grpc.Core/Version.csproj.include index 503693bb8a6..8aaec6e4138 100755 --- a/src/csharp/Grpc.Core/Version.csproj.include +++ b/src/csharp/Grpc.Core/Version.csproj.include @@ -1,7 +1,7 @@ - 1.3.2-pre1 + 1.3.2 3.2.0 diff --git a/src/csharp/Grpc.Core/VersionInfo.cs b/src/csharp/Grpc.Core/VersionInfo.cs index fcac3c7e647..9cb660829d1 100644 --- a/src/csharp/Grpc.Core/VersionInfo.cs +++ b/src/csharp/Grpc.Core/VersionInfo.cs @@ -53,6 +53,6 @@ namespace Grpc.Core /// /// Current version of gRPC C# /// - public const string CurrentVersion = "1.3.2-pre1"; + public const string CurrentVersion = "1.3.2"; } } diff --git a/src/csharp/build_packages_dotnetcli.bat b/src/csharp/build_packages_dotnetcli.bat index 9e837ba1661..8dcf2812132 100755 --- a/src/csharp/build_packages_dotnetcli.bat +++ b/src/csharp/build_packages_dotnetcli.bat @@ -28,7 +28,7 @@ @rem OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @rem Current package versions -set VERSION=1.3.2-pre1 +set VERSION=1.3.2 @rem Adjust the location of nuget.exe set NUGET=C:\nuget\nuget.exe diff --git a/src/csharp/build_packages_dotnetcli.sh b/src/csharp/build_packages_dotnetcli.sh index a87673cb515..9fb9cdd84a2 100755 --- a/src/csharp/build_packages_dotnetcli.sh +++ b/src/csharp/build_packages_dotnetcli.sh @@ -70,7 +70,7 @@ dotnet pack --configuration Release --include-symbols --include-source Grpc.Auth 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.3.2-pre1" -OutputDirectory ../../artifacts -nuget pack Grpc.Tools.nuspec -Version "1.3.2-pre1" -OutputDirectory ../../artifacts +nuget pack Grpc.nuspec -Version "1.3.2" -OutputDirectory ../../artifacts +nuget pack Grpc.Tools.nuspec -Version "1.3.2" -OutputDirectory ../../artifacts (cd ../../artifacts && zip csharp_nugets_dotnetcli.zip *.nupkg) diff --git a/src/node/health_check/package.json b/src/node/health_check/package.json index 3067f02c6c0..da44c1383ce 100644 --- a/src/node/health_check/package.json +++ b/src/node/health_check/package.json @@ -1,6 +1,6 @@ { "name": "grpc-health-check", - "version": "1.3.2-pre1", + "version": "1.3.2", "author": "Google Inc.", "description": "Health check service for use with gRPC", "repository": { @@ -15,7 +15,7 @@ } ], "dependencies": { - "grpc": "^1.3.2-pre1", + "grpc": "^1.3.2", "lodash": "^3.9.3", "google-protobuf": "^3.0.0" }, diff --git a/src/node/tools/package.json b/src/node/tools/package.json index 61efa203528..1e0c9c18dd3 100644 --- a/src/node/tools/package.json +++ b/src/node/tools/package.json @@ -1,6 +1,6 @@ { "name": "grpc-tools", - "version": "1.3.2-pre1", + "version": "1.3.2", "author": "Google Inc.", "description": "Tools for developing with gRPC on Node.js", "homepage": "http://www.grpc.io/", diff --git a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec index 0b7b40adeb1..6bb9e396b7e 100644 --- a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec +++ b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec @@ -42,7 +42,7 @@ Pod::Spec.new do |s| # exclamation mark ensures that other "regular" pods will be able to find it as it'll be installed # before them. s.name = '!ProtoCompiler-gRPCPlugin' - v = '1.3.2-pre1' + v = '1.3.2' s.version = v s.summary = 'The gRPC ProtoC plugin generates Objective-C files from .proto services.' s.description = <<-DESC diff --git a/src/objective-c/GRPCClient/private/version.h b/src/objective-c/GRPCClient/private/version.h index 9cdb7e05189..9851cda0e4d 100644 --- a/src/objective-c/GRPCClient/private/version.h +++ b/src/objective-c/GRPCClient/private/version.h @@ -38,4 +38,4 @@ // `tools/buildgen/generate_projects.sh`. -#define GRPC_OBJC_VERSION_STRING @"1.3.2-pre1" +#define GRPC_OBJC_VERSION_STRING @"1.3.2" diff --git a/src/python/grpcio/grpc_version.py b/src/python/grpcio/grpc_version.py index 89dabad8072..b07ec718918 100644 --- a/src/python/grpcio/grpc_version.py +++ b/src/python/grpcio/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio/grpc_version.py.template`!!! -VERSION='1.3.2rc1' +VERSION='1.3.2' diff --git a/src/python/grpcio_health_checking/grpc_version.py b/src/python/grpcio_health_checking/grpc_version.py index aebb6a9e4f5..1615bd50a49 100644 --- a/src/python/grpcio_health_checking/grpc_version.py +++ b/src/python/grpcio_health_checking/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_health_checking/grpc_version.py.template`!!! -VERSION='1.3.2rc1' +VERSION='1.3.2' diff --git a/src/python/grpcio_reflection/grpc_version.py b/src/python/grpcio_reflection/grpc_version.py index c3a35877716..9fc16a90971 100644 --- a/src/python/grpcio_reflection/grpc_version.py +++ b/src/python/grpcio_reflection/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_reflection/grpc_version.py.template`!!! -VERSION='1.3.2rc1' +VERSION='1.3.2' diff --git a/src/python/grpcio_tests/grpc_version.py b/src/python/grpcio_tests/grpc_version.py index 32dc29b5f74..206315a983b 100644 --- a/src/python/grpcio_tests/grpc_version.py +++ b/src/python/grpcio_tests/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_tests/grpc_version.py.template`!!! -VERSION='1.3.2rc1' +VERSION='1.3.2' diff --git a/src/ruby/lib/grpc/version.rb b/src/ruby/lib/grpc/version.rb index 4a9f170f36a..7cd1f1e67a8 100644 --- a/src/ruby/lib/grpc/version.rb +++ b/src/ruby/lib/grpc/version.rb @@ -29,5 +29,5 @@ # GRPC contains the General RPC module. module GRPC - VERSION = '1.3.2.pre1' + VERSION = '1.3.2' end diff --git a/src/ruby/tools/version.rb b/src/ruby/tools/version.rb index e7f1525a959..ec562bfbe84 100644 --- a/src/ruby/tools/version.rb +++ b/src/ruby/tools/version.rb @@ -29,6 +29,6 @@ module GRPC module Tools - VERSION = '1.3.2.pre1' + VERSION = '1.3.2' end end diff --git a/tools/distrib/python/grpcio_tools/grpc_version.py b/tools/distrib/python/grpcio_tools/grpc_version.py index e833bde0dc5..d232250dec9 100644 --- a/tools/distrib/python/grpcio_tools/grpc_version.py +++ b/tools/distrib/python/grpcio_tools/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/tools/distrib/python/grpcio_tools/grpc_version.py.template`!!! -VERSION='1.3.2rc1' +VERSION='1.3.2' diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index 9dc23e8a041..84850986dc9 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.2-pre1 +PROJECT_NUMBER = 1.3.2 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal index f244c8c8742..9bec618dbd6 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.2-pre1 +PROJECT_NUMBER = 1.3.2 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a From 3b90b7dc0f641aa1ce3baf3dead4620e6855e95a Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Wed, 10 May 2017 15:34:33 -0700 Subject: [PATCH 17/38] Fixed BUILD as well --- BUILD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BUILD b/BUILD index da572181f27..1eb39b6c326 100644 --- a/BUILD +++ b/BUILD @@ -42,7 +42,7 @@ g_stands_for = "gentle" core_version = "3.0.0" -version = "1.3.1" +version = "1.3.2" grpc_cc_library( name = "gpr", From 41ff2e1ee6afc5373a60edc19b5c477e10a429b2 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Wed, 10 May 2017 15:19:01 -0700 Subject: [PATCH 18/38] address comments, format changes --- include/grpc++/generic/generic_stub.h | 6 +- include/grpc++/impl/codegen/async_stream.h | 86 ++++++------------- .../grpc++/impl/codegen/async_unary_call.h | 58 ++++++------- include/grpc++/impl/codegen/client_context.h | 13 ++- include/grpc++/impl/codegen/server_context.h | 8 +- include/grpc++/impl/codegen/service_type.h | 6 ++ include/grpc++/impl/codegen/sync_stream.h | 35 ++++---- include/grpc++/impl/server_builder_plugin.h | 2 +- include/grpc/impl/codegen/gpr_slice.h | 3 +- include/grpc/impl/codegen/grpc_types.h | 19 ++-- include/grpc/slice.h | 3 +- 11 files changed, 99 insertions(+), 140 deletions(-) diff --git a/include/grpc++/generic/generic_stub.h b/include/grpc++/generic/generic_stub.h index fdd23772043..1478846fc84 100644 --- a/include/grpc++/generic/generic_stub.h +++ b/include/grpc++/generic/generic_stub.h @@ -50,11 +50,11 @@ class GenericStub final { explicit GenericStub(std::shared_ptr channel) : channel_(channel) {} - /// Begin a call to a named method \a method usign \a context. - /// A tag \a tag will be deliever to \a cq when the call has been started + /// 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 0). + /// succeeded (i.e. the call won't proceed if the return value is nullptr). std::unique_ptr Call( ClientContext* context, const grpc::string& method, CompletionQueue* cq, void* tag); diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index 5a685cbe554..72fbd9ea796 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -53,7 +53,7 @@ class ClientAsyncStreamingInterface { /// 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; @@ -64,12 +64,14 @@ class ClientAsyncStreamingInterface { /// /// 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 \a - /// WritesDone. - /// * there are no more messages to be received from the server (which can - /// be known implicitly by the calling code, or known explicitly from an - /// earlier call to \a Read that yielded a failed result - /// (e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false'. + /// by calling this method, or explicitly through an earlier call to + /// the WritesDone 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 @@ -97,7 +99,7 @@ class AsyncReaderInterface { /// 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 + /// 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. @@ -119,7 +121,7 @@ class AsyncWriterInterface { /// 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. @@ -132,7 +134,7 @@ class AsyncWriterInterface { /// 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. @@ -205,7 +207,6 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncReaderInterface.Read method for semantics of this method. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -258,13 +259,13 @@ class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface { public: /// Signal the client is done with the writes (half-close the client stream). - /// Thread-safe with respect to \a Read + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; -/// Async API to on the client side for doing client-streaming RPCs, +/// 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 ClientAsyncWriter final : public ClientAsyncWriterInterface { @@ -309,8 +310,6 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncWriterInterface.Write(const W& msg, void* tag) - /// method for semantics of this method. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); // TODO(ctiller): don't assert @@ -318,9 +317,6 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&write_ops_); } - /// See the - /// \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) - /// method for semantics of this method. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -332,8 +328,6 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&write_ops_); } - /// See the \a ClientAsyncWriterInterface.WritesDone method for semantics of - /// this method. void WritesDone(void* tag) override { write_ops_.set_output_tag(tag); write_ops_.ClientSendClose(); @@ -387,14 +381,14 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { /// Async client-side interface for bi-directional streaming, /// where the client-to-server message stream has messages of type \a W, -/// abnd the server-to-client message stream has messages of type \a R. +/// and the server-to-client message stream has messages of type \a R. template class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface, public AsyncReaderInterface { public: /// Signal the client is done with the writes (half-close the client stream). - /// Thread-safe with respect to \a Read + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; @@ -443,8 +437,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&meta_ops_); } - /// See \a AsyncReaderInterface.Read method for semantics - /// of this method. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -454,8 +446,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&read_ops_); } - /// See \a AsyncWriterInterface.Write(const W& msg, void* tag) method for - /// semantics of this method. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); // TODO(ctiller): don't assert @@ -463,8 +453,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) - /// method for semantics of this method. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -476,8 +464,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See \a ClientAsyncReaderWriterInterface.WritesDone method for semantics - /// of this method. void WritesDone(void* tag) override { write_ops_.set_output_tag(tag); write_ops_.ClientSendClose(); @@ -534,12 +520,12 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, /// /// 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 Read operation + /// 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), repsonse message, and status, or if some failure + /// (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. @@ -555,11 +541,10 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, /// 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 Write. + /// \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. + /// (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. @@ -576,16 +561,11 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { explicit ServerAsyncReader(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// 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. + /// 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_); @@ -599,7 +579,6 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncReaderInterface.Read method for semantics. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); read_ops_.RecvMessage(msg); @@ -678,13 +657,13 @@ class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, /// /// 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 Read operation + /// 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), repsonse message, and status, or if some failure + /// (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. @@ -714,10 +693,7 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { explicit ServerAsyncWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// Request notification of the sending the 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. + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. /// /// Implicit input parameter: /// - The initial metadata that will be sent to the client from this op will be @@ -737,7 +713,6 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncWriterInterface.Write(const W &msg, void *tag) method for semantics. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&write_ops_); @@ -746,7 +721,6 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { call_.PerformOps(&write_ops_); } - /// See the \a AsyncWriterInterface.Write(const W &msg, WriteOptions options, void *tag) method for semantics. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -827,13 +801,13 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, /// /// 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 Read operation + /// 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), repsonse message, and status, or if some failure + /// (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. @@ -865,10 +839,7 @@ class ServerAsyncReaderWriter final explicit ServerAsyncReaderWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// Request notification of the sending the 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. + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. /// /// Implicit input parameter: /// - The initial metadata that will be sent to the client from this op will be @@ -888,14 +859,12 @@ class ServerAsyncReaderWriter final call_.PerformOps(&meta_ops_); } - /// See the \a AsyncReaderInterface.Read method for semantics. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); read_ops_.RecvMessage(msg); call_.PerformOps(&read_ops_); } - /// See the \a AsyncWriterInterface.Write(const W& msg, void* tag) method for semantics. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&write_ops_); @@ -904,7 +873,6 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See the \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) method for semantics. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h index 15179e53d6e..6db0a677eaa 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -51,7 +51,29 @@ template 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; }; @@ -83,16 +105,9 @@ class ClientAsyncResponseReader final assert(size == sizeof(ClientAsyncResponseReader)); } - /// 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. + /// See \a ClientAsyncResponseReaderInterface::ReadInitialMetadata for + /// semantics. /// - /// Once a completion has been notified, the initial metadata read from - /// the server will be accessable through the \a ClientContext used to - /// construct this object. - /// - /// \param[in] tag Tag identifying this request. /// Side effect: /// - the \a ClientContext associated with this call is updated with /// possible initial and trailing metadata sent from the serve. @@ -104,20 +119,7 @@ class ClientAsyncResponseReader final call_.PerformOps(&meta_buf_); } - /// 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. + /// See \a ClientAysncResponseReaderInterface::Finish for semantics. /// /// Side effect: /// - the \a ClientContext associated with this call is updated with @@ -169,13 +171,11 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { explicit ServerAsyncResponseWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// Request notification of the sending the 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. + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. /// - /// The initial metadata that will be sent to the client from this op will be - /// taken from the \a ServerContext associated with the call. + /// 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 { diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h index 31bd0d258a6..1653887289f 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -154,7 +154,7 @@ class InteropClientContextInspector; /// A ClientContext allows the person implementing a service client to: /// /// - Add custom metadata key-value pairs that will propagated to the server -/// side. +/// side. /// - Control call settings such as compression and authentication. /// - Initial and trailing metadata coming from the server. /// - Get performance metrics (ie, census). @@ -193,8 +193,7 @@ class ClientContext { /// \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". + /// end in "-bin". void AddMetadata(const grpc::string& meta_key, const grpc::string& meta_value); @@ -243,13 +242,13 @@ class ClientContext { /// this RPC multiple times. void set_idempotent(bool idempotent) { idempotent_ = idempotent; } - /// EXPERIMENTAL: Set this request to be cacheable - /// If set, grpc is free the GET verb for sending the request, + /// 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 - /// See grpc/doc/wait-for-ready.md. + /// 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 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 diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index beaad1c6fa1..1bf9d102a2b 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -96,7 +96,7 @@ class ServerContextTestSpouse; /// - 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 Initial metadata coming from the client. +/// - 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 @@ -130,8 +130,7 @@ class ServerContext { /// \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". + /// 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 @@ -145,8 +144,7 @@ class ServerContext { /// \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". + /// end in "-bin". void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); /// IsCancelled is always safe to call when using sync API. diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index 0df90678b18..9439bd324ef 100644 --- a/include/grpc++/impl/codegen/service_type.h +++ b/include/grpc++/impl/codegen/service_type.h @@ -54,6 +54,12 @@ class ServerAsyncStreamingInterface { 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: diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index ecde15fac9f..82870817bb2 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -54,12 +54,14 @@ class ClientStreamingInterface { /// 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 \a - /// WritesDone. + /// * 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 WritesDone 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 Read that - /// returned "false" + /// 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 @@ -118,7 +120,7 @@ class WriterInterface { virtual ~WriterInterface() {} /// Block to write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// 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. @@ -127,7 +129,7 @@ class WriterInterface { virtual bool Write(const W& msg, WriteOptions options) = 0; /// Block to write \a msg to the stream with default write options. - /// This is thread-safe with respect to \a Read + /// This is thread-safe with respect to \a ReaderInterface::Read /// /// \param msg The message to be written to the stream. /// @@ -209,7 +211,6 @@ class ClientReader final : public ClientReaderInterface { cq_.Pluck(&ops); /// status ignored } - /// See the \a ReaderInterface.NextMessageSize for semantics. bool NextMessageSize(uint32_t* sz) override { *sz = call_.max_receive_message_size(); return true; @@ -258,7 +259,7 @@ class ClientWriterInterface : public ClientStreamingInterface, /// 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 Read operations only + /// Thread safe with respect to \a ReaderInterface::Read operations only /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; @@ -339,7 +340,6 @@ class ClientWriter : public ClientWriterInterface { return cq_.Pluck(&ops); } - /// See the \a ClientWriterInterface.WritesDone method for semantics. bool WritesDone() override { CallOpSet ops; ops.ClientSendClose(); @@ -389,7 +389,7 @@ class ClientReaderWriterInterface : public ClientStreamingInterface, /// 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 Read + /// Thread-safe with respect to \a ReaderInterface::Read /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; @@ -484,7 +484,6 @@ class ClientReaderWriter final : public ClientReaderWriterInterface { return cq_.Pluck(&ops); } - /// See the ClientWriterInterface.WritesDone method for semantics. bool WritesDone() override { CallOpSet ops; ops.ClientSendClose(); @@ -546,13 +545,11 @@ class ServerReader final : public ServerReaderInterface { call_->cq()->Pluck(&ops); } - /// See the \a ReaderInterface.NextMessageSize method. bool NextMessageSize(uint32_t* sz) override { *sz = call_->max_receive_message_size(); return true; } - /// See the \a ReaderInterface.Read method for semantics. bool Read(R* msg) override { CallOpSet> ops; ops.RecvMessage(msg); @@ -707,12 +704,10 @@ class ServerReaderWriter final : public ServerReaderWriterInterface { /// \a ServerContext associated with this call. void SendInitialMetadata() override { body_.SendInitialMetadata(); } - /// See the \a ReaderInterface.NextMessageSize method for semantics bool NextMessageSize(uint32_t* sz) override { return body_.NextMessageSize(sz); } - /// See the \a ReaderInterface.Read method for semantics bool Read(R* msg) override { return body_.Read(msg); } /// See the \a WriterInterface.Write(const W& msg, WriteOptions options) method for semantics. @@ -760,7 +755,7 @@ class ServerUnaryStreamer final /// 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 + /// 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. @@ -774,7 +769,7 @@ class ServerUnaryStreamer final } /// Block to write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// 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. @@ -823,7 +818,7 @@ class ServerSplitStreamer final /// 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 + /// 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. @@ -837,7 +832,7 @@ class ServerSplitStreamer final } /// Block to write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// 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. diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h index 8ce16d66780..d7ea6729071 100644 --- a/include/grpc++/impl/server_builder_plugin.h +++ b/include/grpc++/impl/server_builder_plugin.h @@ -44,7 +44,7 @@ class ServerInitializer; class ChannelArguments; /// A builder class for the creation and startup of \a grpc::Server instances. -/// This is interface is meant for internal usage only. Implementations of this +/// 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 { diff --git a/include/grpc/impl/codegen/gpr_slice.h b/include/grpc/impl/codegen/gpr_slice.h index 3797645442e..f2becd44f85 100644 --- a/include/grpc/impl/codegen/gpr_slice.h +++ b/include/grpc/impl/codegen/gpr_slice.h @@ -33,8 +33,7 @@ #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 +/** 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 diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index dccbd6dbd69..c9af38e5300 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -162,8 +162,7 @@ typedef struct { /** 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. Use - GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH +/** \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. @@ -272,10 +271,8 @@ typedef struct { #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 (a pointer of type - grpc_resource_quota*). - (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" @@ -288,12 +285,11 @@ typedef struct { /** 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. */ + 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 @@ -383,8 +379,7 @@ typedef enum grpc_call_error { /** A single metadata element */ typedef struct grpc_metadata { - /** the key, value values are expected to line up with grpc_mdelem: if - changing + /** 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; diff --git a/include/grpc/slice.h b/include/grpc/slice.h index bd54bc81501..19f546afb6e 100644 --- a/include/grpc/slice.h +++ b/include/grpc/slice.h @@ -166,8 +166,7 @@ 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 */ + 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); From d6ba5ecc343479f8a0508f3ea322fafe162d0290 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Wed, 10 May 2017 16:19:47 -0700 Subject: [PATCH 19/38] fix bad line breaks and lengths --- include/grpc++/impl/codegen/async_stream.h | 143 ++++++++++-------- .../grpc++/impl/codegen/async_unary_call.h | 9 +- include/grpc++/impl/codegen/server_context.h | 67 ++++---- include/grpc++/impl/codegen/service_type.h | 10 +- include/grpc++/impl/codegen/sync_stream.h | 120 +++++++-------- include/grpc/impl/codegen/gpr_slice.h | 10 +- include/grpc/impl/codegen/grpc_types.h | 61 ++++---- 7 files changed, 217 insertions(+), 203 deletions(-) diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index 72fbd9ea796..3402fff38b1 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -63,14 +63,15 @@ class ClientAsyncStreamingInterface { /// Should not be used concurrently with other operations. /// /// 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 WritesDone method of the class in use, e.g. - /// \a ClientAsyncWriterInterface::WritesDone or + /// * 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 WritesDone 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 + /// 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: @@ -80,8 +81,8 @@ class ClientAsyncStreamingInterface { /// - 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. + /// 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. @@ -99,14 +100,14 @@ class AsyncReaderInterface { /// 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 AsyncReaderInterface::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. + /// 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; }; @@ -142,11 +143,11 @@ class AsyncWriterInterface { 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 @@ -166,7 +167,8 @@ class ClientAsyncReaderInterface : public ClientAsyncStreamingInterface, public AsyncReaderInterface {}; /// Async client-side API for doing server-streaming RPCs, -/// where the incoming message stream coming from the server has messages of type \a R. +/// where the incoming message stream coming from the server has +/// messages of type \a R. template class ClientAsyncReader final : public ClientAsyncReaderInterface { public: @@ -191,8 +193,8 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface { assert(size == sizeof(ClientAsyncReader)); } - /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method for - /// semantics. + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata + /// method for semantics. /// /// Side effect: /// - upon receiving initial metadata from the server, @@ -266,7 +268,8 @@ class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, }; /// 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. +/// where the outgoing message stream going to the server contains +/// messages of type \a W. template class ClientAsyncWriter final : public ClientAsyncWriterInterface { public: @@ -298,10 +301,9 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { /// 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. + /// - 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_); @@ -395,8 +397,9 @@ class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, }; /// 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. +/// 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 ClientAsyncReaderWriter final : public ClientAsyncReaderWriterInterface { @@ -428,7 +431,7 @@ class ClientAsyncReaderWriter final /// 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 + /// be accessed through this \a ClientContext. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -514,26 +517,27 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, 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. + /// 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'. + /// 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. + /// 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. + /// 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. @@ -543,8 +547,9 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, /// 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. + /// 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. @@ -564,8 +569,8 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { /// 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. + /// - 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_); @@ -657,25 +662,25 @@ class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, /// /// 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'. + /// 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. + /// 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. @@ -696,8 +701,8 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { /// 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. + /// - 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 { @@ -753,10 +758,11 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { /// 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. + /// - 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 + /// 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_); @@ -801,12 +807,14 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, /// /// 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 + /// 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 + /// 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. /// @@ -815,8 +823,8 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, 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. @@ -830,8 +838,9 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, }; /// 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. +/// 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 ServerAsyncReaderWriter final : public ServerAsyncReaderWriterInterface { @@ -842,8 +851,8 @@ class ServerAsyncReaderWriter final /// 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. + /// - 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 { @@ -883,7 +892,8 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish method for semantics. + /// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish + /// method for semantics. /// /// Implicit input parameter: /// - the \a ServerContext associated with this call is used @@ -903,10 +913,11 @@ class ServerAsyncReaderWriter final /// 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. + /// - 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 + /// 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 6db0a677eaa..0f2f466bfcd 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -174,8 +174,8 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { /// 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. + /// 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 { @@ -193,12 +193,12 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { /// 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. + /// 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). @@ -234,6 +234,7 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { /// \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). diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index 1bf9d102a2b..42575176d77 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -93,17 +93,17 @@ class ServerContextTestSpouse; /// 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. +/// - 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 parameter to the see \a grpc::Server -/// constructor. +/// 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 parameter +/// to the see \a grpc::Server constructor. /// /// \warning ServerContext instances should \em not be reused across rpcs. class ServerContext { @@ -119,32 +119,32 @@ class ServerContext { /// 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. + /// 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, it must be - /// must end in "-bin". + /// \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 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. + /// 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). + /// \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, it must be - /// end in "-bin". + /// \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 end in "-bin". void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); /// IsCancelled is always safe to call when using sync API. @@ -152,22 +152,23 @@ class ServerContext { /// 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. + /// 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. + /// 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). + /// 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 @@ -194,7 +195,7 @@ class ServerContext { /// 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 + /// \a set_compression_level. bool compression_level_set() const { return compression_level_set_; } /// Return the compression algorithm to be used by the server call. diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index 9439bd324ef..b88019164d7 100644 --- a/include/grpc++/impl/codegen/service_type.h +++ b/include/grpc++/impl/codegen/service_type.h @@ -54,10 +54,10 @@ class ServerAsyncStreamingInterface { 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. + /// 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; @@ -162,7 +162,7 @@ class Service { // 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/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index 82870817bb2..e7d9b07c194 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -54,18 +54,18 @@ class ClientStreamingInterface { /// 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 WritesDone method of the class in use, e.g. - /// \a ClientWriterInterface::WritesDone or + /// * 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 WritesDone 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"). + /// 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 - /// status. + /// - 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. @@ -97,7 +97,8 @@ class ReaderInterface { public: virtual ~ReaderInterface() {} - /// Get an 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; /// Block to read a message and parse to \a msg. Returns \a true on success. @@ -141,12 +142,12 @@ class WriterInterface { /// /// 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. @@ -167,14 +168,15 @@ class ClientReaderInterface : public ClientStreamingInterface, 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. +/// 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 ClientReader final : public ClientReaderInterface { public: - /// 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. + /// 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 ClientReader(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, const W& request) @@ -218,8 +220,9 @@ class ClientReader final : public ClientReaderInterface { /// 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 + /// 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> ops; @@ -234,8 +237,8 @@ class ClientReader final : public ClientReaderInterface { /// 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. + /// The \a ClientContext associated with this call is updated with + /// possible metadata received from the server. Status Finish() override { CallOpSet ops; Status status; @@ -266,15 +269,16 @@ class ClientWriterInterface : public ClientStreamingInterface, }; /// 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. +/// where the outgoing message stream coming from the client has messages of +/// type \a W. template class ClientWriter : public ClientWriterInterface { public: - /// 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. + /// 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 ClientWriter(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, R* response) @@ -299,9 +303,8 @@ class ClientWriter : public ClientWriterInterface { /// semantics. /// // Side effect: - /// Once complete, the initial metadata read from - /// the server will be accessable through the \a ClientContext used to - /// construct this object. + /// 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_); @@ -315,8 +318,8 @@ class ClientWriter : public ClientWriterInterface { /// for semantics. /// /// Side effect: - /// Also sends initial metadata if not already sent (using the \a ClientContext - /// associated with this call). + /// Also sends initial metadata if not already sent (using the + /// \a ClientContext associated with this call). using WriterInterface::Write; bool Write(const W& msg, WriteOptions options) override { CallOpSet { /// 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. + /// - 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_) { @@ -395,15 +399,15 @@ class ClientReaderWriterInterface : public ClientStreamingInterface, 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. +/// 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 ClientReaderWriter final : public ClientReaderWriterInterface { public: - /// 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 + /// 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) @@ -425,9 +429,8 @@ class ClientReaderWriter final : public ClientReaderWriterInterface { /// 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. + /// 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_); @@ -528,8 +531,7 @@ class ServerReader final : public ServerReaderInterface { 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 + /// 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_); @@ -691,16 +693,16 @@ class ServerReaderWriterBody final { } // namespace internal /// 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. +/// 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 ServerReaderWriter final : public ServerReaderWriterInterface { 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 + /// for semantics. Note that initial metadata will be affected by the /// \a ServerContext associated with this call. void SendInitialMetadata() override { body_.SendInitialMetadata(); } @@ -710,7 +712,8 @@ class ServerReaderWriter final : public ServerReaderWriterInterface { bool Read(R* msg) override { return body_.Read(msg); } - /// See the \a WriterInterface.Write(const W& msg, WriteOptions options) method for semantics. + /// 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). @@ -728,8 +731,7 @@ class ServerReaderWriter final : public ServerReaderWriterInterface { /// 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 @@ -755,8 +757,8 @@ class ServerUnaryStreamer final /// 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. + /// 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. @@ -818,8 +820,8 @@ class ServerSplitStreamer final /// 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. + /// 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. diff --git a/include/grpc/impl/codegen/gpr_slice.h b/include/grpc/impl/codegen/gpr_slice.h index f2becd44f85..ead0b7db958 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/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index c9af38e5300..99b0e43b3c5 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -67,8 +67,8 @@ typedef struct grpc_byte_buffer { } 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 @@ typedef struct { 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,8 +162,8 @@ typedef struct { /** 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. Use GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH - instead. */ +/** \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. */ @@ -171,8 +171,8 @@ typedef struct { /** 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. */ @@ -271,8 +271,10 @@ typedef struct { #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 (a pointer of type grpc_resource_quota*). - (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" @@ -284,12 +286,12 @@ typedef struct { #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 @@ -331,8 +333,8 @@ typedef enum grpc_call_error { 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, @@ -379,8 +381,8 @@ typedef enum grpc_call_error { /** 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 +449,13 @@ typedef enum { 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 +473,10 @@ typedef enum { 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; @@ -537,8 +537,7 @@ typedef struct grpc_op { 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; From bb2c338924c128fb84f224d2531f4c24fa7da241 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Thu, 11 May 2017 14:23:53 -0700 Subject: [PATCH 20/38] format changes, address comments --- include/grpc++/impl/codegen/async_stream.h | 10 +++--- .../grpc++/impl/codegen/async_unary_call.h | 2 ++ include/grpc++/impl/codegen/client_context.h | 6 ++-- include/grpc++/impl/codegen/server_context.h | 14 ++++----- .../grpc++/impl/codegen/status_code_enum.h | 2 +- include/grpc++/impl/codegen/sync_stream.h | 3 +- include/grpc/impl/codegen/grpc_types.h | 31 ++++++++----------- 7 files changed, 31 insertions(+), 37 deletions(-) diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index 3402fff38b1..04fc5241cb1 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -70,9 +70,8 @@ class ClientAsyncStreamingInterface { /// \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'). + /// 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 @@ -814,9 +813,8 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, /// * 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. + /// 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. diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h index 0f2f466bfcd..aadf77d8a82 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -47,6 +47,8 @@ namespace grpc { 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 ClientAsyncResponseReaderInterface { public: diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h index 1653887289f..b1b9be0fe28 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -192,8 +192,8 @@ class ClientContext { /// /// \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 - /// 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); @@ -249,7 +249,7 @@ class ClientContext { /// 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 made when a channel's connectivity state is + /// 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. diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index 42575176d77..bd52434c543 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -127,10 +127,10 @@ class ServerContext { /// 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, - /// it must be must end in "-bin". + /// \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 @@ -143,8 +143,8 @@ class ServerContext { /// /// \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 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. @@ -153,7 +153,7 @@ class ServerContext { 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 + /// 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 diff --git a/include/grpc++/impl/codegen/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h index a60cdef60e8..c3d27fa3b00 100644 --- a/include/grpc++/impl/codegen/status_code_enum.h +++ b/include/grpc++/impl/codegen/status_code_enum.h @@ -136,7 +136,7 @@ enum StatusCode { /// 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 + /// \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. diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index e7d9b07c194..db9048d7e5f 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -222,8 +222,7 @@ class ClientReader final : public ClientReaderInterface { /// 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). + /// accessed through the \a ClientContext associated with this call). bool Read(R* msg) override { CallOpSet> ops; if (!context_->initial_metadata_received_) { diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index 99b0e43b3c5..394a7413087 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -198,9 +198,8 @@ typedef struct { #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" @@ -210,15 +209,13 @@ typedef struct { /** 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 */ @@ -260,21 +257,19 @@ typedef struct { /** 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. */ + 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. 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 - * (a pointer of type grpc_resource_quota*). - (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" From c8a6822b0e0afa53b2ec4c92610f7175e4be5127 Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Fri, 12 May 2017 12:21:16 -0700 Subject: [PATCH 21/38] Revert "Add cpp test" This reverts commit e22bd48cd93cf4c0b777e124631f14bb21073c6c. --- test/cpp/server/server_builder_test.cc | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/test/cpp/server/server_builder_test.cc b/test/cpp/server/server_builder_test.cc index 68b2f656bca..1d9eda17b40 100644 --- a/test/cpp/server/server_builder_test.cc +++ b/test/cpp/server/server_builder_test.cc @@ -40,8 +40,6 @@ #include "src/proto/grpc/testing/echo.grpc.pb.h" #include "test/core/util/port.h" -#include - namespace grpc { namespace { @@ -89,15 +87,6 @@ TEST(ServerBuilderTest, CreateServerRepeatedPortWithDisallowedReusePort) { nullptr); } -TEST(ServerBuilderTest, CreateServerOnePortWithCronetCompressionWorkaround) { - ServerBuilder() - .RegisterService(&g_service) - .AddListeningPort(g_port, InsecureServerCredentials()) - .EnableWorkaround(GRPC_WORKAROUND_ID_CRONET_COMPRESSION) - .BuildAndStart() - ->Shutdown(); -} - } // namespace } // namespace grpc From 16153d11f89ee7403cb1ded92f5ee0d2328309e6 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Mon, 15 May 2017 09:46:33 -0700 Subject: [PATCH 22/38] address comments, description changes --- include/grpc++/impl/codegen/server_context.h | 4 ++-- include/grpc++/impl/server_builder_plugin.h | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index bd52434c543..48967c2e683 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -102,8 +102,8 @@ class ServerContextTestSpouse; /// 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 parameter -/// to the see \a grpc::Server constructor. +/// 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 { diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h index d7ea6729071..8f2bce54d7e 100644 --- a/include/grpc++/impl/server_builder_plugin.h +++ b/include/grpc++/impl/server_builder_plugin.h @@ -43,7 +43,6 @@ namespace grpc { class ServerInitializer; class ChannelArguments; -/// A builder class for the creation and startup of \a grpc::Server instances. /// 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. From 7ff21a67193e9c21f021b539ae90d2c75820a37d Mon Sep 17 00:00:00 2001 From: Ken Payson Date: Wed, 10 May 2017 12:24:13 -0700 Subject: [PATCH 23/38] Add Raspberry Pi Python binaries --- .../grpc_artifact_linux_armv6/Dockerfile | 39 +++++++++++++++++++ .../grpc_artifact_linux_armv7/Dockerfile | 39 +++++++++++++++++++ tools/run_tests/artifacts/artifact_targets.py | 29 +++++++++++++- .../dockerize/build_and_run_docker.sh | 3 +- 4 files changed, 107 insertions(+), 3 deletions(-) create mode 100644 tools/dockerfile/grpc_artifact_linux_armv6/Dockerfile create mode 100644 tools/dockerfile/grpc_artifact_linux_armv7/Dockerfile diff --git a/tools/dockerfile/grpc_artifact_linux_armv6/Dockerfile b/tools/dockerfile/grpc_artifact_linux_armv6/Dockerfile new file mode 100644 index 00000000000..b085dd00dbf --- /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 00000000000..d7759a6c503 --- /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/run_tests/artifacts/artifact_targets.py b/tools/run_tests/artifacts/artifact_targets.py index 04702baccae..d64c4846817 100644 --- a/tools/run_tests/artifacts/artifact_targets.py +++ b/tools/run_tests/artifacts/artifact_targets.py @@ -41,7 +41,7 @@ import python_utils.jobset as jobset 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 @@ -55,6 +55,8 @@ def create_docker_jobspec(name, dockerfile_dir, shell_command, environ={}, 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, @@ -102,7 +104,22 @@ class PythonArtifact: 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 @@ -332,6 +349,14 @@ def targets(): 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 8c25c861c1a..6189e9a5c02 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 @@ docker run \ -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" != "" ] From 16f76d209203110ee0fbfef8f667d7f0cc76ef86 Mon Sep 17 00:00:00 2001 From: Ken Payson Date: Tue, 16 May 2017 08:54:22 -0700 Subject: [PATCH 24/38] Bump to version 1.3.3 --- BUILD | 2 +- CMakeLists.txt | 2 +- Makefile | 4 ++-- build.yaml | 2 +- gRPC-Core.podspec | 2 +- gRPC-ProtoRPC.podspec | 2 +- gRPC-RxLibrary.podspec | 2 +- gRPC.podspec | 2 +- package.json | 2 +- package.xml | 4 ++-- src/cpp/common/version_cc.cc | 2 +- src/csharp/Grpc.Core/Version.csproj.include | 2 +- src/csharp/Grpc.Core/VersionInfo.cs | 4 ++-- src/csharp/build_packages_dotnetcli.bat | 2 +- src/csharp/build_packages_dotnetcli.sh | 4 ++-- src/node/health_check/package.json | 4 ++-- src/node/tools/package.json | 2 +- src/objective-c/!ProtoCompiler-gRPCPlugin.podspec | 2 +- src/objective-c/GRPCClient/private/version.h | 2 +- src/php/composer.json | 2 +- src/python/grpcio/grpc_version.py | 2 +- src/python/grpcio_health_checking/grpc_version.py | 2 +- src/python/grpcio_reflection/grpc_version.py | 2 +- src/python/grpcio_tests/grpc_version.py | 2 +- src/ruby/lib/grpc/version.rb | 2 +- src/ruby/tools/version.rb | 2 +- tools/distrib/python/grpcio_tools/grpc_version.py | 2 +- tools/doxygen/Doxyfile.c++ | 2 +- tools/doxygen/Doxyfile.c++.internal | 2 +- 29 files changed, 34 insertions(+), 34 deletions(-) diff --git a/BUILD b/BUILD index 1eb39b6c326..a0d80cd5735 100644 --- a/BUILD +++ b/BUILD @@ -42,7 +42,7 @@ g_stands_for = "gentle" core_version = "3.0.0" -version = "1.3.2" +version = "1.3.3" grpc_cc_library( name = "gpr", diff --git a/CMakeLists.txt b/CMakeLists.txt index 680ee8b8291..279e12bbd0b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -39,7 +39,7 @@ cmake_minimum_required(VERSION 2.8) set(PACKAGE_NAME "grpc") -set(PACKAGE_VERSION "1.3.2") +set(PACKAGE_VERSION "1.3.3") set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}") set(PACKAGE_TARNAME "${PACKAGE_NAME}-${PACKAGE_VERSION}") set(PACKAGE_BUGREPORT "https://github.com/grpc/grpc/issues/") diff --git a/Makefile b/Makefile index 6a8037fca4b..e5f23e75ad6 100644 --- a/Makefile +++ b/Makefile @@ -420,8 +420,8 @@ Q = @ endif CORE_VERSION = 3.0.0 -CPP_VERSION = 1.3.2 -CSHARP_VERSION = 1.3.2 +CPP_VERSION = 1.3.3 +CSHARP_VERSION = 1.3.3 CPPFLAGS_NO_ARCH += $(addprefix -I, $(INCLUDES)) $(addprefix -D, $(DEFINES)) CPPFLAGS += $(CPPFLAGS_NO_ARCH) $(ARCH_FLAGS) diff --git a/build.yaml b/build.yaml index d18be48d7af..5d1e74b93a8 100644 --- a/build.yaml +++ b/build.yaml @@ -14,7 +14,7 @@ settings: '#10': See the expand_version.py for all the quirks here core_version: 3.0.0 g_stands_for: gentle - version: 1.3.2 + version: 1.3.3 filegroups: - name: census public_headers: diff --git a/gRPC-Core.podspec b/gRPC-Core.podspec index 8f0530ebb3b..a2237ac0855 100644 --- a/gRPC-Core.podspec +++ b/gRPC-Core.podspec @@ -37,7 +37,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-Core' - version = '1.3.2' + version = '1.3.3' s.version = version s.summary = 'Core cross-platform gRPC library, written in C' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-ProtoRPC.podspec b/gRPC-ProtoRPC.podspec index 9b783b9ce0e..1af811aa558 100644 --- a/gRPC-ProtoRPC.podspec +++ b/gRPC-ProtoRPC.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-ProtoRPC' - version = '1.3.2' + version = '1.3.3' s.version = version s.summary = 'RPC library for Protocol Buffers, based on gRPC' s.homepage = 'http://www.grpc.io' diff --git a/gRPC-RxLibrary.podspec b/gRPC-RxLibrary.podspec index 39e053a5212..3f720f2393f 100644 --- a/gRPC-RxLibrary.podspec +++ b/gRPC-RxLibrary.podspec @@ -36,7 +36,7 @@ Pod::Spec.new do |s| s.name = 'gRPC-RxLibrary' - version = '1.3.2' + version = '1.3.3' s.version = version s.summary = 'Reactive Extensions library for iOS/OSX.' s.homepage = 'http://www.grpc.io' diff --git a/gRPC.podspec b/gRPC.podspec index 8b43a1fe113..b064c50ccfd 100644 --- a/gRPC.podspec +++ b/gRPC.podspec @@ -35,7 +35,7 @@ Pod::Spec.new do |s| s.name = 'gRPC' - version = '1.3.2' + version = '1.3.3' s.version = version s.summary = 'gRPC client library for iOS/OSX' s.homepage = 'http://www.grpc.io' diff --git a/package.json b/package.json index a2b4633fc98..2cb86a65a30 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "grpc", - "version": "1.3.2", + "version": "1.3.3", "author": "Google Inc.", "description": "gRPC Library for Node", "homepage": "http://www.grpc.io/", diff --git a/package.xml b/package.xml index f0d277b25ab..faf36657577 100644 --- a/package.xml +++ b/package.xml @@ -13,8 +13,8 @@ 2017-05-05 - 1.3.2 - 1.3.2 + 1.3.3 + 1.3.3 beta diff --git a/src/cpp/common/version_cc.cc b/src/cpp/common/version_cc.cc index 6bcfbba7715..2d44fb9d084 100644 --- a/src/cpp/common/version_cc.cc +++ b/src/cpp/common/version_cc.cc @@ -37,5 +37,5 @@ #include namespace grpc { -grpc::string Version() { return "1.3.2"; } +grpc::string Version() { return "1.3.3"; } } diff --git a/src/csharp/Grpc.Core/Version.csproj.include b/src/csharp/Grpc.Core/Version.csproj.include index 8aaec6e4138..9ececc9b95a 100755 --- a/src/csharp/Grpc.Core/Version.csproj.include +++ b/src/csharp/Grpc.Core/Version.csproj.include @@ -1,7 +1,7 @@ - 1.3.2 + 1.3.3 3.2.0 diff --git a/src/csharp/Grpc.Core/VersionInfo.cs b/src/csharp/Grpc.Core/VersionInfo.cs index 9cb660829d1..12cbc6f0491 100644 --- a/src/csharp/Grpc.Core/VersionInfo.cs +++ b/src/csharp/Grpc.Core/VersionInfo.cs @@ -48,11 +48,11 @@ namespace Grpc.Core /// /// Current AssemblyFileVersion of gRPC C# assemblies /// - public const string CurrentAssemblyFileVersion = "1.3.2.0"; + public const string CurrentAssemblyFileVersion = "1.3.3.0"; /// /// Current version of gRPC C# /// - public const string CurrentVersion = "1.3.2"; + public const string CurrentVersion = "1.3.3"; } } diff --git a/src/csharp/build_packages_dotnetcli.bat b/src/csharp/build_packages_dotnetcli.bat index 8dcf2812132..6806bbd2ae5 100755 --- a/src/csharp/build_packages_dotnetcli.bat +++ b/src/csharp/build_packages_dotnetcli.bat @@ -28,7 +28,7 @@ @rem OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @rem Current package versions -set VERSION=1.3.2 +set VERSION=1.3.3 @rem Adjust the location of nuget.exe set NUGET=C:\nuget\nuget.exe diff --git a/src/csharp/build_packages_dotnetcli.sh b/src/csharp/build_packages_dotnetcli.sh index 9fb9cdd84a2..fc9fd50f596 100755 --- a/src/csharp/build_packages_dotnetcli.sh +++ b/src/csharp/build_packages_dotnetcli.sh @@ -70,7 +70,7 @@ dotnet pack --configuration Release --include-symbols --include-source Grpc.Auth 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.3.2" -OutputDirectory ../../artifacts -nuget pack Grpc.Tools.nuspec -Version "1.3.2" -OutputDirectory ../../artifacts +nuget pack Grpc.nuspec -Version "1.3.3" -OutputDirectory ../../artifacts +nuget pack Grpc.Tools.nuspec -Version "1.3.3" -OutputDirectory ../../artifacts (cd ../../artifacts && zip csharp_nugets_dotnetcli.zip *.nupkg) diff --git a/src/node/health_check/package.json b/src/node/health_check/package.json index da44c1383ce..fe36fb2693d 100644 --- a/src/node/health_check/package.json +++ b/src/node/health_check/package.json @@ -1,6 +1,6 @@ { "name": "grpc-health-check", - "version": "1.3.2", + "version": "1.3.3", "author": "Google Inc.", "description": "Health check service for use with gRPC", "repository": { @@ -15,7 +15,7 @@ } ], "dependencies": { - "grpc": "^1.3.2", + "grpc": "^1.3.3", "lodash": "^3.9.3", "google-protobuf": "^3.0.0" }, diff --git a/src/node/tools/package.json b/src/node/tools/package.json index 1e0c9c18dd3..caf2b5a5cb9 100644 --- a/src/node/tools/package.json +++ b/src/node/tools/package.json @@ -1,6 +1,6 @@ { "name": "grpc-tools", - "version": "1.3.2", + "version": "1.3.3", "author": "Google Inc.", "description": "Tools for developing with gRPC on Node.js", "homepage": "http://www.grpc.io/", diff --git a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec index 6bb9e396b7e..4e93c0f1b53 100644 --- a/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec +++ b/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec @@ -42,7 +42,7 @@ Pod::Spec.new do |s| # exclamation mark ensures that other "regular" pods will be able to find it as it'll be installed # before them. s.name = '!ProtoCompiler-gRPCPlugin' - v = '1.3.2' + v = '1.3.3' s.version = v s.summary = 'The gRPC ProtoC plugin generates Objective-C files from .proto services.' s.description = <<-DESC diff --git a/src/objective-c/GRPCClient/private/version.h b/src/objective-c/GRPCClient/private/version.h index 9851cda0e4d..66408f5bbb3 100644 --- a/src/objective-c/GRPCClient/private/version.h +++ b/src/objective-c/GRPCClient/private/version.h @@ -38,4 +38,4 @@ // `tools/buildgen/generate_projects.sh`. -#define GRPC_OBJC_VERSION_STRING @"1.3.2" +#define GRPC_OBJC_VERSION_STRING @"1.3.3" diff --git a/src/php/composer.json b/src/php/composer.json index 3b7ba4162cb..bbe33974d5e 100644 --- a/src/php/composer.json +++ b/src/php/composer.json @@ -2,7 +2,7 @@ "name": "grpc/grpc-dev", "description": "gRPC library for PHP - for Developement use only", "license": "BSD-3-Clause", - "version": "1.3.2", + "version": "1.3.3", "require": { "php": ">=5.5.0", "google/protobuf": "^v3.1.0" diff --git a/src/python/grpcio/grpc_version.py b/src/python/grpcio/grpc_version.py index b07ec718918..027f6caf28c 100644 --- a/src/python/grpcio/grpc_version.py +++ b/src/python/grpcio/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio/grpc_version.py.template`!!! -VERSION='1.3.2' +VERSION='1.3.3' diff --git a/src/python/grpcio_health_checking/grpc_version.py b/src/python/grpcio_health_checking/grpc_version.py index 1615bd50a49..f2db8bb056f 100644 --- a/src/python/grpcio_health_checking/grpc_version.py +++ b/src/python/grpcio_health_checking/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_health_checking/grpc_version.py.template`!!! -VERSION='1.3.2' +VERSION='1.3.3' diff --git a/src/python/grpcio_reflection/grpc_version.py b/src/python/grpcio_reflection/grpc_version.py index 9fc16a90971..3f33eb3ed55 100644 --- a/src/python/grpcio_reflection/grpc_version.py +++ b/src/python/grpcio_reflection/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_reflection/grpc_version.py.template`!!! -VERSION='1.3.2' +VERSION='1.3.3' diff --git a/src/python/grpcio_tests/grpc_version.py b/src/python/grpcio_tests/grpc_version.py index 206315a983b..1a681d01360 100644 --- a/src/python/grpcio_tests/grpc_version.py +++ b/src/python/grpcio_tests/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/src/python/grpcio_tests/grpc_version.py.template`!!! -VERSION='1.3.2' +VERSION='1.3.3' diff --git a/src/ruby/lib/grpc/version.rb b/src/ruby/lib/grpc/version.rb index 7cd1f1e67a8..4ab94c91324 100644 --- a/src/ruby/lib/grpc/version.rb +++ b/src/ruby/lib/grpc/version.rb @@ -29,5 +29,5 @@ # GRPC contains the General RPC module. module GRPC - VERSION = '1.3.2' + VERSION = '1.3.3' end diff --git a/src/ruby/tools/version.rb b/src/ruby/tools/version.rb index ec562bfbe84..58e05d08143 100644 --- a/src/ruby/tools/version.rb +++ b/src/ruby/tools/version.rb @@ -29,6 +29,6 @@ module GRPC module Tools - VERSION = '1.3.2' + VERSION = '1.3.3' end end diff --git a/tools/distrib/python/grpcio_tools/grpc_version.py b/tools/distrib/python/grpcio_tools/grpc_version.py index d232250dec9..ecfa9d85e36 100644 --- a/tools/distrib/python/grpcio_tools/grpc_version.py +++ b/tools/distrib/python/grpcio_tools/grpc_version.py @@ -29,4 +29,4 @@ # AUTO-GENERATED FROM `$REPO_ROOT/templates/tools/distrib/python/grpcio_tools/grpc_version.py.template`!!! -VERSION='1.3.2' +VERSION='1.3.3' diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index 84850986dc9..8067aa764c1 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.2 +PROJECT_NUMBER = 1.3.3 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal index 9bec618dbd6..1a94b01e35e 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -40,7 +40,7 @@ PROJECT_NAME = "GRPC C++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.3.2 +PROJECT_NUMBER = 1.3.3 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a From 928681dc3d3c738eb807b457ccd72627ac344dd3 Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 16 May 2017 10:16:23 -0700 Subject: [PATCH 25/38] obsolete -> is obsolete --- src/cpp/server/server_builder.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cpp/server/server_builder.cc b/src/cpp/server/server_builder.cc index 1da7836e453..797a8eb095c 100644 --- a/src/cpp/server/server_builder.cc +++ b/src/cpp/server/server_builder.cc @@ -364,7 +364,7 @@ ServerBuilder& ServerBuilder::EnableWorkaround(uint32_t 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 obsolete.", id); + gpr_log(GPR_ERROR, "Workaround %u does not exist or is obsolete.", id); return *this; } } From b1e5bac392a3c229eed5df16a6b8ea850501ef39 Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 16 May 2017 11:07:55 -0700 Subject: [PATCH 26/38] Add /doc/workarounds.md --- doc/workarounds.md | 20 ++++++++++++++++++++ include/grpc++/server_builder.h | 2 +- include/grpc/support/workaround_list.h | 2 +- 3 files changed, 22 insertions(+), 2 deletions(-) create mode 100644 doc/workarounds.md diff --git a/doc/workarounds.md b/doc/workarounds.md new file mode 100644 index 00000000000..4dd1a2c83c5 --- /dev/null +++ b/doc/workarounds.md @@ -0,0 +1,20 @@ +# 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 Lists + +| Workaround ID | Date added | Issue | Workaround Description | Status | +|-------------------------------------|--------------|---------------------------------------------------|------------------------------------------------------|--------------------------| +| WORKAROUND\_ID\_CRONET\_COMPRESSION | May 06, 2017 | Before version v1.3.0-dev, gRPC iOS client's | Implemented as a server channel filter in C core. | Implemented in C and C++ | +| | | Cronet transport did not implement compression. | The filter identifies the version of peer client | | +| | | However the clients still claim to support | with incoming `user-agent` header of each call. If | | +| | | compression. As a result, a client fails to parse | the client's gRPC version is lower that or equal to | | +| | | received message when the message is compressed. | v1.3.x, a flag GRPC\_WRITE\_NO\_COMPRESS is marked | | +| | | | for all send\_message ops which prevents compression | | +| | | The problem above was resolved in gRPC v1.3.0-dev.| of the messages to be sent out. | | +| | | For backward compatibility, a server must | | | +| | | forcingly disable compression for gRPC clients of | | | +| | | version lower than or equal to v1.3.0-dev. | | | + diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h index 2dcd0701a2b..3c989c041dd 100644 --- a/include/grpc++/server_builder.h +++ b/include/grpc++/server_builder.h @@ -186,7 +186,7 @@ class ServerBuilder { /// Enable a server workaround. Do not use unless you know what the workaround /// does. For explanation and detailed descriptions of workarounds, see - /// docs/workarounds.md. + /// doc/workarounds.md. ServerBuilder& EnableWorkaround(uint32_t id); private: diff --git a/include/grpc/support/workaround_list.h b/include/grpc/support/workaround_list.h index 6a8aa1f9550..ec4766510f3 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, From a31b9d6bf447a64c46d344043f04c8a0cd4741c5 Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 16 May 2017 11:15:47 -0700 Subject: [PATCH 27/38] Alternate workaround description style --- doc/workarounds.md | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/doc/workarounds.md b/doc/workarounds.md index 4dd1a2c83c5..0446db65b68 100644 --- a/doc/workarounds.md +++ b/doc/workarounds.md @@ -5,16 +5,11 @@ This document lists the workarounds implemented on gRPC servers for record and r ## Workaround Lists -| Workaround ID | Date added | Issue | Workaround Description | Status | -|-------------------------------------|--------------|---------------------------------------------------|------------------------------------------------------|--------------------------| -| WORKAROUND\_ID\_CRONET\_COMPRESSION | May 06, 2017 | Before version v1.3.0-dev, gRPC iOS client's | Implemented as a server channel filter in C core. | Implemented in C and C++ | -| | | Cronet transport did not implement compression. | The filter identifies the version of peer client | | -| | | However the clients still claim to support | with incoming `user-agent` header of each call. If | | -| | | compression. As a result, a client fails to parse | the client's gRPC version is lower that or equal to | | -| | | received message when the message is compressed. | v1.3.x, a flag GRPC\_WRITE\_NO\_COMPRESS is marked | | -| | | | for all send\_message ops which prevents compression | | -| | | The problem above was resolved in gRPC v1.3.0-dev.| of the messages to be sent out. | | -| | | For backward compatibility, a server must | | | -| | | forcingly disable compression for gRPC clients of | | | -| | | version lower than or equal to v1.3.0-dev. | | | - +### 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. From 719d37397d3ec8fdb64e4b9497a414067a4fce53 Mon Sep 17 00:00:00 2001 From: Jan Tattermusch Date: Tue, 16 May 2017 20:18:27 +0200 Subject: [PATCH 28/38] dont use non-blittable types in native method signatures --- src/csharp/Grpc.Core/Internal/CallSafeHandle.cs | 4 ++-- src/csharp/Grpc.Core/Internal/NativeMethods.cs | 6 +++--- .../Grpc.Core/Internal/ServerCredentialsSafeHandle.cs | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs b/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs index 3c368fbc6cd..8ed0c0b92f7 100644 --- a/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs +++ b/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs @@ -117,7 +117,7 @@ namespace Grpc.Core.Internal { 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 @@ namespace Grpc.Core.Internal 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 a98861af616..696987d2a85 100644 --- a/src/csharp/Grpc.Core/Internal/NativeMethods.cs +++ b/src/csharp/Grpc.Core/Internal/NativeMethods.cs @@ -346,11 +346,11 @@ namespace Grpc.Core.Internal 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 @@ namespace Grpc.Core.Internal 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 24f686fddc1..c14fa7c8270 100644 --- a/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs +++ b/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs @@ -53,7 +53,7 @@ namespace Grpc.Core.Internal return Native.grpcsharp_ssl_server_credentials_create(pemRootCerts, keyCertPairCertChainArray, keyCertPairPrivateKeyArray, new UIntPtr((ulong)keyCertPairCertChainArray.Length), - forceClientAuth); + forceClientAuth ? 1 : 0); } protected override bool ReleaseHandle() From d212a021e4d6e065ef3458012155ae7d6dd71623 Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 16 May 2017 11:21:00 -0700 Subject: [PATCH 29/38] Polish workarounds.md --- doc/workarounds.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/workarounds.md b/doc/workarounds.md index 0446db65b68..bc511860f87 100644 --- a/doc/workarounds.md +++ b/doc/workarounds.md @@ -3,13 +3,17 @@ ## Introduction This document lists the workarounds implemented on gRPC servers for record and reference when users need to enable a certain workaround. -## Workaround Lists +## 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. From 7aa3a7fb6e847fb7b2674fe5f903ba22276c42c2 Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Tue, 16 May 2017 18:26:47 -0700 Subject: [PATCH 30/38] generate_project --- tools/doxygen/Doxyfile.c++ | 1 + tools/doxygen/Doxyfile.c++.internal | 1 + tools/doxygen/Doxyfile.core | 1 + tools/doxygen/Doxyfile.core.internal | 1 + 4 files changed, 4 insertions(+) diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index b7531bc276f..b6f2857b391 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -794,6 +794,7 @@ doc/statuscodes.md \ 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 5bae9fad9bf..a2349bc0a25 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -794,6 +794,7 @@ doc/statuscodes.md \ 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 74e76bfce9c..c5ae421d40c 100644 --- a/tools/doxygen/Doxyfile.core +++ b/tools/doxygen/Doxyfile.core @@ -794,6 +794,7 @@ doc/statuscodes.md \ 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 597f22b6340..7f2ccc97330 100644 --- a/tools/doxygen/Doxyfile.core.internal +++ b/tools/doxygen/Doxyfile.core.internal @@ -794,6 +794,7 @@ doc/statuscodes.md \ 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 \ From b2574bfb68c6fa8817e268fb90f94dae79297aba Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Wed, 17 May 2017 09:01:28 -0700 Subject: [PATCH 31/38] Fix runtests --force_default_poller on linux --- tools/run_tests/run_tests.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/run_tests/run_tests.py b/tools/run_tests/run_tests.py index 1a16b093259..830c356d913 100755 --- a/tools/run_tests/run_tests.py +++ b/tools/run_tests/run_tests.py @@ -1459,7 +1459,7 @@ def _build_and_run( 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') From f6b622c08a908f6c67cebfd554f3e2039298416f Mon Sep 17 00:00:00 2001 From: Muxi Yan Date: Wed, 17 May 2017 10:34:10 -0700 Subject: [PATCH 32/38] Take grpc_workaround_list as parameter --- include/grpc++/server_builder.h | 3 ++- src/cpp/server/server_builder.cc | 3 +-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h index 3c989c041dd..e0aa2a5b94b 100644 --- a/include/grpc++/server_builder.h +++ b/include/grpc++/server_builder.h @@ -46,6 +46,7 @@ #include #include #include +#include struct grpc_resource_quota; @@ -187,7 +188,7 @@ class ServerBuilder { /// 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(uint32_t id); + ServerBuilder& EnableWorkaround(grpc_workaround_list id); private: friend class ::grpc::testing::ServerBuilderPluginTest; diff --git a/src/cpp/server/server_builder.cc b/src/cpp/server/server_builder.cc index 797a8eb095c..6dca6a6862c 100644 --- a/src/cpp/server/server_builder.cc +++ b/src/cpp/server/server_builder.cc @@ -39,7 +39,6 @@ #include #include #include -#include #include "src/cpp/server/thread_pool_interface.h" @@ -359,7 +358,7 @@ void ServerBuilder::InternalAddPluginFactory( (*g_plugin_factory_list).push_back(CreatePlugin); } -ServerBuilder& ServerBuilder::EnableWorkaround(uint32_t id) { +ServerBuilder& ServerBuilder::EnableWorkaround(grpc_workaround_list id) { switch (id) { case GRPC_WORKAROUND_ID_CRONET_COMPRESSION: return AddChannelArgument(GRPC_ARG_WORKAROUND_CRONET_COMPRESSION, 1); From d7389b418f9ea077e4ab3de2b53362ab02ab6870 Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Wed, 17 May 2017 12:22:17 -0700 Subject: [PATCH 33/38] Implement grpclb drop support. --- .../filters/client_channel/client_channel.c | 18 +- .../ext/filters/client_channel/lb_policy.h | 4 +- .../client_channel/lb_policy/grpclb/grpclb.c | 81 +++++-- .../lb_policy/grpclb/load_balancer_api.c | 89 ++++---- .../lb_policy/grpclb/load_balancer_api.h | 2 +- test/cpp/end2end/grpclb_end2end_test.cc | 207 ++++++++++++++---- 6 files changed, 287 insertions(+), 114 deletions(-) diff --git a/src/core/ext/filters/client_channel/client_channel.c b/src/core/ext/filters/client_channel/client_channel.c index 24843d52e9f..f2f27b9175a 100644 --- a/src/core/ext/filters/client_channel/client_channel.c +++ b/src/core/ext/filters/client_channel/client_channel.c @@ -914,10 +914,13 @@ static void subchannel_ready_locked(grpc_exec_ctx *exec_ctx, void *arg, grpc_polling_entity_del_from_pollset_set(exec_ctx, calld->pollent, chand->interested_parties); if (calld->connected_subchannel == NULL) { - gpr_atm_no_barrier_store(&calld->subchannel_call, 1); + gpr_atm_no_barrier_store(&calld->subchannel_call, (gpr_atm)CANCELLED_CALL); fail_locked(exec_ctx, calld, - GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING( - "Failed to create subchannel", &error, 1)); + error == GRPC_ERROR_NONE + ? GRPC_ERROR_CREATE_FROM_STATIC_STRING( + "Call dropped by load balancing policy") + : GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING( + "Failed to create subchannel", &error, 1)); } else if (GET_CALL(calld) == CANCELLED_CALL) { /* already cancelled before subchannel became ready */ grpc_error *cancellation_error = @@ -1180,6 +1183,15 @@ static void start_transport_stream_op_batch_locked_inner( &calld->next_step)) { calld->pick_pending = false; GRPC_CALL_STACK_UNREF(exec_ctx, calld->owning_call, "pick_subchannel"); + if (calld->connected_subchannel == NULL) { + gpr_atm_no_barrier_store(&calld->subchannel_call, + (gpr_atm)CANCELLED_CALL); + grpc_error *error = GRPC_ERROR_CREATE_FROM_STATIC_STRING( + "Call dropped by load balancing policy"); + fail_locked(exec_ctx, calld, GRPC_ERROR_REF(error)); + grpc_transport_stream_op_batch_finish_with_failure(exec_ctx, op, error); + return; // Early out. + } } else { grpc_polling_entity_add_to_pollset_set(exec_ctx, calld->pollent, chand->interested_parties); diff --git a/src/core/ext/filters/client_channel/lb_policy.h b/src/core/ext/filters/client_channel/lb_policy.h index 184b2ef720c..fb4aa084a61 100644 --- a/src/core/ext/filters/client_channel/lb_policy.h +++ b/src/core/ext/filters/client_channel/lb_policy.h @@ -149,7 +149,9 @@ void grpc_lb_policy_init(grpc_lb_policy *policy, /** Finds an appropriate subchannel for a call, based on \a pick_args. - \a target will be set to the selected subchannel, or NULL on failure. + \a target will be set to the selected subchannel, or NULL on failure + or when the LB policy decides to drop the call. + Upon success, \a user_data will be set to whatever opaque information may need to be propagated from the LB policy, or NULL if not needed. \a context will be populated with context to pass to the subchannel diff --git a/src/core/ext/filters/client_channel/lb_policy/grpclb/grpclb.c b/src/core/ext/filters/client_channel/lb_policy/grpclb/grpclb.c index b7c0e929b7e..d2a2856a180 100644 --- a/src/core/ext/filters/client_channel/lb_policy/grpclb/grpclb.c +++ b/src/core/ext/filters/client_channel/lb_policy/grpclb/grpclb.c @@ -327,6 +327,11 @@ typedef struct glb_lb_policy { * response has arrived. */ grpc_grpclb_serverlist *serverlist; + /** Index into serverlist for next pick. + * If the server at this index is a drop, we return a drop. + * Otherwise, we delegate to the RR policy. */ + size_t serverlist_index; + /** list of picks that are waiting on RR's policy connectivity */ pending_pick *pending_picks; @@ -402,6 +407,9 @@ struct rr_connectivity_data { static bool is_server_valid(const grpc_grpclb_server *server, size_t idx, bool log) { + if (server->drop_for_rate_limiting || server->drop_for_load_balancing) { + return false; + } const grpc_grpclb_ip_address *ip = &server->ip_address; if (server->port >> 16 != 0) { if (log) { @@ -411,7 +419,6 @@ static bool is_server_valid(const grpc_grpclb_server *server, size_t idx, } return false; } - if (ip->size != 4 && ip->size != 16) { if (log) { gpr_log(GPR_ERROR, @@ -445,11 +452,12 @@ static const grpc_lb_user_data_vtable lb_token_vtable = { static void parse_server(const grpc_grpclb_server *server, grpc_resolved_address *addr) { + memset(addr, 0, sizeof(*addr)); + if (server->drop_for_rate_limiting || server->drop_for_load_balancing) return; const uint16_t netorder_port = htons((uint16_t)server->port); /* the addresses are given in binary format (a in(6)_addr struct) in * server->ip_address.bytes. */ const grpc_grpclb_ip_address *ip = &server->ip_address; - memset(addr, 0, sizeof(*addr)); if (ip->size == 4) { addr->len = sizeof(struct sockaddr_in); struct sockaddr_in *addr4 = (struct sockaddr_in *)&addr->addr; @@ -586,16 +594,51 @@ static bool update_lb_connectivity_status_locked( return true; } -/* perform a pick over \a rr_policy. Given that a pick can return immediately - * (ignoring its completion callback) we need to perform the cleanups this - * callback would be otherwise resposible for */ +/* Perform a pick over \a glb_policy->rr_policy. Given that a pick can return + * immediately (ignoring its completion callback), we need to perform the + * cleanups this callback would otherwise be resposible for. + * If \a force_async is true, then we will manually schedule the + * completion callback even if the pick is available immediately. */ static bool pick_from_internal_rr_locked( - grpc_exec_ctx *exec_ctx, grpc_lb_policy *rr_policy, - const grpc_lb_policy_pick_args *pick_args, + grpc_exec_ctx *exec_ctx, glb_lb_policy *glb_policy, + const grpc_lb_policy_pick_args *pick_args, bool force_async, grpc_connected_subchannel **target, wrapped_rr_closure_arg *wc_arg) { - GPR_ASSERT(rr_policy != NULL); + // Look at the index into the serverlist to see if we should drop this call. + grpc_grpclb_server *server = + glb_policy->serverlist->servers[glb_policy->serverlist_index++]; + if (glb_policy->serverlist_index == glb_policy->serverlist->num_servers) { + glb_policy->serverlist_index = 0; // Wrap-around. + } + if (server->drop_for_rate_limiting || server->drop_for_load_balancing) { + // Not using the RR policy, so unref it. + if (GRPC_TRACER_ON(grpc_lb_glb_trace)) { + gpr_log(GPR_INFO, "Unreffing RR for drop (0x%" PRIxPTR ")", + (intptr_t)wc_arg->rr_policy); + } + GRPC_LB_POLICY_UNREF(exec_ctx, wc_arg->rr_policy, "glb_pick_sync"); + // Update client load reporting stats to indicate the number of + // dropped calls. Note that we have to do this here instead of in + // the client_load_reporting filter, because we do not create a + // subchannel call (and therefore no client_load_reporting filter) + // for dropped calls. + grpc_grpclb_client_stats_add_call_started(wc_arg->client_stats); + grpc_grpclb_client_stats_add_call_finished( + server->drop_for_rate_limiting, server->drop_for_load_balancing, + false /* failed_to_send */, false /* known_received */, + wc_arg->client_stats); + grpc_grpclb_client_stats_unref(wc_arg->client_stats); + if (force_async) { + GPR_ASSERT(wc_arg->wrapped_closure != NULL); + grpc_closure_sched(exec_ctx, wc_arg->wrapped_closure, GRPC_ERROR_NONE); + gpr_free(wc_arg->free_when_done); + return false; + } + gpr_free(wc_arg->free_when_done); + return true; + } + // Pick via the RR policy. const bool pick_done = grpc_lb_policy_pick_locked( - exec_ctx, rr_policy, pick_args, target, wc_arg->context, + exec_ctx, wc_arg->rr_policy, pick_args, target, wc_arg->context, (void **)&wc_arg->lb_token, &wc_arg->wrapper_closure); if (pick_done) { /* synchronous grpc_lb_policy_pick call. Unref the RR policy. */ @@ -604,17 +647,20 @@ static bool pick_from_internal_rr_locked( (intptr_t)wc_arg->rr_policy); } GRPC_LB_POLICY_UNREF(exec_ctx, wc_arg->rr_policy, "glb_pick_sync"); - /* add the load reporting initial metadata */ initial_metadata_add_lb_token(exec_ctx, pick_args->initial_metadata, pick_args->lb_token_mdelem_storage, GRPC_MDELEM_REF(wc_arg->lb_token)); - // Pass on client stats via context. Passes ownership of the reference. GPR_ASSERT(wc_arg->client_stats != NULL); wc_arg->context[GRPC_GRPCLB_CLIENT_STATS].value = wc_arg->client_stats; wc_arg->context[GRPC_GRPCLB_CLIENT_STATS].destroy = destroy_client_stats; - + if (force_async) { + GPR_ASSERT(wc_arg->wrapped_closure != NULL); + grpc_closure_sched(exec_ctx, wc_arg->wrapped_closure, GRPC_ERROR_NONE); + gpr_free(wc_arg->free_when_done); + return false; + } gpr_free(wc_arg->free_when_done); } /* else, the pending pick will be registered and taken care of by the @@ -744,8 +790,8 @@ static void rr_handover_locked(grpc_exec_ctx *exec_ctx, gpr_log(GPR_INFO, "Pending pick about to PICK from 0x%" PRIxPTR "", (intptr_t)glb_policy->rr_policy); } - pick_from_internal_rr_locked(exec_ctx, glb_policy->rr_policy, - &pp->pick_args, pp->target, + pick_from_internal_rr_locked(exec_ctx, glb_policy, &pp->pick_args, + true /* force_async */, pp->target, &pp->wrapped_on_complete_arg); } @@ -1115,8 +1161,9 @@ static int glb_pick_locked(grpc_exec_ctx *exec_ctx, grpc_lb_policy *pol, wc_arg->lb_token_mdelem_storage = pick_args->lb_token_mdelem_storage; wc_arg->initial_metadata = pick_args->initial_metadata; wc_arg->free_when_done = wc_arg; - pick_done = pick_from_internal_rr_locked(exec_ctx, glb_policy->rr_policy, - pick_args, target, wc_arg); + pick_done = + pick_from_internal_rr_locked(exec_ctx, glb_policy, pick_args, + false /* force_async */, target, wc_arg); } else { if (GRPC_TRACER_ON(grpc_lb_glb_trace)) { gpr_log(GPR_DEBUG, @@ -1517,7 +1564,7 @@ static void lb_on_response_received_locked(grpc_exec_ctx *exec_ctx, void *arg, * serverlist instance will be destroyed either upon the next * update or in glb_destroy() */ glb_policy->serverlist = serverlist; - + glb_policy->serverlist_index = 0; rr_handover_locked(exec_ctx, glb_policy); } } else { diff --git a/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.c b/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.c index 81b6932faeb..90e7c2efe53 100644 --- a/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.c +++ b/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.c @@ -37,44 +37,39 @@ #include +/* invoked once for every Server in ServerList */ +static bool count_serverlist(pb_istream_t *stream, const pb_field_t *field, + void **arg) { + grpc_grpclb_serverlist *sl = *arg; + grpc_grpclb_server server; + if (!pb_decode(stream, grpc_lb_v1_Server_fields, &server)) { + gpr_log(GPR_ERROR, "nanopb error: %s", PB_GET_ERROR(stream)); + return false; + } + ++sl->num_servers; + return true; +} + typedef struct decode_serverlist_arg { - /* The first pass counts the number of servers in the server list. The second - * one allocates and decodes. */ - bool first_pass; /* The decoding callback is invoked once per server in serverlist. Remember * which index of the serverlist are we currently decoding */ size_t decoding_idx; - /* Populated after the first pass. Number of server in the input serverlist */ - size_t num_servers; /* The decoded serverlist */ - grpc_grpclb_server **servers; + grpc_grpclb_serverlist *serverlist; } decode_serverlist_arg; /* invoked once for every Server in ServerList */ static bool decode_serverlist(pb_istream_t *stream, const pb_field_t *field, void **arg) { decode_serverlist_arg *dec_arg = *arg; - if (dec_arg->first_pass) { /* count how many server do we have */ - grpc_grpclb_server server; - if (!pb_decode(stream, grpc_lb_v1_Server_fields, &server)) { - gpr_log(GPR_ERROR, "nanopb error: %s", PB_GET_ERROR(stream)); - return false; - } - dec_arg->num_servers++; - } else { /* second pass. Actually decode. */ - grpc_grpclb_server *server = gpr_zalloc(sizeof(grpc_grpclb_server)); - GPR_ASSERT(dec_arg->num_servers > 0); - if (dec_arg->decoding_idx == 0) { /* first iteration of second pass */ - dec_arg->servers = - gpr_malloc(sizeof(grpc_grpclb_server *) * dec_arg->num_servers); - } - if (!pb_decode(stream, grpc_lb_v1_Server_fields, server)) { - gpr_log(GPR_ERROR, "nanopb error: %s", PB_GET_ERROR(stream)); - return false; - } - dec_arg->servers[dec_arg->decoding_idx++] = server; + GPR_ASSERT(dec_arg->serverlist->num_servers >= dec_arg->decoding_idx); + grpc_grpclb_server *server = gpr_zalloc(sizeof(grpc_grpclb_server)); + if (!pb_decode(stream, grpc_lb_v1_Server_fields, server)) { + gpr_free(server); + gpr_log(GPR_ERROR, "nanopb error: %s", PB_GET_ERROR(stream)); + return false; } - + dec_arg->serverlist->servers[dec_arg->decoding_idx++] = server; return true; } @@ -165,36 +160,38 @@ grpc_grpclb_initial_response *grpc_grpclb_initial_response_parse( grpc_grpclb_serverlist *grpc_grpclb_response_parse_serverlist( grpc_slice encoded_grpc_grpclb_response) { - bool status; - decode_serverlist_arg arg; pb_istream_t stream = pb_istream_from_buffer(GRPC_SLICE_START_PTR(encoded_grpc_grpclb_response), GRPC_SLICE_LENGTH(encoded_grpc_grpclb_response)); pb_istream_t stream_at_start = stream; + grpc_grpclb_serverlist *sl = gpr_zalloc(sizeof(grpc_grpclb_serverlist)); grpc_grpclb_response res; memset(&res, 0, sizeof(grpc_grpclb_response)); - memset(&arg, 0, sizeof(decode_serverlist_arg)); - - res.server_list.servers.funcs.decode = decode_serverlist; - res.server_list.servers.arg = &arg; - arg.first_pass = true; - status = pb_decode(&stream, grpc_lb_v1_LoadBalanceResponse_fields, &res); + // First pass: count number of servers. + res.server_list.servers.funcs.decode = count_serverlist; + res.server_list.servers.arg = sl; + bool status = pb_decode(&stream, grpc_lb_v1_LoadBalanceResponse_fields, &res); if (!status) { + gpr_free(sl); gpr_log(GPR_ERROR, "nanopb error: %s", PB_GET_ERROR(&stream)); return NULL; } - - arg.first_pass = false; - status = - pb_decode(&stream_at_start, grpc_lb_v1_LoadBalanceResponse_fields, &res); - if (!status) { - gpr_log(GPR_ERROR, "nanopb error: %s", PB_GET_ERROR(&stream)); - return NULL; + // Second pass: populate servers. + if (sl->num_servers > 0) { + sl->servers = gpr_zalloc(sizeof(grpc_grpclb_server *) * sl->num_servers); + decode_serverlist_arg decode_arg; + memset(&decode_arg, 0, sizeof(decode_arg)); + decode_arg.serverlist = sl; + res.server_list.servers.funcs.decode = decode_serverlist; + res.server_list.servers.arg = &decode_arg; + status = pb_decode(&stream_at_start, grpc_lb_v1_LoadBalanceResponse_fields, + &res); + if (!status) { + grpc_grpclb_destroy_serverlist(sl); + gpr_log(GPR_ERROR, "nanopb error: %s", PB_GET_ERROR(&stream)); + return NULL; + } } - - grpc_grpclb_serverlist *sl = gpr_zalloc(sizeof(grpc_grpclb_serverlist)); - sl->num_servers = arg.num_servers; - sl->servers = arg.servers; if (res.server_list.has_expiration_interval) { sl->expiration_interval = res.server_list.expiration_interval; } @@ -228,7 +225,7 @@ grpc_grpclb_serverlist *grpc_grpclb_serverlist_copy( bool grpc_grpclb_serverlist_equals(const grpc_grpclb_serverlist *lhs, const grpc_grpclb_serverlist *rhs) { - if ((lhs == NULL) || (rhs == NULL)) { + if (lhs == NULL || rhs == NULL) { return false; } if (lhs->num_servers != rhs->num_servers) { diff --git a/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.h b/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.h index 06873821bd3..7f596ce1f1d 100644 --- a/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.h +++ b/src/core/ext/filters/client_channel/lb_policy/grpclb/load_balancer_api.h @@ -51,7 +51,7 @@ typedef grpc_lb_v1_LoadBalanceRequest grpc_grpclb_request; typedef grpc_lb_v1_InitialLoadBalanceResponse grpc_grpclb_initial_response; typedef grpc_lb_v1_Server grpc_grpclb_server; typedef grpc_lb_v1_Duration grpc_grpclb_duration; -typedef struct grpc_grpclb_serverlist { +typedef struct { grpc_grpclb_server **servers; size_t num_servers; grpc_grpclb_duration expiration_interval; diff --git a/test/cpp/end2end/grpclb_end2end_test.cc b/test/cpp/end2end/grpclb_end2end_test.cc index 8417f1a99c8..4e1bcc7a60d 100644 --- a/test/cpp/end2end/grpclb_end2end_test.cc +++ b/test/cpp/end2end/grpclb_end2end_test.cc @@ -98,12 +98,12 @@ namespace { template class CountedService : public ServiceType { public: - int request_count() { + size_t request_count() { std::unique_lock lock(mu_); return request_count_; } - int response_count() { + size_t response_count() { std::unique_lock lock(mu_); return response_count_; } @@ -121,8 +121,8 @@ class CountedService : public ServiceType { std::mutex mu_; private: - int request_count_ = 0; - int response_count_ = 0; + size_t request_count_ = 0; + size_t response_count_ = 0; }; using BackendService = CountedService; @@ -243,9 +243,18 @@ class BalancerServiceImpl : public BalancerService { } static LoadBalanceResponse BuildResponseForBackends( - const std::vector& backend_ports) { + const std::vector& backend_ports, int num_drops_for_rate_limiting, + int num_drops_for_load_balancing) { LoadBalanceResponse response; - for (const int backend_port : backend_ports) { + for (int i = 0; i < num_drops_for_rate_limiting; ++i) { + auto* server = response.mutable_server_list()->add_servers(); + server->set_drop_for_rate_limiting(true); + } + for (int i = 0; i < num_drops_for_load_balancing; ++i) { + auto* server = response.mutable_server_list()->add_servers(); + server->set_drop_for_load_balancing(true); + } + for (const int& backend_port : backend_ports) { auto* server = response.mutable_server_list()->add_servers(); server->set_ip_address(Ip4ToPackedString("127.0.0.1")); server->set_port(backend_port); @@ -327,10 +336,8 @@ class GrpclbEnd2endTest : public ::testing::Test { ChannelArguments args; args.SetPointer(GRPC_ARG_FAKE_RESOLVER_RESPONSE_GENERATOR, response_generator_); - std::ostringstream uri; - uri << "test:///servername_not_used"; - channel_ = - CreateCustomChannel(uri.str(), InsecureChannelCredentials(), args); + channel_ = CreateCustomChannel("test:///not_used", + InsecureChannelCredentials(), args); stub_ = grpc::testing::EchoTestService::NewStub(channel_); } @@ -467,26 +474,33 @@ class SingleBalancerTest : public GrpclbEnd2endTest { }; TEST_F(SingleBalancerTest, Vanilla) { + const size_t kNumRpcsPerAddress = 100; ScheduleResponseForBalancer( - 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts()), 0); + 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts(), 0, 0), + 0); // Make sure that trying to connect works without a call. channel_->GetState(true /* try_to_connect */); - // Start servers and send 100 RPCs per server. - const auto& statuses_and_responses = SendRpc(kMessage_, 100 * num_backends_); + // Send 100 RPCs per server. + const auto& statuses_and_responses = + SendRpc(kMessage_, kNumRpcsPerAddress * num_backends_); for (const auto& status_and_response : statuses_and_responses) { - EXPECT_TRUE(status_and_response.first.ok()); - EXPECT_EQ(status_and_response.second.message(), kMessage_); + const Status& status = status_and_response.first; + const EchoResponse& response = status_and_response.second; + EXPECT_TRUE(status.ok()) << "code=" << status.error_code() + << " message=" << status.error_message(); + EXPECT_EQ(response.message(), kMessage_); } // Each backend should have gotten 100 requests. for (size_t i = 0; i < backends_.size(); ++i) { - EXPECT_EQ(100, backend_servers_[i].service_->request_count()); + EXPECT_EQ(kNumRpcsPerAddress, + backend_servers_[i].service_->request_count()); } // The balancer got a single request. - EXPECT_EQ(1, balancer_servers_[0].service_->request_count()); + EXPECT_EQ(1U, balancer_servers_[0].service_->request_count()); // and sent a single response. - EXPECT_EQ(1, balancer_servers_[0].service_->response_count()); + EXPECT_EQ(1U, balancer_servers_[0].service_->response_count()); // Check LB policy name for the channel. EXPECT_EQ("grpclb", channel_->GetLoadBalancingPolicyName()); @@ -500,7 +514,7 @@ TEST_F(SingleBalancerTest, InitiallyEmptyServerlist) { ScheduleResponseForBalancer(0, LoadBalanceResponse(), 0); // Send non-empty serverlist only after kServerlistDelayMs ScheduleResponseForBalancer( - 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts()), + 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts(), 0, 0), kServerlistDelayMs); const auto t0 = system_clock::now(); @@ -518,17 +532,20 @@ TEST_F(SingleBalancerTest, InitiallyEmptyServerlist) { // Each backend should have gotten 1 request. for (size_t i = 0; i < backends_.size(); ++i) { - EXPECT_EQ(1, backend_servers_[i].service_->request_count()); + EXPECT_EQ(1U, backend_servers_[i].service_->request_count()); } for (const auto& status_and_response : statuses_and_responses) { - EXPECT_TRUE(status_and_response.first.ok()); - EXPECT_EQ(status_and_response.second.message(), kMessage_); + const Status& status = status_and_response.first; + const EchoResponse& response = status_and_response.second; + EXPECT_TRUE(status.ok()) << "code=" << status.error_code() + << " message=" << status.error_message(); + EXPECT_EQ(response.message(), kMessage_); } // The balancer got a single request. - EXPECT_EQ(1, balancer_servers_[0].service_->request_count()); + EXPECT_EQ(1U, balancer_servers_[0].service_->request_count()); // and sent two responses. - EXPECT_EQ(2, balancer_servers_[0].service_->response_count()); + EXPECT_EQ(2U, balancer_servers_[0].service_->response_count()); // Check LB policy name for the channel. EXPECT_EQ("grpclb", channel_->GetLoadBalancingPolicyName()); @@ -539,10 +556,11 @@ TEST_F(SingleBalancerTest, RepeatedServerlist) { // Send a serverlist right away. ScheduleResponseForBalancer( - 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts()), 0); + 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts(), 0, 0), + 0); // ... and the same one a bit later. ScheduleResponseForBalancer( - 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts()), + 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts(), 0, 0), kServerlistDelayMs); // Send num_backends/2 requests. @@ -550,14 +568,17 @@ TEST_F(SingleBalancerTest, RepeatedServerlist) { // only the first half of the backends will receive them. for (size_t i = 0; i < backends_.size(); ++i) { if (i < backends_.size() / 2) - EXPECT_EQ(1, backend_servers_[i].service_->request_count()); + EXPECT_EQ(1U, backend_servers_[i].service_->request_count()); else - EXPECT_EQ(0, backend_servers_[i].service_->request_count()); + EXPECT_EQ(0U, backend_servers_[i].service_->request_count()); } EXPECT_EQ(statuses_and_responses.size(), num_backends_ / 2); for (const auto& status_and_response : statuses_and_responses) { - EXPECT_TRUE(status_and_response.first.ok()); - EXPECT_EQ(status_and_response.second.message(), kMessage_); + const Status& status = status_and_response.first; + const EchoResponse& response = status_and_response.second; + EXPECT_TRUE(status.ok()) << "code=" << status.error_code() + << " message=" << status.error_message(); + EXPECT_EQ(response.message(), kMessage_); } // Wait for the (duplicated) serverlist update. @@ -566,7 +587,7 @@ TEST_F(SingleBalancerTest, RepeatedServerlist) { gpr_time_from_millis(kServerlistDelayMs * 1.1, GPR_TIMESPAN))); // Verify the LB has sent two responses. - EXPECT_EQ(2, balancer_servers_[0].service_->response_count()); + EXPECT_EQ(2U, balancer_servers_[0].service_->response_count()); // Some more calls to complete the total number of backends. statuses_and_responses = SendRpc( @@ -575,52 +596,146 @@ TEST_F(SingleBalancerTest, RepeatedServerlist) { // Because a duplicated serverlist should have no effect, all backends must // have been hit once now. for (size_t i = 0; i < backends_.size(); ++i) { - EXPECT_EQ(1, backend_servers_[i].service_->request_count()); + EXPECT_EQ(1U, backend_servers_[i].service_->request_count()); } EXPECT_EQ(statuses_and_responses.size(), num_backends_ / 2); for (const auto& status_and_response : statuses_and_responses) { - EXPECT_TRUE(status_and_response.first.ok()); - EXPECT_EQ(status_and_response.second.message(), kMessage_); + const Status& status = status_and_response.first; + const EchoResponse& response = status_and_response.second; + EXPECT_TRUE(status.ok()) << "code=" << status.error_code() + << " message=" << status.error_message(); + EXPECT_EQ(response.message(), kMessage_); } // The balancer got a single request. - EXPECT_EQ(1, balancer_servers_[0].service_->request_count()); + EXPECT_EQ(1U, balancer_servers_[0].service_->request_count()); // Check LB policy name for the channel. EXPECT_EQ("grpclb", channel_->GetLoadBalancingPolicyName()); } +TEST_F(SingleBalancerTest, Drop) { + const size_t kNumRpcsPerAddress = 100; + ScheduleResponseForBalancer( + 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts(), 1, 2), + 0); + // Send 100 RPCs for each server and drop address. + const auto& statuses_and_responses = + SendRpc(kMessage_, kNumRpcsPerAddress * (num_backends_ + 3)); + + size_t num_drops = 0; + for (const auto& status_and_response : statuses_and_responses) { + const Status& status = status_and_response.first; + const EchoResponse& response = status_and_response.second; + if (!status.ok() && + status.error_message() == "Call dropped by load balancing policy") { + ++num_drops; + } else { + EXPECT_TRUE(status.ok()) << "code=" << status.error_code() + << " message=" << status.error_message(); + EXPECT_EQ(response.message(), kMessage_); + } + } + EXPECT_EQ(kNumRpcsPerAddress * 3, num_drops); + + // Each backend should have gotten 100 requests. + for (size_t i = 0; i < backends_.size(); ++i) { + EXPECT_EQ(kNumRpcsPerAddress, + backend_servers_[i].service_->request_count()); + } + // The balancer got a single request. + EXPECT_EQ(1U, balancer_servers_[0].service_->request_count()); + // and sent a single response. + EXPECT_EQ(1U, balancer_servers_[0].service_->response_count()); +} + class SingleBalancerWithClientLoadReportingTest : public GrpclbEnd2endTest { public: SingleBalancerWithClientLoadReportingTest() : GrpclbEnd2endTest(4, 1, 2) {} }; TEST_F(SingleBalancerWithClientLoadReportingTest, Vanilla) { + const size_t kNumRpcsPerAddress = 100; ScheduleResponseForBalancer( - 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts()), 0); - // Start servers and send 100 RPCs per server. - const auto& statuses_and_responses = SendRpc(kMessage_, 100 * num_backends_); + 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts(), 0, 0), + 0); + // Send 100 RPCs per server. + const auto& statuses_and_responses = + SendRpc(kMessage_, kNumRpcsPerAddress * num_backends_); for (const auto& status_and_response : statuses_and_responses) { - EXPECT_TRUE(status_and_response.first.ok()); - EXPECT_EQ(status_and_response.second.message(), kMessage_); + const Status& status = status_and_response.first; + const EchoResponse& response = status_and_response.second; + EXPECT_TRUE(status.ok()) << "code=" << status.error_code() + << " message=" << status.error_message(); + EXPECT_EQ(response.message(), kMessage_); } // Each backend should have gotten 100 requests. for (size_t i = 0; i < backends_.size(); ++i) { - EXPECT_EQ(100, backend_servers_[i].service_->request_count()); + EXPECT_EQ(kNumRpcsPerAddress, + backend_servers_[i].service_->request_count()); } // The balancer got a single request. - EXPECT_EQ(1, balancer_servers_[0].service_->request_count()); + EXPECT_EQ(1U, balancer_servers_[0].service_->request_count()); // and sent a single response. - EXPECT_EQ(1, balancer_servers_[0].service_->response_count()); + EXPECT_EQ(1U, balancer_servers_[0].service_->response_count()); const ClientStats client_stats = WaitForLoadReports(); - EXPECT_EQ(100 * num_backends_, client_stats.num_calls_started); - EXPECT_EQ(100 * num_backends_, client_stats.num_calls_finished); + EXPECT_EQ(kNumRpcsPerAddress * num_backends_, client_stats.num_calls_started); + EXPECT_EQ(kNumRpcsPerAddress * num_backends_, + client_stats.num_calls_finished); EXPECT_EQ(0U, client_stats.num_calls_finished_with_drop_for_rate_limiting); EXPECT_EQ(0U, client_stats.num_calls_finished_with_drop_for_load_balancing); EXPECT_EQ(0U, client_stats.num_calls_finished_with_client_failed_to_send); - EXPECT_EQ(100 * num_backends_, + EXPECT_EQ(kNumRpcsPerAddress * num_backends_, + client_stats.num_calls_finished_known_received); +} + +TEST_F(SingleBalancerWithClientLoadReportingTest, Drop) { + const size_t kNumRpcsPerAddress = 3; + ScheduleResponseForBalancer( + 0, BalancerServiceImpl::BuildResponseForBackends(GetBackendPorts(), 2, 1), + 0); + // Send 100 RPCs for each server and drop address. + const auto& statuses_and_responses = + SendRpc(kMessage_, kNumRpcsPerAddress * (num_backends_ + 3)); + + size_t num_drops = 0; + for (const auto& status_and_response : statuses_and_responses) { + const Status& status = status_and_response.first; + const EchoResponse& response = status_and_response.second; + if (!status.ok() && + status.error_message() == "Call dropped by load balancing policy") { + ++num_drops; + } else { + EXPECT_TRUE(status.ok()) << "code=" << status.error_code() + << " message=" << status.error_message(); + EXPECT_EQ(response.message(), kMessage_); + } + } + EXPECT_EQ(kNumRpcsPerAddress * 3, num_drops); + + // Each backend should have gotten 100 requests. + for (size_t i = 0; i < backends_.size(); ++i) { + EXPECT_EQ(kNumRpcsPerAddress, + backend_servers_[i].service_->request_count()); + } + // The balancer got a single request. + EXPECT_EQ(1U, balancer_servers_[0].service_->request_count()); + // and sent a single response. + EXPECT_EQ(1U, balancer_servers_[0].service_->response_count()); + + const ClientStats client_stats = WaitForLoadReports(); + EXPECT_EQ(kNumRpcsPerAddress * (num_backends_ + 3), + client_stats.num_calls_started); + EXPECT_EQ(kNumRpcsPerAddress * (num_backends_ + 3), + client_stats.num_calls_finished); + EXPECT_EQ(kNumRpcsPerAddress * 2, + client_stats.num_calls_finished_with_drop_for_rate_limiting); + EXPECT_EQ(kNumRpcsPerAddress, + client_stats.num_calls_finished_with_drop_for_load_balancing); + EXPECT_EQ(0U, client_stats.num_calls_finished_with_client_failed_to_send); + EXPECT_EQ(kNumRpcsPerAddress * num_backends_, client_stats.num_calls_finished_known_received); } From d15f5c015ac52d3e24e5fa5c2dbcd33e6e04433b Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Wed, 17 May 2017 13:21:05 -0700 Subject: [PATCH 34/38] PHP: fix pecl extension reported version --- build.yaml | 1 + package.xml | 1 + src/php/ext/grpc/php_grpc.h | 6 +-- src/php/ext/grpc/version.h | 40 ++++++++++++++++++ templates/src/php/ext/grpc/version.h.template | 42 +++++++++++++++++++ 5 files changed, 85 insertions(+), 5 deletions(-) create mode 100644 src/php/ext/grpc/version.h create mode 100644 templates/src/php/ext/grpc/version.h.template diff --git a/build.yaml b/build.yaml index 2c540557151..c780e829016 100644 --- a/build.yaml +++ b/build.yaml @@ -4642,6 +4642,7 @@ php_config_m4: - 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/package.xml b/package.xml index bb8617f6d6e..e1b6fc69f72 100644 --- a/package.xml +++ b/package.xml @@ -52,6 +52,7 @@ + diff --git a/src/php/ext/grpc/php_grpc.h b/src/php/ext/grpc/php_grpc.h index 13083b0bc71..51f9dd5fe6d 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 @@ extern zend_module_entry grpc_module_entry; #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 00000000000..993ef2de274 --- /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/templates/src/php/ext/grpc/version.h.template b/templates/src/php/ext/grpc/version.h.template new file mode 100644 index 00000000000..828ea69296c --- /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 */ From 94d75888c9f237dedb559a5e43c6fb4a2b9e137d Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Wed, 17 May 2017 14:58:02 -0700 Subject: [PATCH 35/38] PHP: fix pecl extension after cc files are added --- config.m4 | 9 +++++---- templates/config.m4.template | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/config.m4 b/config.m4 index cc050ed9b34..7b5cf952222 100644 --- a/config.m4 +++ b/config.m4 @@ -13,9 +13,11 @@ if test "$PHP_GRPC" != "no"; then 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) @@ -688,9 +690,8 @@ if test "$PHP_GRPC" != "no"; then 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 \ + , $ext_shared, , -fvisibility=hidden \ + -DOPENSSL_NO_ASM -D_GNU_SOURCE -DWIN32_LEAN_AND_MEAN \ -D_HAS_EXCEPTIONS=0 -DNOMINMAX) PHP_ADD_BUILD_DIR($ext_builddir/src/php/ext/grpc) diff --git a/templates/config.m4.template b/templates/config.m4.template index 13ff7389e68..8bcbb47319a 100644 --- a/templates/config.m4.template +++ b/templates/config.m4.template @@ -15,9 +15,11 @@ 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) @@ -43,9 +45,8 @@ % 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 ${"\\"} + , $ext_shared, , -fvisibility=hidden ${"\\"} + -DOPENSSL_NO_ASM -D_GNU_SOURCE -DWIN32_LEAN_AND_MEAN ${"\\"} -D_HAS_EXCEPTIONS=0 -DNOMINMAX) PHP_ADD_BUILD_DIR($ext_builddir/src/php/ext/grpc) From 67cda0a701ff5698c54336df464d12ff9bd12b08 Mon Sep 17 00:00:00 2001 From: yang-g Date: Wed, 17 May 2017 17:23:47 -0700 Subject: [PATCH 36/38] Unref pending events under cq lock --- src/core/lib/surface/completion_queue.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/core/lib/surface/completion_queue.c b/src/core/lib/surface/completion_queue.c index b0a4b1fbcca..de905941c14 100644 --- a/src/core/lib/surface/completion_queue.c +++ b/src/core/lib/surface/completion_queue.c @@ -582,9 +582,9 @@ static void cq_end_op_for_next(grpc_exec_ctx *exec_ctx, 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); From 646677216d5195768453c65ca291250dd5fb5161 Mon Sep 17 00:00:00 2001 From: Stanley Cheung Date: Wed, 17 May 2017 23:15:45 -0700 Subject: [PATCH 37/38] Fixed missed conflicts - use constants.logVerbosity instead --- src/node/src/server.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/node/src/server.js b/src/node/src/server.js index 75426a62c17..1d9cc7d2c18 100644 --- a/src/node/src/server.js +++ b/src/node/src/server.js @@ -782,7 +782,7 @@ Server.prototype.addService = function(service, implementation) { }; var logAddProtoServiceDeprecationOnce = _.once(function() { - common.log(grpc.logVerbosity.INFO, + common.log(constants.logVerbosity.INFO, 'Server#addProtoService is deprecated. Use addService instead'); }); From 9883e0b4d2556ba224664411d248e06cd29c30cf Mon Sep 17 00:00:00 2001 From: Jan Tattermusch Date: Thu, 18 May 2017 11:00:27 +0200 Subject: [PATCH 38/38] fix run_tests.py on Windows and for non-C langs --- tools/run_tests/run_tests.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tools/run_tests/run_tests.py b/tools/run_tests/run_tests.py index 830c356d913..568774cecea 100755 --- a/tools/run_tests/run_tests.py +++ b/tools/run_tests/run_tests.py @@ -1440,6 +1440,9 @@ def _has_epollexclusive(): 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)