gPRC學習筆記

gPRC學習筆記

• gPRC基礎教程。
• gPRC官方文檔。
• protobuf 3.0的簡易教程。

什麼是RPC

• RPC(remote procedure call) -- 遠程過程調用(相對於本地調用的概念)。
  • 本地調用
    • ex:本地的函數調用
    • 在函數調用的時候,通常會通過幾個步驟
      
    • 返回地址入棧
    • 參數入棧
    • 提高堆棧空間
    • 函數參數的複製
    • 執行函數調用
    • 清空堆棧
  • 爲何須要RPC?
    • ex:兩臺機器 一臺機器想調用另外一臺機器的函數執行某個功能
    • 因爲是兩個不一樣的進程 咱們沒法使用函數指針來調用該函數
    • 而只能經過網絡請求來調用的具體函數
• 那麼如何知道須要具體調用的函數呢?（關聯）
  • 兩臺機器之間能夠各自維護一個關聯式容器 從而找到要調用的函數
• 一次完整的RPC調用流程
  1. client 以本地的方式進行的調用服務
  2. client stub接收到調用後負責將方法 參數等組裝成可以進行網絡傳輸的消息體
  3. cleint stub找到服務端的地址 並將消息發送給server stub
  4. server stub收到消息後進行解碼
  5. server stub根據解碼結果調用本地的服務
  6. 本地服務執行結果並將結果返回後給server stub
  7. server stub將返回結果打包成消息併發送至消費方
  8. client stub接受到消息
  9. client獲得返回結果

爲何須要proto buffer

• 在許多高級語言中, 咱們都是使用類的方式對數據進行封裝, 而利用網絡傳遞數據只能以二進制的方式進行傳輸, 所以咱們須要將數據轉化爲二進制數據從而在網絡上進行傳播過程稱爲序列化, 再將接收到的數據從二進制轉化爲對應的數據類型, 稱爲反序列化。
• proto buffer是Google使用的一個開源軟件，數據打包小，數據傳輸快。

proto buffer基礎教程

• proto buffer協議的格式
  • .proto文件
  • package name;//能夠理解爲c++中的名稱空間
  • message dataname; //message能夠理解爲c++中的class 或者struct
  • requried type name = 1 //消息的接收方和發送發都必須提供required修飾字段的值
  • opitional type name = 2 //可選擇的
  • =1 =2 表示惟一標記的tag(maybe傳輸的過程當中傳遞的是tag 讓後經過tag找到對應的數據)
• protobuf入門教程。
  • 編譯.proto文件，protoc addressbook.proto --cpp_out=./;
  • protoc 是protobuf自帶的編譯工具，將.proto文件生成指定的類。
  • -cpp_out：指定輸出特定的語言和路徑。
  • 經過protoc工具編譯.proto文件時，編譯器將生成所選擇語言的代碼，這些代碼能夠操做在.proto文件中定義的消息類型，包括獲取、設置字段值，將消息序列化到一個輸出流中，以及從一個輸入流中解析消息。
  • 對C++來講，編譯器會爲每一個.proto文件生成一個.h文件和一個.cc文件，.proto文件中的每個消息有一個對應的類。
  • pkg-config –cflags protobuf：列出指定共享庫的預處理和編譯flags，在終端中執行。
  • -I/path/to/protobuf/include -L/path/to/protobuf/lib -lprotobuf -lpthread --- 編譯protoc生成的cc和h文件。
• Protocol Buffers C++入門教程.
  • protobuf（Protocol Buffers ）是Google的開源項目，是Google的中立於語言、平臺，可擴展的用於序列化結構化數據的解決方案。
  • 簡單的說，protobuf是用來對數據進行序列化和反序列化。

數據的序列化和反序列化

• 序列化 (Serialization)：將數據結構或對象轉換成二進制串的過程。
• 反序列化（Deserialization）：將在序列化過程當中所生成的二進制串轉換成數據結構或者對象的過程。
• JSON簡介: JSON（JavaScript Object Notation）是一種輕量級的數據交換格式。它基於ECMAScript的一個子集，採用徹底獨立於語言的文本格式來存儲和表示數據，這些特性使JSON成爲理想的數據交換語言，易於人閱讀和編寫，同時也易於機器解析和生成，通常用於網絡傳輸。
• JSON的語法規則：
  • json語法是JavaScript對象表示語法的子集，數據在鍵值中；
  • 數據由逗號分隔；
  • 花括號保存對象；
  • 花括號保存數組；

  {
      "ID":"312822199204085698",
      "gender":0,
      "major":"math",
      "name":18
  }

