update docs

README.md

@@ -38,7 +38,7 @@
   * As a client, you can send POST requests with HTTP client developed in any language and add the required HTTP headers.
 * Built-in client/server which can seamlessly communicate with a server/client in other RPC frameworks, including:
   * BRPC
-  * TRPC
+  * TRPC (the only open-source implementation of TRPC protocol so far)
   * ~~GRPC~~
   * Thrift Framed Binary
   * Thrift Http Binary

README_cn.md

@@ -6,8 +6,7 @@
 [![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey.svg)](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey.svg)
 [![Build Status](https://travis-ci.com/sogou/srpc.svg?branch=master)](https://travis-ci.com/sogou/srpc)
 
-[Wiki：SRPC架构介绍](https://github.com/sogou/srpc/docs/wiki.md)
-
+[Wiki：SRPC架构介绍](/docs/wiki.md)
 
 
 ## Introduction
@@ -40,7 +39,7 @@
     * 如果自己是client调用方，用任何语言的http client发送post请求，添加若干http header即可
   * 内置了可以与其他RPC框架的server/client无缝互通的client/server，包括：
     * BRPC
-    * TRPC
+    * TRPC (目前唯一的TRPC协议开源实现)
     * ~~GRPC~~
     * Thrift Framed Binary
     * Thrift Http Binary
@@ -64,12 +63,21 @@ make
 sudo make install
 ~~~
 
-多种使用示例可以通过tutorial编译：
+## Tutorial
+
+* [第1步：设计IDL描述文件](docs/tutorial-01-idl.md)
+* [第2步：实现ServiceIMPL](docs/tutorial-02-service.md)
+* [第3步：启动Server](docs/tutorial-03-server.md)
+* [第4步：使用Client](docs/tutorial-04-client.md)
+* [第5步：了解异步Context](docs/tutorial-05-context.md)
+* [第6步：与workflow的结合使用](docs/tutorial-06-workflow.md)
+
+简单的命令即可编译示例：
 
 ~~~sh
  cd tutorial
  make
- ~~~
+~~~
 
 ## Quick Start
 #### 1. example.proto
@@ -214,15 +222,6 @@ message: "Hi, workflow"
 {"message":"Hi, CURL"}
 ~~~
 
-## Tutorial
-
-* [第1步：设计IDL描述文件](docs/tutorial-01-idl.md)
-* [第2步：实现ServiceIMPL](docs/tutorial-02-service.md)
-* [第3步：启动Server](docs/tutorial-03-server.md)
-* [第4步：使用Client](docs/tutorial-04-client.md)
-* [第5步：了解异步Context](docs/tutorial-05-context.md)
-* [第6步：与workflow的结合使用](docs/tutorial-06-workflow.md)
-
 ## Benchmark
 
 * CPU 2-chip/8-core/32-processor Intel(R) Xeon(R) CPU E5-2630 v3 @2.40GHz

docs/en/rpc.md

@@ -1,4 +1,4 @@
-[中文版入口](/docs/rpc.md)
+[中文版](/docs/rpc.md)
 
 ## Comparison of basic features
 
@@ -446,3 +446,4 @@ int main()
     return 0;
 }
 ~~~
+

docs/en/tutorial-01-idl.md

@@ -0,0 +1,34 @@
+[中文版](/docs/tutorial-01-idl.md)
+
+## RPC IDL
+
+- Interface Description Languaue file
+- Backward and forward compatibility
+- Protobuf/Thrift
+
+### Sample
+
+You can follow the detailed example below:
+
+- Take pb as an example. First, define an `example.proto` file with the ServiceName as `Example`.
+- The name of the rpc interface is `Echo`, with the input parameter as `EchoRequest`, and the output parameter as `EchoResponse`.
+- `EchoRequest` consists of two strings: `message` and `name`.
+- `EchoResponse` consists of one string: `message`.
+
+~~~proto
+syntax="proto2";
+
+message EchoRequest {
+    optional string message = 1;
+    optional string name = 2;
+};
+
+message EchoResponse {
+    optional string message = 1;
+};
+
+service Example {
+     rpc Echo(EchoRequest) returns (EchoResponse);
+};
+~~~
+

docs/en/tutorial-02-service.md

@@ -0,0 +1,33 @@
+[中文版](/docs/tutorial-02-service.md)
+
+## RPC Service
+
+- It is the basic unit for sogouRPC services.
+- Each service must be generated by one type of IDLs.
+- Service is determined by IDL type, not by specific network communication protocol.
+
+### Sample
+
+You can follow the detailed example below:
+
+- Use the same `example.proto` IDL above.
+- Run the official `protoc example.proto --cpp_out=./ --proto_path=./` to get two files: `example.pb.h` and `example.pb.cpp`.
+- Run the `srpc_generator protobuf ./example.proto ./` in SogouRPC to get `example.srpc.h`.
+- Derive `Example::Service` to implement the rpc business logic, which is an RPC Service.
+- Please note that this Service does not involve any concepts such as network, port, communication protocol, etc., and it is only responsible for completing the business logic that convert `EchoRequest` to `EchoResponse`.
+
+~~~cpp
+class ExampleServiceImpl : public Example::Service
+{
+public:
+    void Echo(EchoRequest *request, EchoResponse *response, RPCContext *ctx) override
+    {
+        response->set_message("Hi, " + request->name());
+
+        printf("get_req:\n%s\nset_resp:\n%s\n",
+                request->DebugString().c_str(),
+                response->DebugString().c_str());
+    }
+};
+~~~
+

docs/en/tutorial-03-server.md

@@ -0,0 +1,56 @@
+[中文版](/docs/tutorial-03-server.md)
+
+## RPC Server
+
+- Each server corresponds to one port
+- Each server corresponds to one specific network communication protocol
+- One service may be added into multiple Servers
+- One Server may have one or more Services, but the ServiceName must be unique within that Server
+- Services from different IDLs can be added into the same Server
+
+### Sample
+
+You can follow the detailed example below:
+
+- Follow the above `ExampleServiceImpl` Service
+- First, create an RPC Server and determine the proto file.
+- Then, create any number of Service instances and any number of Services for different protocols, and add these services to the Server through the `add_service()`interface.
+- Finally, use `start()` or `serve()` to start the services in the Server and handle the upcoming rpc requests through the Server.
+- Imagine that we can also derive more Serivce from `Example::Service`, which have different implementations of rpc `Echo`.
+- Imagine that we can create N different RPC Servers on N different ports, serving on different network protocols.
+- Imagine that we can use `add_service()` to add the same ServiceIMPL instance on different Servers, or we can use `add_service()` to add different ServiceIMPL instances on the same server.
+- Imagine that we can use the same `ExampleServiceImpl`, serving BPRC-STD, SogouRPC-STD, SogouRPC-Http at three different ports at the same time.
+- And we can use `add_service()` to add one `ExampleServiceImpl` related to Protobuf IDL and one `AnotherThriftServiceImpl` related to Thrift IDL to the same SogouRPC-STD Server, and the two IDLs work perfectly on the same port!
+
+~~~cpp
+int main()
+{
+    SRPCServer server_srpc;
+    SRPCHttpServer server_srpc_http;
+    BRPCServer server_brpc;
+    ThriftServer server_thrift;
+
+    ExampleServiceImpl impl_pb;
+    AnotherThriftServiceImpl impl_thrift;
+
+    server_srpc.add_service(&impl_pb);
+    server_srpc.add_service(&impl_thrift);
+    server_srpc_http.add_service(&impl_pb);
+    server_srpc_http.add_service(&impl_thrift);
+    server_brpc.add_service(&impl_pb);
+    server_thrift.add_service(&impl_thrift);
+
+    server_srpc.start(1412);
+    server_srpc_http.start(8811);
+    server_brpc.start(2020);
+    server_thrift.start(9090);
+    pause();
+    server_thrift.stop();
+    server_brpc.stop();
+    server_srpc_http.stop();
+    server_srpc.stop();
+
+    return 0;
+}
+~~~
+

docs/en/tutorial-04-client.md

@@ -0,0 +1,43 @@
+[中文版](/docs/tutorial-04-client.md)
+
+## RPC Client
+
+- Each Client corresponds to one specific target/one specific cluster
+- Each Client corresponds to one specific network communication protocol
+- Each Client corresponds to one specific IDL
+
+### Sample
+
+You can follow the detailed example below:
+
+- Following the above example, the client is relatively simple and you can call the method directly.
+- Use `Example::XXXClient` to create a client instance of some RPC. The IP+port or URL of the target is required.
+- With the client instance, directly call the rpc function `Echo`. This is an asynchronous request, and the callback function will be invoked after the request is completed.
+- For the usage of the RPC Context, please check [RPC Context](/docs/en/rpc.md#rpc-context).
+
+~~~cpp
+#include <stdio.h>
+#include "example.srpc.h"
+
+using namespace srpc;
+
+int main()
+{
+    Example::SRPCClient client("127.0.0.1", 1412);
+    EchoRequest req;
+    req.set_message("Hello, sogou rpc!");
+    req.set_name("Li Yingxin");
+
+    client.Echo(&req, [](EchoResponse *response, RPCContext *ctx) {
+        if (ctx->success())
+            printf("%s\n", response->DebugString().c_str());
+        else
+            printf("status[%d] error[%d] errmsg:%s\n",
+                    ctx->get_status_code(), ctx->get_error(), ctx->get_errmsg());
+    });
+
+    pause();
+    return 0;
+}
+~~~
+

docs/en/tutorial-05-context.md

@@ -0,0 +1,96 @@
+[中文版](/docs/tutorial-05-context.md)
+
+## RPC Context
+
+- RPCContext is used specially to assist asynchronous interfaces, and can be used in both Service and Client.
+- Each asynchronous interface will provide a Context, which offers higher-level functions, such as obtaining the remote IP, the connection seqid, and so on.
+- Some functions on Context are unique to Server or Client. For example, you can set the compression mode of the response data on Server, and you can obtain the success or failure status of a request on Client.
+- On the Context, you can use ``get_series()`` to obtain the SeriesWork, which is seamlessly integrated with the asynchronous mode of Workflow.
+
+### RPCContext API - Common
+
+#### `long long get_seqid() const;`
+
+One complete communication consists of request+response. The sequence id of the communication on the current socket connection can be obtained, and seqid=0 indicates the first communication.
+
+#### `std::string get_remote_ip() const;`
+
+Get the remote IP address. IPv4/IPv6 is supported.
+
+#### `int get_peer_addr(struct sockaddr *addr, socklen_t *addrlen) const;`
+
+Get the remote address. The in/out parameter is the lower-level data structure sockaddr.
+
+#### `const std::string& get_service_name() const;`
+
+Get RPC Service Name.
+
+#### `const std::string& get_method_name() const;`
+
+Get RPC Method Name.
+
+#### `SeriesWork *get_series() const;`
+
+Get the SeriesWork of the current ServerTask/ClientTask.
+
+### RPCContext API - Only for client done
+
+#### `bool success() const;`
+
+For client only. The success or failure of the request.
+
+#### `int get_status_code() const;`
+
+For client only. The rpc status code of the request.
+
+#### `const char *get_errmsg() const;`
+
+For client only. The error info of the request.
+
+#### `int get_error() const;`
+
+For client only. The error code of the request.
+
+#### `void *get_user_data() const;`
+
+For client only. Get the user\_data of the ClientTask. If a user generates a task through the ``create_xxx_task()`` interface, the context can be recorded in the user_data field. You can set that field when creating the task, and retrieve it in the callback function.
+
+### RPCContext API - Only for server process
+
+#### `void set_data_type(RPCDataType type);`
+
+For Server only. Set the data packaging type
+
+- RPCDataProtobuf
+- RPCDataThrift
+- RPCDataJson
+
+#### `void set_compress_type(RPCCompressType type);`
+
+For Server only. Set the data compression type (note: the compression type for the Client is set on Client or Task)
+
+- RPCCompressNone
+- RPCCompressSnappy
+- RPCCompressGzip
+- RPCCompressZlib
+- RPCCompressLz4
+
+#### `void set_attachment_nocopy(const char *attachment, size_t len);`
+
+For Server only. Set the attachment.
+
+#### `bool get_attachment(const char **attachment, size_t *len) const;`
+
+For Server only. Get the attachment.
+
+#### `void set_reply_callback(std::function<void (RPCContext *ctx)> cb);`
+
+For Server only. Set reply callback, which is called after the operating system successfully writes the data into the socket buffer.
+
+#### `void set_send_timeout(int timeout);`
+
+For Server only. Set the maximum time for sending the message, in milliseconds. -1 indicates unlimited time.
+
+#### `void set_keep_alive(int timeout);`
+For Server only. Set the maximum connection keep-alive time,  in milliseconds. -1 indicates unlimited time.
+