From cd42eb0a8ea21e3002f4377b24d5f54ae7791833 Mon Sep 17 00:00:00 2001 From: Vijay Pai Date: Fri, 6 Oct 2017 15:26:00 -0700 Subject: [PATCH 1/2] Doc with plans for converting core to C++ --- doc/core/moving-to-c++.md | 54 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 doc/core/moving-to-c++.md diff --git a/doc/core/moving-to-c++.md b/doc/core/moving-to-c++.md new file mode 100644 index 00000000000..33c3cfa0e66 --- /dev/null +++ b/doc/core/moving-to-c++.md @@ -0,0 +1,54 @@ +# Moving gRPC core to C++ + +October 2017 + +ctiller, markdroth, vjpai + +## Background and Goal + +gRPC core was originally written in C89 for several reasons (possibility of +kernel integration, ease of wrapping, compiler support, etc). Over time, this +was changed to C99 as all relevant compilers in active use came to support C99 +effectively. Now, gRPC core is C++ (although the code is still idiomatically C +code) with C linkage for public functions. Throughout all of these transitions, +the public header files are committed to remain in C89. + +The goal now is to make gRPC core true idiomatic C++ compatible with +[Google's C++ style guide](https://google.github.io/styleguide/cppguide.html). + +## Constraints + +- No use of standard library + - Standard library makes wrapping difficult/impossible and also reduces platform portability + - This takes precedence over using C++ style guide +- But lambdas are ok +- As are third-party libraries that meet our build requirements (such as many parts of abseil) +- There will be some C++ features that don't work + - `new` and `delete` + - pure virtual functions are not allowed because the message that prints out "Pure Virtual Function called" is part of the standard library + - Make a `#define GRPC_ABSTRACT {GPR_ASSERT(false);}` instead of `= 0;` +- The sanity for making sure that we don't depend on libstdc++ is that at least some tests should explicitly not include it + - Most tests can migrate to use gtest + - There are tremendous # of code paths that can now be exposed to unit tests because of the use of gtest and C++ + - But at least some tests should not use gtest + + +## Roadmap + +- What should be the phases of getting code converted to idiomatic C++ + - Opportunistically do leaf code that other parts don't depend on + - Spend a little time deciding how to do non-leaf stuff that isn't central or polymorphic (e.g., timer, call combiner) + - For big central or polymorphic interfaces, actually do an API review (for things like transport, filter API, endpoint, closure, exec_ctx, ...) . + - Core internal changes don't need a gRFC, but core surface changes do + - But an API review should include at least a PR with the header change and tests to use it before it gets used more broadly + - iomgr polling for POSIX is a gray area whether it's a leaf or central +- What is the schedule? + - In Q4 2017, if some stuff happens opportunistically, great; otherwise ¯\\\_(ツ)\_/¯ + - More updates as team time becomes available and committed to this project + +## Implications for C++ API and wrapped languages + +- For C++ structs, switch to `using` when possible (e.g., Slice, ByteBuffer, ...) +- Can we get wrapped languages to a point where we can statically link C++? This will take a year in probability but that would allow the use of `std::` + - Are there other environments that don't support std library, like maybe Android NDK? + - Probably, that might push things out to 18 months From d137066be8c9527b5cea36132915619cc61cfc6d Mon Sep 17 00:00:00 2001 From: Vijay Pai Date: Mon, 9 Oct 2017 10:15:37 -0700 Subject: [PATCH 2/2] Add some details --- doc/core/moving-to-c++.md | 24 +++++++++++++++--------- tools/doxygen/Doxyfile.core | 1 + tools/doxygen/Doxyfile.core.internal | 1 + 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/doc/core/moving-to-c++.md b/doc/core/moving-to-c++.md index 33c3cfa0e66..4c745b38a90 100644 --- a/doc/core/moving-to-c++.md +++ b/doc/core/moving-to-c++.md @@ -6,14 +6,17 @@ ctiller, markdroth, vjpai ## Background and Goal -gRPC core was originally written in C89 for several reasons (possibility of -kernel integration, ease of wrapping, compiler support, etc). Over time, this -was changed to C99 as all relevant compilers in active use came to support C99 -effectively. Now, gRPC core is C++ (although the code is still idiomatically C -code) with C linkage for public functions. Throughout all of these transitions, -the public header files are committed to remain in C89. - -The goal now is to make gRPC core true idiomatic C++ compatible with +gRPC core was originally written in C89 for several reasons +(possibility of kernel integration, ease of wrapping, compiler +support, etc). Over time, this was changed to C99 as all relevant +compilers in active use came to support C99 effectively. +[Now, gRPC core is C++](https://github.com/grpc/proposal/blob/master/L6-allow-c%2B%2B-in-grpc-core.md) +(although the code is still idiomatically C code) with C linkage for +public functions. Throughout all of these transitions, the public +header files are committed to remain in C89. + +The goal now is to make the gRPC core implementation true idiomatic +C++ compatible with [Google's C++ style guide](https://google.github.io/styleguide/cppguide.html). ## Constraints @@ -48,7 +51,10 @@ The goal now is to make gRPC core true idiomatic C++ compatible with ## Implications for C++ API and wrapped languages -- For C++ structs, switch to `using` when possible (e.g., Slice, ByteBuffer, ...) +- For C++ structs, switch to `using` when possible (e.g., Slice, +ByteBuffer, ...) +- The C++ API implementation might directly start using +`grpc_transport_stream_op_batch` rather than the core surface `grpc_op`. - Can we get wrapped languages to a point where we can statically link C++? This will take a year in probability but that would allow the use of `std::` - Are there other environments that don't support std library, like maybe Android NDK? - Probably, that might push things out to 18 months diff --git a/tools/doxygen/Doxyfile.core b/tools/doxygen/Doxyfile.core index b8514fe3114..c8fd2ee48b2 100644 --- a/tools/doxygen/Doxyfile.core +++ b/tools/doxygen/Doxyfile.core @@ -772,6 +772,7 @@ doc/connection-backoff-interop-test-description.md \ doc/connection-backoff.md \ doc/connectivity-semantics-and-api.md \ doc/core/grpc-error.md \ +doc/core/moving-to-c++.md \ doc/core/pending_api_cleanups.md \ doc/cpp-style-guide.md \ doc/environment_variables.md \ diff --git a/tools/doxygen/Doxyfile.core.internal b/tools/doxygen/Doxyfile.core.internal index ee593e3ea09..3047778737b 100644 --- a/tools/doxygen/Doxyfile.core.internal +++ b/tools/doxygen/Doxyfile.core.internal @@ -772,6 +772,7 @@ doc/connection-backoff-interop-test-description.md \ doc/connection-backoff.md \ doc/connectivity-semantics-and-api.md \ doc/core/grpc-error.md \ +doc/core/moving-to-c++.md \ doc/core/pending_api_cleanups.md \ doc/cpp-style-guide.md \ doc/environment_variables.md \