• JSON支持的類型有:
  • 數字(整數或浮點數)；
  • 字符串(在雙引號中)；
  • 邏輯值(true或false);
  • 數組(在方括號中)；
  • 對象(在花括號中)；
• 當網絡中不一樣主機進行數據傳輸時，咱們就能夠採用JSON進行傳輸。
• 將現有的數據對象轉換爲JSON字符串就是對對象的序列化操做，將接收到的JSON字符串轉換爲咱們須要的對象，就是反序列化操做。
• XML(Extensive Markup Language)，可擴展標記語言，用結構化的方式來表示數據，和JSON同樣，都是一種數據交換格式。
  • C++能夠對象能夠序列化爲XML，用於網絡傳輸或存儲。
  • XML具備統一的標準、可移植性高等優勢，但由於文件格式複雜，致使格式化數據較大，傳輸佔用帶寬大，其在序列化和反序列化場景中，沒有JSON常見。
• Google Protocal Buffers是Google內部使用得而數據編碼方式，旨在用來代替XML進行數據交換，可用於數據序列化與反序列化。
  • 高效；
  • 語言中立(C++, Java, Python等)。
  • 可擴展。
• Boost Serialization能夠差U年間或重建程序中的等效結構，並保存爲二進制數據、文本數據、JSON/XML或者用戶自定義的其餘文件，該庫的有點有:
  • 代碼可移植性(實現僅依賴於ANSI C++)。
  • 深度指針保存與恢復。
  • 能夠序列化STL容器和其餘經常使用模板庫。
  • 數據可移植。
  • 能夠序列化STL容器和其餘經常使用模板庫。
  • 數據可移植。
  • 非入侵性。
• XML產生的數據文件較大，不多使用。MFC和.NET框架的方法適用範圍很窄，只適用於Windows下，且.NET框架方法須要.NET的運行環境，可是兩者結合Visual Studio IDE使用最爲方便。Google Protocol Buffers效率較高，可是數據對象必須預先定義，並使用protoc編譯，適合要求效率，容許自定義類型的內部場合使用。Boost.Serialization使用靈活簡單，並且支持標準C++容器。
• protobuf相對而言效率應該是最高的，不論是安裝效率仍是使用效率，protobuf都很高效，並且protobuf不只用於C++序列化，還可用於Java和Python的序列化，使用範圍很廣。
• protobuf數據類型: protobuf屬於輕量級的, 所以不能支持太多的數據類型，sint32使用可變長編碼方式，有符號的整型值，負數編碼時比一般的int32高效。
• protobuf使用的通常步驟:
  • 定義proto文件，文件的內容就是定義咱們須要存儲或者傳輸的數據結構，也就是定義咱們本身餓數據存儲或者傳輸的協議。
  • 編譯安裝protocol buffer編譯器來編譯自定義的.proto文件，用於生成.pb.h文件(proto文件中自定義類的頭文件)和.pb.cc(proto文件中自定義的實現文件)。
  • 使用protocol buffer的C++ API來讀寫消息。
• 定義proto文件就是定義本身的數據存儲或者傳輸的協議格式。

