Merge branch 'master' of github.com:grpc/grpc into simplify_compression_interop

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|