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.