diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/c-style-guide.md | 2 | ||||
-rw-r--r-- | doc/command_line_tool.md | 77 | ||||
-rw-r--r-- | doc/cpp-style-guide.md | 85 | ||||
-rw-r--r-- | doc/statuscodes.md | 2 |
4 files changed, 165 insertions, 1 deletions
diff --git a/doc/c-style-guide.md b/doc/c-style-guide.md index 87de8892dd..d6f9bbd7d4 100644 --- a/doc/c-style-guide.md +++ b/doc/c-style-guide.md @@ -11,7 +11,7 @@ General - 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] (../tools/distrib/clang_format_code.sh). Header Files ------------ diff --git a/doc/command_line_tool.md b/doc/command_line_tool.md new file mode 100644 index 0000000000..89a70548b8 --- /dev/null +++ b/doc/command_line_tool.md @@ -0,0 +1,77 @@ +# gRPC command line tool + +## Overview + +This document describes the command line tool that comes with gRPC repository. It is desireable to have command line +tools written in other languages to roughly follow the same syntax and flags. + +At this point, the tool needs to be built from source, and it should be moved out to grpc-tools repository as a stand +alone application once it is mature enough. + +## Core functionality + +The command line tool can do the following things: + +- Send unary rpc. +- Attach metadata and display received metadata. +- Handle common authentication to server. +- Find the request/response types from a given proto file. +- Read proto request in text form. +- Read request in wire form (for protobuf messages, this means serialized binary form). +- Display proto response in text form. +- Write response in wire form to a file. + +The command line tool should support the following things: + +- List server services and methods through server reflection. +- Infer request/response types from server reflection result. +- Fine-grained auth control (such as, use this oauth token to talk to the server). +- Send streaming rpc. + +## Code location + +To use the tool, you need to get the grpc repository and in the grpc directory execute + +``` +$ make grpc_cli +``` + +The main file can be found at +https://github.com/grpc/grpc/blob/master/test/cpp/util/grpc_cli.cc + +## Usage + +### Basic usage + +Send a rpc to a helloworld server at `localhost:50051`: + +``` +$ bins/opt/grpc_cli call localhost:50051 SayHello examples/protos/helloworld.proto \ + "name: 'world'" --enable_ssl=false +``` + +On success, the tool will print out + +``` +Rpc succeeded with OK status +Response: + message: "Hello world" +``` + +The `localhost:50051` part indicates the server you are connecting to. `SayHello` is (part of) the +gRPC method string. Then there is the path to the proto file containing the service definition, +if it is not under current directory, you can use `--proto_path` to specify a new search root. +`"name: 'world'"` is the text format of the request proto message. +We are not using ssl here by `--enable_ssl=false`. For information on more +flags, look at the comments of `grpc_cli.cc`. + +### Send non-proto rpc + +For using gRPC with protocols other than probobuf, you will need the exact method name string +and a file containing the raw bytes to be sent on the wire + +``` +$ bins/opt/grpc_cli call localhost:50051 /helloworld.Greeter/SayHello --input_binary_file=input.bin \ + --output_binary_file=output.bin +``` +On success, you will need to read or decode the response from the `output.bin` file. diff --git a/doc/cpp-style-guide.md b/doc/cpp-style-guide.md new file mode 100644 index 0000000000..9408c4abd6 --- /dev/null +++ b/doc/cpp-style-guide.md @@ -0,0 +1,85 @@ +GRPC C++ STYLE GUIDE +===================== + +Background +---------- + +Here we document style rules for C++ usage in the gRPC C++ bindings +and tests. + +General +------- + +- The majority of gRPC's C++ requirements are drawn from the [Google C++ style +guide] (https://google.github.io/styleguide/cppguide.html) + - However, gRPC has some additional requirements to maintain + [portability] (#portability) +- 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). + +<a name="portability"></a> +Portability Restrictions +------------------- + +gRPC supports a large number of compilers, ranging from those that are +missing many key C++11 features to those that have quite detailed +analysis. As a result, gRPC compiles with a high level of warnings and +treat all warnings as errors. gRPC also forbids the use of some common +C++11 constructs. Here are some guidelines, to be extended as needed: +- Do not use range-based for. Expressions of the form + ```c + for (auto& i: vec) { + // code + } + ``` + + are not allowed and should be replaced with code such as + ```c + for (auto it = vec.begin; it != vec.end(); it++) { + auto& i = *it; + // code + } + ``` + +- Do not use lambda of any kind (no capture, explicit capture, or +default capture). Other C++ functional features such as +`std::function` or `std::bind` are allowed +- Do not use brace-list initializers. +- Do not compare a pointer to `nullptr` . This is because gcc 4.4 + does not support `nullptr` directly and gRPC implements a subset of + its features in [include/grpc++/impl/codegen/config.h] + (../include/grpc++/impl/codegen/config.h). Instead, pointers should + be checked for validity using their implicit conversion to `bool`. + In other words, use `if (p)` rather than `if (p != nullptr)` +- Do not use `final` or `override` as these are not supported by some + compilers. Instead use `GRPC_FINAL` and `GRPC_OVERRIDE` . These + compile down to the traditional C++ forms for compilers that support + them but are just elided if the compiler does not support those features. +- In the [include] (../../../tree/master/include/grpc++) and [src] + (../../../tree/master/src/cpp) directory trees, you should also not + use certain STL objects like `std::mutex`, `std::lock_guard`, + `std::unique_lock`, `std::nullptr`, `std::thread` . Instead, use + `grpc::mutex`, `grpc::lock_guard`, etc., which are gRPC + implementations of the prominent features of these objects that are + not always available. You can use the `std` versions of those in [test] + (../../../tree/master/test/cpp) +- Similarly, in the same directories, do not use `std::chrono` unless + it is guarded by `#ifndef GRPC_CXX0X_NO_CHRONO` . For platforms that + lack`std::chrono,` there is a C-language timer called gpr_timespec that can + be used instead. +- `std::unique_ptr` must be used with extreme care in any kind of + collection. For example `vector<std::unique_ptr>` does not work in + gcc 4.4 if the vector is constructed to its full size at + initialization but does work if elements are added to the vector + using functions like `push_back`. `map` and other pair-based + collections do not work with `unique_ptr` under gcc 4.4. The issue + is that many of these collection implementations assume a copy + constructor + to be available. +- Don't use `std::this_thread` . Use `gpr_sleep_until` for sleeping a thread. +- [Some adjacent character combinations cause problems] + (https://en.wikipedia.org/wiki/Digraphs_and_trigraphs#C). If declaring a + template against some class relative to the global namespace, + `<::name` will be non-portable. Separate the `<` from the `:` and use `< ::name`. diff --git a/doc/statuscodes.md b/doc/statuscodes.md index 84258c8d12..c918f9ed9a 100644 --- a/doc/statuscodes.md +++ b/doc/statuscodes.md @@ -21,6 +21,8 @@ Only a subset of the pre-defined status codes are generated by the gRPC librarie | Flow-control protocol violation | INTERNAL | Both | | Error parsing returned status | UNKNOWN | Client | | Incorrect Auth metadata ( Credentials failed to get metadata, Incompatible credentials set on channel and call, Invalid host set in `:authority` metadata, etc.) | UNAUTHENTICATED | Both | +| Request cardinality violation (method requires exactly one request but client sent some other number of requests) | UNIMPLEMENTED | Server| +| Response cardinality violation (method requires exactly one response but server sent some other number of responses) | UNIMPLEMENTED | Client| | Error parsing response proto | INTERNAL | Client| | Error parsing request proto | INTERNAL | Server| |