package tutotial;   // .proto文件以一個package聲明開始。這個聲明是爲了防止不一樣項目之間的命名衝突。
message Student{ // message 一個消息就是某些類型的字段的集合，能夠嵌套使用其餘的消息類型。
    requried uint64 id = 1;  // requried 是必須提供的字段，否者對應的消息就會被認爲是未初始化的。
    requried string name = 2;
    opitional string email = 3; // 字段值指定與否均可以, 若是沒有指定一個optional的字段值，他會使用默認值，若是沒有默認值，系統默認值會使用: 數據類型的默認值爲0，string的默認值爲空字符串，bool的默認值爲false,對嵌套消息來講，其默認值老是消息的默認實例或者原型。

// 關於標識: '=1'的標誌指出了該字段在二進制編碼中使用的惟一"標識(tag)"；
// 標識號1~15編碼所須要的字節數比更大的標識號使用的字節數要少1個，因此，若是你想尋求優化，能夠爲常用或重複的項採用1~15的標識(tag)，其餘常用的optional項採用>=16的標識(tag)。
// 在重複的字段中，每一項都要求重編碼標識(tag number)，因此重複的字段特別適用於這種優化。
    enum PhoneType {
        MOBILE = 0;
        HOME = 1;
    }

    message PhoneNumber {
        requried string number = 1;
        opitional PhoneType type = 2 [default = HOME];
    }
    repeated PhoneNumber phone = 4; //字段會重複N次（N能夠爲0）。重複的值的順序將被保存在protocol buffer中。你只要將重複的字段視爲動態大小的數組就能夠了。
}

• equired是永久性的：在把一個字段標識爲required的時候，你應該特別當心。若是在某些狀況下你不想寫入或者發送一個required的字段，那麼將該字段更改成optional可能會遇到問題——舊版本的讀者（譯者注：即讀取、解析消息的一方）會認爲不含該字段的消息（message）是不完整的，從而有可能會拒絕解析。在這種狀況下，你應該考慮編寫特別針對於應用程序的、自定義的消息校驗函數。Google的一些工程師得出了一個結論：使用required弊多於利；他們更願意使用optional和repeated而不是required。固然，這個觀點並不具備廣泛性。
• 特別注意:
  • protocol buffers和麪向對象的設計 protocol buffer類一般只是純粹的數據存儲器（就像C++中的結構體同樣）；它們在對象模型中並非一等公民。若是你想向生成的類中添加更豐富的行爲，最好的方法就是在應用程序中對它進行封裝。若是你無權控制.proto文件的設計的話，封裝protocol buffers也是一個好主意（例如，你從另外一個項目中重用一個.proto文件）。在那種狀況下，你能夠用封裝類來設計接口，以更好地適應你的應用程序的特定環境：隱藏一些數據和方法，暴露一些便於使用的函數，等等。可是你絕對不要經過繼承生成的類來添加行爲。這樣作的話，會破壞其內部機制，而且不是一個好的面向對象的實踐。
• 編譯不過緣由是protobuf的鏈接庫默認安裝路徑是/usr/local/lib，而/usr/local/lib 不在常見Linux系統的LD_LIBRARY_PATH連接庫路徑這個環境變量裏，因此就找不到該lib。LD_LIBRARY_PATH是Linux環境變量名，該環境變量主要用於指定查找共享庫（動態連接庫）。因此，解決辦法就是修改環境變量LD_LIBRARY_PATH的值。
  • g++ -o protobufTest.out test.cpp student.pb.cc -I/usr/local/include -L/usr/local/lib -lprotobuf -pthread, 命令行編譯生成的文件;
• Protocol Buffers的做用毫不僅僅是簡單的數據存取以及序列化。
• protocol消息類所提供的一個關鍵特性就是反射。你不須要編寫針對一個特殊的消息（message）類型的代碼，就能夠遍歷一個消息的字段，並操縱它們的值，就像XML和JSON同樣。
• 「反射」的一個更高級的用法可能就是能夠找出兩個相同類型的消息之間的區別，或者開發某種「協議消息的正則表達式」，利用正則表達式，你能夠對某種消息內容進行匹配。

爲何使用gRPC

• 有了 gRPC， 咱們能夠一次性的在一個 .proto 文件中定義服務並使用任何支持它的語言去實現客戶端和服務器，反過來，它們能夠在各類環境中，從Google的服務器到你本身的平板電腦- gRPC 幫你解決了不一樣語言間通訊的複雜性以及環境的不一樣.使用 protocol buffers 還能得到其餘好處，包括高效的序列號，簡單的 IDL 以及容易進行接口更新。

官方的入門教程

gRPC Basics: C++

This tutorial provides a basic C++ programmer's introduction to working with
gRPC. By walking through this example you'll learn how to:

• Define a service in a .proto file.
• Generate server and client code using the protocol buffer compiler.
• Use the C++ gRPC API to write a simple client and server for your service.

