1# Moving gRPC core to C++ 2 3Originally written by ctiller, markdroth, and vjpai in October 2017 4 5Revised by veblush in October 2019 6 7## Background and Goal 8 9gRPC core was originally written in C89 for several reasons 10(possibility of kernel integration, ease of wrapping, compiler 11support, etc). Over time, this was changed to C99 as all relevant 12compilers in active use came to support C99 effectively. 13 14gRPC started allowing to use C++ with a couple of exceptions not to 15have 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 18Finally 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 20Throughout all of these transitions, the public header files are committed to remain in C89. 21 22The goal now is to make the gRPC core implementation true idiomatic 23C++ 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, 64ByteBuffer, ...) 65- The C++ API implementation might directly start using 66`grpc_transport_stream_op_batch` rather than the core surface `grpc_op`. 67