| 1 |
# Moving gRPC core to C++ |
| 2 |
|
| 3 |
Originally written by ctiller, markdroth, and vjpai in October 2017 |
| 4 |
|
| 5 |
Revised by veblush in October 2019 |
| 6 |
|
| 7 |
## Background and Goal |
| 8 |
|
| 9 |
gRPC core was originally written in C89 for several reasons |
| 10 |
(possibility of kernel integration, ease of wrapping, compiler |
| 11 |
support, etc). Over time, this was changed to C99 as all relevant |
| 12 |
compilers in active use came to support C99 effectively. |
| 13 |
|
| 14 |
gRPC started allowing to use C++ with a couple of exceptions not to |
| 15 |
have C++ library linked such as `libstdc++.so`. |
| 16 |
(For more detail, see the [proposal](https://github.com/grpc/proposal/blob/master/L6-core-allow-cpp.md)) |
| 17 |
|
| 18 |
Finally gRPC became ready to use full C++11 with the standard library by the [proposal](https://github.com[/grpc/proposal/blob/master/L59-core-allow-cppstdlib.md). |
| 19 |
|
| 20 |
Throughout all of these transitions, the public header files are committed to remain in C89. |
| 21 |
|
| 22 |
The goal now is to make the gRPC core implementation true idiomatic |
| 23 |
C++ compatible with |
| 24 |
[Google's C++ style guide](https://google.github.io/styleguide/cppguide.html). |
| 25 |
|
| 26 |
## Constraints |
| 27 |
|
| 28 |
- Most of features available in C++11 are allowed to use but there are some exceptions |
| 29 |
because gRPC should support old systems. |
| 30 |
- Should be built with gcc 4.8, clang 3.3, and Visual C++ 2015. |
| 31 |
- Should be run on Linux system with libstdc++ 6.0.9 to support |
| 32 |
[manylinux1](https://www.python.org/dev/peps/pep-0513). |
| 33 |
- This would limit us not to use modern C++11 standard library such as `filesystem`. |
| 34 |
You can easily see whether PR is free from this issue by checking the result of |
| 35 |
`Artifact Build Linux` test. |
| 36 |
- `thread_local` is not allowed to use on Apple's products because their old OSes |
| 37 |
(e.g. ios < 9.0) don't support `thread_local`. Please use `GPR_TLS_DECL` instead. |
| 38 |
- gRPC main libraries (grpc, grpc+++, and plugins) cannot use following C++ libraries: |
| 39 |
(Test and example codes are relatively free from this constraints) |
| 40 |
- `<thread>`. Use `grpc_core::Thread`. |
| 41 |
- `<condition_variable>`. Use `grpc_core::CondVar`. |
| 42 |
- `<mutex>`. Use `grpc_core::Mutex`, `grpc_core::MutexLock`, and `grpc_core::ReleasableMutexLock`. |
| 43 |
- `<future>` |
| 44 |
- `<ratio>` |
| 45 |
- `<system_error>` |
| 46 |
- `<filesystem>` |
| 47 |
|
| 48 |
## Roadmap |
| 49 |
|
| 50 |
- What should be the phases of getting code converted to idiomatic C++ |
| 51 |
- Opportunistically do leaf code that other parts don't depend on |
| 52 |
- Spend a little time deciding how to do non-leaf stuff that isn't central or polymorphic (e.g., timer, call combiner) |
| 53 |
- For big central or polymorphic interfaces, actually do an API review (for things like transport, filter API, endpoint, closure, exec_ctx, ...) . |
| 54 |
- Core internal changes don't need a gRFC, but core surface changes do |
| 55 |
- 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 |
| 56 |
- iomgr polling for POSIX is a gray area whether it's a leaf or central |
| 57 |
- What is the schedule? |
| 58 |
- In Q4 2017, if some stuff happens opportunistically, great; otherwise ¯\\\_(ツ)\_/¯ |
| 59 |
- More updates as team time becomes available and committed to this project |
| 60 |
|
| 61 |
## Implications for C++ API and wrapped languages |
| 62 |
|
| 63 |
- For C++ structs, switch to `using` when possible (e.g., Slice, |
| 64 |
ByteBuffer, ...) |
| 65 |
- The C++ API implementation might directly start using |
| 66 |
`grpc_transport_stream_op_batch` rather than the core surface `grpc_op`. |