It assumes that you are familiar with
protocol buffers.
Note that the example in this tutorial uses the proto3 version of the protocol
buffers language, which is currently in alpha release: you can find out more in
the proto3 language guide
and see the release notes for the
new version in the protocol buffers Github repository.

Why use gRPC?

Our example is a simple route mapping application that lets clients get
information about features on their route, create a summary of their route, and
exchange route information such as traffic updates with the server and other
clients.

With gRPC we can define our service once in a .proto file and implement clients
and servers in any of gRPC's supported languages, which in turn can be run in
environments ranging from servers inside Google to your own tablet - all the
complexity of communication between different languages and environments is
handled for you by gRPC. We also get all the advantages of working with protocol
buffers, including efficient serialization, a simple IDL, and easy interface
updating.

Example code and setup

The example code for our tutorial is in examples/cpp/route_guide.
You also should have the relevant tools installed to generate the server and
client interface code - if you don't already, follow the setup instructions in
BUILDING.md.

Defining the service

Our first step is to define the gRPC service and the method request and
response types using
protocol buffers.
You can see the complete .proto file in
examples/protos/route_guide.proto.

To define a service, you specify a named service in your .proto file:

service RouteGuide {
   ...
}

Then you define rpc methods inside your service definition, specifying their
request and response types. gRPC lets you define four kinds of service method,
all of which are used in the RouteGuide service:

• A simple RPC where the client sends a request to the server using the stub
  and waits for a response to come back, just like a normal function call.

// Obtains the feature at a given position.
   rpc GetFeature(Point) returns (Feature) {}

• A server-side streaming RPC where the client sends a request to the server
  and gets a stream to read a sequence of messages back. The client reads from
  the returned stream until there are no more messages. As you can see in our
  example, you specify a server-side streaming method by placing the stream
  keyword before the response type.

// Obtains the Features available within the given Rectangle.  Results are
  // streamed rather than returned at once (e.g. in a response message with a
  // repeated field), as the rectangle may cover a large area and contain a
  // huge number of features.
  rpc ListFeatures(Rectangle) returns (stream Feature) {}

• A client-side streaming RPC where the client writes a sequence of messages
  and sends them to the server, again using a provided stream. Once the client
  has finished writing the messages, it waits for the server to read them all
  and return its response. You specify a client-side streaming method by placing
  the stream keyword before the request type.

// Accepts a stream of Points on a route being traversed, returning a
  // RouteSummary when traversal is completed.
  rpc RecordRoute(stream Point) returns (RouteSummary) {}

• A bidirectional streaming RPC where both sides send a sequence of messages
  using a read-write stream. The two streams operate independently, so clients
  and servers can read and write in whatever order they like: for example, the
  server could wait to receive all the client messages before writing its
  responses, or it could alternately read a message then write a message, or
  some other combination of reads and writes. The order of messages in each
  stream is preserved. You specify this type of method by placing the stream
  keyword before both the request and the response.

// Accepts a stream of RouteNotes sent while a route is being traversed,
  // while receiving other RouteNotes (e.g. from other users).
  rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}

Our .proto file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's
the Point message type:

// Points are represented as latitude-longitude pairs in the E7 representation
// (degrees multiplied by 10**7 and rounded to the nearest integer).
// Latitudes should be in the range +/- 90 degrees and longitude should be in
// the range +/- 180 degrees (inclusive).
message Point {
  int32 latitude = 1;
  int32 longitude = 2;
}

Generating client and server code

Next we need to generate the gRPC client and server interfaces from our .proto
service definition. We do this using the protocol buffer compiler protoc with
a special gRPC C++ plugin.

For simplicity, we've provided a Makefile that runs
protoc for you with the appropriate plugin, input, and output (if you want to
run this yourself, make sure you've installed protoc and followed the gRPC code
installation instructions first):

$ make route_guide.grpc.pb.cc route_guide.pb.cc

which actually runs:

$ protoc -I ../../protos --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_cpp_plugin` ../../protos/route_guide.proto
$ protoc -I ../../protos --cpp_out=. ../../protos/route_guide.proto

Running this command generates the following files in your current directory:

• route_guide.pb.h, the header which declares your generated message classes
• route_guide.pb.cc, which contains the implementation of your message classes
• route_guide.grpc.pb.h, the header which declares your generated service
  classes
• route_guide.grpc.pb.cc, which contains the implementation of your service
  classes

These contain:

• All the protocol buffer code to populate, serialize, and retrieve our request
  and response message types
• A class called RouteGuide that contains
  • a remote interface type (or stub) for clients to call with the methods
    defined in the RouteGuide service.
  • two abstract interfaces for servers to implement, also with the methods
    defined in the RouteGuide service.

Creating the server

First let's look at how we create a RouteGuide server. If you're only
interested in creating gRPC clients, you can skip this section and go straight
to Creating the client (though you might find it interesting
anyway!).

There are two parts to making our RouteGuide service do its job:

• Implementing the service interface generated from our service definition:
  doing the actual "work" of our service.
• Running a gRPC server to listen for requests from clients and return the
  service responses.

You can find our example RouteGuide server in
route_guide/route_guide_server.cc. Let's
take a closer look at how it works.

Implementing RouteGuide

As you can see, our server has a RouteGuideImpl class that implements the
generated RouteGuide::Service interface:

class RouteGuideImpl final : public RouteGuide::Service {
...
}

In this case we're implementing the synchronous version of RouteGuide, which
provides our default gRPC server behaviour. It's also possible to implement an
asynchronous interface, RouteGuide::AsyncService, which allows you to further
customize your server's threading behaviour, though we won't look at this in
this tutorial.

RouteGuideImpl implements all our service methods. Let's look at the simplest
type first, GetFeature, which just gets a Point from the client and returns
the corresponding feature information from its database in a Feature.

Status GetFeature(ServerContext* context, const Point* point,
                    Feature* feature) override {
    feature->set_name(GetFeatureName(*point, feature_list_));
    feature->mutable_location()->CopyFrom(*point);
    return Status::OK;
  }

The method is passed a context object for the RPC, the client's Point protocol
buffer request, and a Feature protocol buffer to fill in with the response
information. In the method we populate the Feature with the appropriate
information, and then return with an OK status to tell gRPC that we've
finished dealing with the RPC and that the Feature can be returned to the
client.

Now let's look at something a bit more complicated - a streaming RPC.
ListFeatures is a server-side streaming RPC, so we need to send back multiple
Features to our client.

Status ListFeatures(ServerContext* context, const Rectangle* rectangle,
                    ServerWriter<Feature>* writer) override {
  auto lo = rectangle->lo();
  auto hi = rectangle->hi();
  long left = std::min(lo.longitude(), hi.longitude());
  long right = std::max(lo.longitude(), hi.longitude());
  long top = std::max(lo.latitude(), hi.latitude());
  long bottom = std::min(lo.latitude(), hi.latitude());
  for (const Feature& f : feature_list_) {
    if (f.location().longitude() >= left &&
        f.location().longitude() <= right &&
        f.location().latitude() >= bottom &&
        f.location().latitude() <= top) {
      writer->Write(f);
    }
  }
  return Status::OK;
}

As you can see, instead of getting simple request and response objects in our
method parameters, this time we get a request object (the Rectangle in which
our client wants to find Features) and a special ServerWriter object. In the
method, we populate as many Feature objects as we need to return, writing them
to the ServerWriter using its Write() method. Finally, as in our simple RPC,
we return Status::OK to tell gRPC that we've finished writing responses.

If you look at the client-side streaming method RecordRoute you'll see it's
quite similar, except this time we get a ServerReader instead of a request
object and a single response. We use the ServerReaders Read() method to
repeatedly read in our client's requests to a request object (in this case a
Point) until there are no more messages: the server needs to check the return
value of Read() after each call. If true, the stream is still good and it
can continue reading; if false the message stream has ended.

while (stream->Read(&point)) {
  ...//process client input
}

Finally, let's look at our bidirectional streaming RPC RouteChat().

Status RouteChat(ServerContext* context,
                   ServerReaderWriter<RouteNote, RouteNote>* stream) override {
    std::vector<RouteNote> received_notes;
    RouteNote note;
    while (stream->Read(&note)) {
      for (const RouteNote& n : received_notes) {
        if (n.location().latitude() == note.location().latitude() &&
            n.location().longitude() == note.location().longitude()) {
          stream->Write(n);
        }
      }
      received_notes.push_back(note);
    }

    return Status::OK;
  }

This time we get a ServerReaderWriter that can be used to read and write
messages. The syntax for reading and writing here is exactly the same as for our
client-streaming and server-streaming methods. Although each side will always
get the other's messages in the order they were written, both the client and
server can read and write in any order — the streams operate completely
independently.

Starting the server

Once we've implemented all our methods, we also need to start up a gRPC server
so that clients can actually use our service. The following snippet shows how we
do this for our RouteGuide service:

void RunServer(const std::string& db_path) {
  std::string server_address("0.0.0.0:50051");
  RouteGuideImpl service(db_path);

  ServerBuilder builder;
  builder.AddListeningPort(server_address, grpc::InsecureServerCredentials());
  builder.RegisterService(&service);
  std::unique_ptr<Server> server(builder.BuildAndStart());
  std::cout << "Server listening on " << server_address << std::endl;
  server->Wait();
}

As you can see, we build and start our server using a ServerBuilder. To do this, we:

1. Create an instance of our service implementation class RouteGuideImpl.
2. Create an instance of the factory ServerBuilder class.
3. Specify the address and port we want to use to listen for client requests
   using the builder's AddListeningPort() method.
4. Register our service implementation with the builder.
5. Call BuildAndStart() on the builder to create and start an RPC server for
   our service.
6. Call Wait() on the server to do a blocking wait until process is killed or
   Shutdown() is called.

Creating the client

In this section, we'll look at creating a C++ client for our RouteGuide
service. You can see our complete example client code in
route_guide/route_guide_client.cc.

Creating a stub

To call service methods, we first need to create a stub.

First we need to create a gRPC channel for our stub, specifying the server
address and port we want to connect to without SSL:

grpc::CreateChannel("localhost:50051", grpc::InsecureChannelCredentials());

Now we can use the channel to create our stub using the NewStub method
provided in the RouteGuide class we generated from our .proto.

public:
 RouteGuideClient(std::shared_ptr<Channel> channel, const std::string& db)
     : stub_(RouteGuide::NewStub(channel)) {
   ...
 }

Calling service methods

Now let's look at how we call our service methods. Note that in this tutorial
we're calling the blocking/synchronous versions of each method: this means
that the RPC call waits for the server to respond, and will either return a
response or raise an exception.

Simple RPC

Calling the simple RPC GetFeature is nearly as straightforward as calling a
local method.

Point point;
  Feature feature;
  point = MakePoint(409146138, -746188906);
  GetOneFeature(point, &feature);

...

  bool GetOneFeature(const Point& point, Feature* feature) {
    ClientContext context;
    Status status = stub_->GetFeature(&context, point, feature);
    ...
  }

As you can see, we create and populate a request protocol buffer object (in our
case Point), and create a response protocol buffer object for the server to
fill in. We also create a ClientContext object for our call - you can
optionally set RPC configuration values on this object, such as deadlines,
though for now we'll use the default settings. Note that you cannot reuse this
object between calls. Finally, we call the method on the stub, passing it the
context, request, and response. If the method returns OK, then we can read the
response information from the server from our response object.

std::cout << "Found feature called " << feature->name()  << " at "
          << feature->location().latitude()/kCoordFactor_ << ", "
          << feature->location().longitude()/kCoordFactor_ << std::endl;

Streaming RPCs

Now let's look at our streaming methods. If you've already read Creating the
server some of this may look very familiar - streaming RPCs are
implemented in a similar way on both sides. Here's where we call the server-side
streaming method ListFeatures, which returns a stream of geographical
Features:

std::unique_ptr<ClientReader<Feature> > reader(
    stub_->ListFeatures(&context, rect));
while (reader->Read(&feature)) {
  std::cout << "Found feature called "
            << feature.name() << " at "
            << feature.location().latitude()/kCoordFactor_ << ", "
            << feature.location().longitude()/kCoordFactor_ << std::endl;
}
Status status = reader->Finish();

Instead of passing the method a context, request, and response, we pass it a
context and request and get a ClientReader object back. The client can use the
ClientReader to read the server's responses. We use the ClientReaders
Read() method to repeatedly read in the server's responses to a response
protocol buffer object (in this case a Feature) until there are no more
messages: the client needs to check the return value of Read() after each
call. If true, the stream is still good and it can continue reading; if
false the message stream has ended. Finally, we call Finish() on the stream
to complete the call and get our RPC status.

The client-side streaming method RecordRoute is similar, except there we pass
the method a context and response object and get back a ClientWriter.

std::unique_ptr<ClientWriter<Point> > writer(
        stub_->RecordRoute(&context, &stats));
    for (int i = 0; i < kPoints; i++) {
      const Feature& f = feature_list_[feature_distribution(generator)];
      std::cout << "Visiting point "
                << f.location().latitude()/kCoordFactor_ << ", "
                << f.location().longitude()/kCoordFactor_ << std::endl;
      if (!writer->Write(f.location())) {
        // Broken stream.
        break;
      }
      std::this_thread::sleep_for(std::chrono::milliseconds(
          delay_distribution(generator)));
    }
    writer->WritesDone();
    Status status = writer->Finish();
    if (status.IsOk()) {
      std::cout << "Finished trip with " << stats.point_count() << " points\n"
                << "Passed " << stats.feature_count() << " features\n"
                << "Travelled " << stats.distance() << " meters\n"
                << "It took " << stats.elapsed_time() << " seconds"
                << std::endl;
    } else {
      std::cout << "RecordRoute rpc failed." << std::endl;
    }

Once we've finished writing our client's requests to the stream using Write(),
we need to call WritesDone() on the stream to let gRPC know that we've
finished writing, then Finish() to complete the call and get our RPC status.
If the status is OK, our response object that we initially passed to
RecordRoute() will be populated with the server's response.

Finally, let's look at our bidirectional streaming RPC RouteChat(). In this
case, we just pass a context to the method and get back a ClientReaderWriter,
which we can use to both write and read messages.

std::shared_ptr<ClientReaderWriter<RouteNote, RouteNote> > stream(
    stub_->RouteChat(&context));

The syntax for reading and writing here is exactly the same as for our
client-streaming and server-streaming methods. Although each side will always
get the other's messages in the order they were written, both the client and
server can read and write in any order — the streams operate completely
independently.

Try it out!

Build client and server:

$ make

Run the server, which will listen on port 50051:

$ ./route_guide_server

Run the client (in a different terminal):

$ ./route_guide_client

grpc官方hello world的入門教程

gRPC C++ Hello World Tutorial

Install gRPC

Make sure you have installed gRPC on your system. Follow the
BUILDING.md instructions.

Get the tutorial source code

The example code for this and our other examples lives in the examples
directory. Clone this repository to your local machine by running the
following command:

$ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc

Change your current directory to examples/cpp/helloworld

$ cd examples/cpp/helloworld/

Defining a service

The first step in creating our example is to define a service: an RPC
service specifies the methods that can be called remotely with their parameters
and return types. As you saw in the
overview above, gRPC does this using protocol
buffers. We
use the protocol buffers interface definition language (IDL) to define our
service methods, and define the parameters and return
types as protocol buffer message types. Both the client and the
server use interface code generated from the service definition.

Here's our example service definition, defined using protocol buffers IDL in
helloworld.proto. The Greeting
service has one method, hello, that lets the server receive a single
HelloRequest
message from the remote client containing the user's name, then send back
a greeting in a single HelloReply. This is the simplest type of RPC you
can specify in gRPC - we'll look at some other types later in this document.

syntax = "proto3";

option java_package = "ex.grpc";

package helloworld;

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Generating gRPC code

Once we've defined our service, we use the protocol buffer compiler
protoc to generate the special client and server code we need to create
our application. The generated code contains both stub code for clients to
use and an abstract interface for servers to implement, both with the method
defined in our Greeting service.

To generate the client and server side interfaces:

$ make helloworld.grpc.pb.cc helloworld.pb.cc

Which internally invokes the proto-compiler as:

$ protoc -I ../../protos/ --grpc_out=. --plugin=protoc-gen-grpc=grpc_cpp_plugin ../../protos/helloworld.proto
$ protoc -I ../../protos/ --cpp_out=. ../../protos/helloworld.proto

Writing a client

• Create a channel. A channel is a logical connection to an endpoint. A gRPC
  channel can be created with the target address, credentials to use and
  arguments as follows

  auto channel = CreateChannel("localhost:50051", InsecureChannelCredentials());

• Create a stub. A stub implements the rpc methods of a service and in the
  generated code, a method is provided to created a stub with a channel:

  auto stub = helloworld::Greeter::NewStub(channel);

• Make a unary rpc, with ClientContext and request/response proto messages.

  ClientContext context;
  HelloRequest request;
  request.set_name("hello");
  HelloReply reply;
  Status status = stub->SayHello(&context, request, &reply);

• Check returned status and response.

  if (status.ok()) {
    // check reply.message()
  } else {
    // rpc failed.
  }

For a working example, refer to greeter_client.cc.

Writing a server

• Implement the service interface

  class GreeterServiceImpl final : public Greeter::Service {
    Status SayHello(ServerContext* context, const HelloRequest* request,
        HelloReply* reply) override {
      std::string prefix("Hello ");
      reply->set_message(prefix + request->name());
      return Status::OK;
    }
  };

• Build a server exporting the service

  GreeterServiceImpl service;
  ServerBuilder builder;
  builder.AddListeningPort("0.0.0.0:50051", grpc::InsecureServerCredentials());
  builder.RegisterService(&service);
  std::unique_ptr<Server> server(builder.BuildAndStart());

For a working example, refer to greeter_server.cc.

Writing asynchronous client and server

gRPC uses CompletionQueue API for asynchronous operations. The basic work flow
is

• bind a CompletionQueue to a rpc call
• do something like a read or write, present with a unique void* tag
• call CompletionQueue::Next to wait for operations to complete. If a tag
  appears, it indicates that the corresponding operation is complete.

Async client

The channel and stub creation code is the same as the sync client.

• Initiate the rpc and create a handle for the rpc. Bind the rpc to a
  CompletionQueue.

  CompletionQueue cq;
  auto rpc = stub->AsyncSayHello(&context, request, &cq);

• Ask for reply and final status, with a unique tag

  Status status;
  rpc->Finish(&reply, &status, (void*)1);

• Wait for the completion queue to return the next tag. The reply and status are
  ready once the tag passed into the corresponding Finish() call is returned.

  void* got_tag;
  bool ok = false;
  cq.Next(&got_tag, &ok);
  if (ok && got_tag == (void*)1) {
    // check reply and status
  }

For a working example, refer to greeter_async_client.cc.

Async server

The server implementation requests a rpc call with a tag and then wait for the
completion queue to return the tag. The basic flow is

• Build a server exporting the async service

  helloworld::Greeter::AsyncService service;
  ServerBuilder builder;
  builder.AddListeningPort("0.0.0.0:50051", InsecureServerCredentials());
  builder.RegisterService(&service);
  auto cq = builder.AddCompletionQueue();
  auto server = builder.BuildAndStart();

• Request one rpc

  ServerContext context;
  HelloRequest request;
  ServerAsyncResponseWriter<HelloReply> responder;
  service.RequestSayHello(&context, &request, &responder, &cq, &cq, (void*)1);

• Wait for the completion queue to return the tag. The context, request and
  responder are ready once the tag is retrieved.

  HelloReply reply;
  Status status;
  void* got_tag;
  bool ok = false;
  cq.Next(&got_tag, &ok);
  if (ok && got_tag == (void*)1) {
    // set reply and status
    responder.Finish(reply, status, (void*)2);
  }

• Wait for the completion queue to return the tag. The rpc is finished when the
  tag is back.

  void* got_tag;
  bool ok = false;
  cq.Next(&got_tag, &ok);
  if (ok && got_tag == (void*)2) {
    // clean up
  }

To handle multiple rpcs, the async server creates an object CallData to
maintain the state of each rpc and use the address of it as the unique tag. For
simplicity the server only uses one completion queue for all events, and runs a
main loop in HandleRpcs to query the queue.

For a working example, refer to greeter_async_server.cc.