Merge branch 'kenshinxf' of https://github.com/kenshinxf/brpc into kenshinxf

README.md

@@ -13,7 +13,7 @@ You can use it to:
   * [rtmp](https://github.com/brpc/brpc/blob/master/src/brpc/rtmp.h)/[flv](https://en.wikipedia.org/wiki/Flash_Video)/[hls](https://en.wikipedia.org/wiki/HTTP_Live_Streaming), for building [live-streaming services](docs/cn/live_streaming.md).
   * hadoop_rpc (may be opensourced)
   * [rdma](https://en.wikipedia.org/wiki/Remote_direct_memory_access) support (will be opensourced)
-  * all sorts of protocols used in Baidu: [baidu_std](docs/cn/baidu_std.md), [streaming_rpc](docs/en/streaming_rpc.md), hulu_pbrpc, [sofa_pbrpc](https://github.com/baidu/sofa-pbrpc), nova_pbrpc, public_pbrpc, ubrpc, and nshead-based ones.
+  * all sorts of protocols used in Baidu: [baidu_std](docs/cn/baidu_std.md), [streaming_rpc](docs/en/streaming_rpc.md), hulu_pbrpc, [sofa_pbrpc](https://github.com/baidu/sofa-pbrpc), nova_pbrpc, public_pbrpc, ubrpc, [thrift](docs/en/thrift.md) and nshead-based ones.
   * Access protobuf-based protocols with HTTP+json, probably from another language.
   * Build [HA](https://en.wikipedia.org/wiki/High_availability) distributed services using an industrial-grade implementation of [RAFT consensus algorithm](https://raft.github.io) which is opensourced at [braft](https://github.com/brpc/braft)
 * Servers can handle requests [synchronously](docs/en/server.md) or [asynchronously](docs/en/server.md#asynchronous-service).

README_cn.md

@@ -14,7 +14,7 @@
   * [rtmp](https://github.com/brpc/brpc/blob/master/src/brpc/rtmp.h)/[flv](https://en.wikipedia.org/wiki/Flash_Video)/[hls](https://en.wikipedia.org/wiki/HTTP_Live_Streaming), 可用于搭建[直播服务](docs/cn/live_streaming.md).
   * hadoop_rpc(可能开源)
   * 支持[rdma](https://en.wikipedia.org/wiki/Remote_direct_memory_access)(即将开源)
-  * 各种百度内使用的协议: [baidu_std](docs/cn/baidu_std.md), [streaming_rpc](docs/cn/streaming_rpc.md), hulu_pbrpc, [sofa_pbrpc](https://github.com/baidu/sofa-pbrpc), nova_pbrpc, public_pbrpc, ubrpc和使用nshead的各种协议.
+  * 各种百度内使用的协议: [baidu_std](docs/cn/baidu_std.md), [streaming_rpc](docs/cn/streaming_rpc.md), hulu_pbrpc, [sofa_pbrpc](https://github.com/baidu/sofa-pbrpc), nova_pbrpc, public_pbrpc, ubrpc, [thrift](docs/cn/thrift.md)和使用nshead的各种协议.
   * 从其他语言通过HTTP+json访问基于protobuf的协议.
   * 基于工业级的[RAFT算法](https://raft.github.io)实现搭建[高可用](https://en.wikipedia.org/wiki/High_availability)分布式系统，已在[braft](https://github.com/brpc/braft)开源。
 * Server能[同步](docs/cn/server.md)或[异步](docs/cn/server.md#异步service)处理请求。

docs/cn/client.md

@@ -543,6 +543,7 @@ Channel的默认协议是baidu_std，可通过设置ChannelOptions.protocol换
 - PROTOCOL_REDIS 或 "redis"，redis 1.2后的协议（也是hiredis支持的协议），默认为单连接。具体方法见[访问Redis](redis_client.md)。
 - PROTOCOL_NSHEAD_MCPACK 或 "nshead_mcpack", 顾名思义，格式为nshead + mcpack，使用mcpack2pb适配，默认为连接池。
 - PROTOCOL_ESP 或 "esp"，访问使用esp协议的服务，默认为连接池。
+- PROTOCOL_THRIFT 或 "thrift"，访问使用thrift协议的服务，默认为连接池, 具体方法见[访问thrift](thrift.md)。
 
 ## 连接方式
 

docs/cn/thrift.md

+[English Version](../en/thrift.md)
+
+[thrift](https://thrift.apache.org/)是近几年应用较广的Facebook发布的RPC服务, 为了使用户更方便,快捷的利用bthread的并发能力，brpc实现并支持thrift工作在NonBlocking模式下的协议(FramedProtocol), 注意本文中所说的thrift协议一律指的是此种情况下的thrift协议.
+示例程序：[example/thrift_extension_c++](https://github.com/brpc/brpc/tree/master/example/thrift_extension_c++/)
+
+相比使用官方原生的优势有：
+
+- 线程安全。用户不需要为每个线程建立独立的client。
+- 支持同步、异步、批量同步、批量异步等访问方式，能使用ParallelChannel等组合访问方式。
+- 支持多种连接方式(连接池, 短连接), 支持超时、backup request、取消、tracing、内置服务等一系列RPC基本福利。
+
+# 编译依赖及运行
+默认brpc编译是不启用thrift协议支持的, 目的是在用户不需要thrift协议支持的情况下可以不安装thrift依赖. 如果用户启用thrift协议的话, 在配置brpc环境的时候加上--with-thrift参数(实际上是在Makefile里面启用ENABLE_THRIFT_FRAMED_PROTOCOL宏)
+
+安装thrift依赖, ubuntu环境下
+```bash
+wget http://www.us.apache.org/dist/thrift/0.9.3/thrift-0.9.3.tar.gz
+tar -xf thrift-0.9.3.tar.gz
+cd thrift-0.9.3/
+./configure --prefix=/usr --with-ruby=no --with-python=no --with-java=no --with-go=no --with-perl=no --with-php=no --with-csharp=no --with-erlang=no --with-lua=no --with-nodejs=no
+make -j 3 -s
+sudo make install
+```
+配置brpc支持thrift协议
+```bash
+sh config_brpc.sh --headers=/usr/include --libs=/usr/lib --nodebugsymbols --with-thrift
+```
+编译完成后会生成libbrpc.a 和libbrpc_thrift.a, thrift扩展协议以静态库的方式提供给用户, 用户在需要启用thrift协议的时候链接即可
+
+# Thrift 原生消息定义, echo.thrift:
+```c++
+namespace cpp example
+
+struct EchoRequest {
+    1: required string data;
+    2: required i32 s;
+}
+
+struct EchoResponse {
+    1: required string data;
+}
+
+service EchoService {
+    EchoResponse Echo(1:EchoRequest request);
+}
+```
+
+
+# Client端访问下游thrift server
+
+创建一个访问thrift server的Channel：
+
+```c++
+#include <brpc/channel.h>
+#include <brpc/details/thrift_utils.h>
+#include <brpc/thrift_message.h>
+...
+
+DEFINE_string(server, "0.0.0.0:8019", "IP Address of thrift server");
+DEFINE_string(load_balancer, "", "The algorithm for load balancing");
+...
+  
+brpc::ChannelOptions options;
+options.protocol = brpc::PROTOCOL_THRIFT;
+brpc::Channel thrift_channel;
+if (thrift_channel.Init(Flags_server.c_str(), FLAGS_load_balancer.c_str(), &options) != 0) {
+   LOG(ERROR) << "Fail to initialize thrift channel";
+   return -1;
+}
+...
+```
+构造thrift请求, 并发送, ThriftTemplateMessage是模板类, 里面托管了thrift原生消息, 通过raw()方法可以可以直接操作原生thrift消息
+```c++
+ // wrapper thrift raw request into ThriftMessage
+ // example::[EchoRequest/EchoResponse]是thrfit原生定义的消息(通过thrift代码生成工具生成)
+ brpc::ThriftTemplateMessage<example::EchoRequest> req;
+ brpc::ThriftTemplateMessage<example::EchoResponse> res;
+
+ req.raw().data = "hello";
+
+ cntl.set_thrift_method_name("Echo");
+
+ channel.CallMethod(NULL, &cntl, &req, &res, NULL);
+
+ if (cntl.Failed()) {
+     LOG(ERROR) << "Fail to send thrift request, " << cntl.ErrorText();
+     return -1;
+ } 
+```
+
+# Server端处理上游thrfit请求
+
+类似原生brpc协议, 用户需要实现自己的thrift handler, 继承自brpc::ThriftService
+由于thrift协议本身的限制, 在服务端只能获取到method name(通过controller.thrift_method_name()方法), 无法获取到service name, 这和原生的thrift实现是一致的, 也就意味着在一个brpc server中只能有一个thrift service
+```c++
+// Implement User Thrift Service handler
+class MyThriftProtocolPbManner : public brpc::ThriftService {
+public:
+    void ProcessThriftFramedRequest(const brpc::Server&,
+                              brpc::Controller* cntl,
+                              brpc::ThriftMessage* request,
+                              brpc::ThriftMessage* response,
+                              brpc::ThriftClosure* done) {
+        // This object helps you to call done->Run() in RAII style. If you need
+        // to process the request asynchronously, pass done_guard.release().
+        brpc::ClosureGuard done_guard(done);
+
+        if (cntl->Failed()) {
+            // NOTE: You can send back a response containing error information
+            // back to client instead of closing the connection.
+            cntl->CloseConnection("Close connection due to previous error");
+            return;
+        }
+
+        example::EchoRequest* req = request->cast<example::EchoRequest>();
+        example::EchoResponse* res = response->cast<example::EchoResponse>();
+
+        // process with req and res
+        res->data = req->data + "user data";
+
+        LOG(INFO) << "success to process thrift request in brpc with pb manner";
+
+    }
+
+};
+```
+
+注册thrift service并启动服务
+```c++
+brpc::Server server;
+    brpc::ServerOptions options;
+    options.thrift_service = new MyThriftProtocolPbManner;
+    options.idle_timeout_sec = FLAGS_idle_timeout_s;
+    options.max_concurrency = FLAGS_max_concurrency;
+
+    // Start the server.
+    if (server.Start(FLAGS_port, &options) != 0) {
+        LOG(ERROR) << "Fail to start EchoServer";
+        return -1;
+    }
+```
\ No newline at end of file

docs/en/thrift.md

+[中文版](../cn/thrift.md)
+
+[thrift](https://thrift.apache.org/)is a RPC framework used widely in production area which was developed by Facebook, In order to access thrift servers more conveniently and make full use of bthread's capability of concurrency, brpc directly supports the thrift protocol.
+Check [example/thrift_extension_c++](https://github.com/brpc/brpc/tree/master/example/thrift_extension_c++/) for an example.
+
+Advantages compared to the official thrift client:
+- Thread safety. No need to set up separate clients for each thread.
+- Support synchronous, asynchronous, semi-synchronous accesses etc. Support [ParallelChannel etc](combo_channel.md) to define access patterns declaratively.
+- Support various connection types(short, connection pool). Support timeout, backup request, cancellation, tracing, built-in services, and other benefits offered by brpc.
+
+# Compile and Run
+In order to not depend on and compile with thrift library for most of the users, the thrift protocol wasn't supported in brpc by default. configure brpc with --with-thrift if you want to enable thrift protocol in brpc(actually it works with a Macro ENABLE_THRIFT_FRAMED_PROTOCOL)
+
+Install Thrift in Ubuntu
+```bash
+wget http://www.us.apache.org/dist/thrift/0.9.3/thrift-0.9.3.tar.gz
+tar -xf thrift-0.9.3.tar.gz
+cd thrift-0.9.3/
+./configure --prefix=/usr --with-ruby=no --with-python=no --with-java=no --with-go=no --with-perl=no --with-php=no --with-csharp=no --with-erlang=no --with-lua=no --with-nodejs=no
+make -j 3 -s
+sudo make install
+```
+Configure with thrift support
+```bash
+sh config_brpc.sh --headers=/usr/include --libs=/usr/lib --nodebugsymbols --with-thrift
+```
+Link with libbrpc_thrift.a if the user want to enable thrift protocol
+
+# Thrift message definition, echo.thrift:
+```c++
+namespace cpp example
+
+struct EchoRequest {
+    1: required string data;
+    2: required i32 s;
+}
+
+struct EchoResponse {
+    1: required string data;
+}
+
+service EchoService {
+    EchoResponse Echo(1:EchoRequest request);
+}
+```
+
+
+# Client asscess thrift server
+
+create a Channel to access thrift server:
+
+```c++
+#include <brpc/channel.h>
+#include <brpc/details/thrift_utils.h>
+#include <brpc/thrift_message.h>
+...
+
+DEFINE_string(server, "0.0.0.0:8019", "IP Address of thrift server");
+DEFINE_string(load_balancer, "", "The algorithm for load balancing");
+...
+  
+brpc::ChannelOptions options;
+options.protocol = brpc::PROTOCOL_THRIFT;
+brpc::Channel thrift_channel;
+if (thrift_channel.Init(Flags_server.c_str(), FLAGS_load_balancer.c_str(), &options) != 0) {
+   LOG(ERROR) << "Fail to initialize thrift channel";
+   return -1;
+}
+...
+```
+construct thrift request and send to server, ThriftTemplateMessage is a template class, the native thrift message was delegated by and can be accessed directly by raw() method.
+
+```c++
+ // wrapper thrift raw request into ThriftMessage
+ // example::[EchoRequest/EchoResponse]is thrift native message generated by thrift toolkits
+ brpc::ThriftTemplateMessage<example::EchoRequest> req;
+ brpc::ThriftTemplateMessage<example::EchoResponse> res;
+
+ req.raw().data = "hello";
+
+ cntl.set_thrift_method_name("Echo");
+
+ channel.CallMethod(NULL, &cntl, &req, &res, NULL);
+
+ if (cntl.Failed()) {
+     LOG(ERROR) << "Fail to send thrift request, " << cntl.ErrorText();
+     return -1;
+ } 
+```
+
+# Server process with thrift message
+User need to implement it's own thrift handler which was inherited from brpc::ThriftService
+Only the method name can obtained in server side due to the limit of thrift protocol itself, the service name wasn't passed to server actually, it means that only one thrift service can be set in one brpc server
+```c++
+// Implement User Thrift Service handler
+class MyThriftProtocolPbManner : public brpc::ThriftService {
+public:
+    void ProcessThriftFramedRequest(const brpc::Server&,
+                              brpc::Controller* cntl,
+                              brpc::ThriftMessage* request,
+                              brpc::ThriftMessage* response,
+                              brpc::ThriftClosure* done) {
+        // This object helps you to call done->Run() in RAII style. If you need
+        // to process the request asynchronously, pass done_guard.release().
+        brpc::ClosureGuard done_guard(done);
+
+        if (cntl->Failed()) {
+            // NOTE: You can send back a response containing error information
+            // back to client instead of closing the connection.
+            cntl->CloseConnection("Close connection due to previous error");
+            return;
+        }
+
+        example::EchoRequest* req = request->cast<example::EchoRequest>();
+        example::EchoResponse* res = response->cast<example::EchoResponse>();
+
+        // process with req and res
+        res->data = req->data + "user data";
+
+        LOG(INFO) << "success to process thrift request in brpc with pb manner";
+
+    }
+
+};
+```
+
+Register thrift service and start brpc server
+```c++
+brpc::Server server;
+    brpc::ServerOptions options;
+    options.thrift_service = new MyThriftProtocolPbManner;
+    options.idle_timeout_sec = FLAGS_idle_timeout_s;
+    options.max_concurrency = FLAGS_max_concurrency;
+
+    // Start the server.
+    if (server.Start(FLAGS_port, &options) != 0) {
+        LOG(ERROR) << "Fail to start EchoServer";
+        return -1;
+    }
+```
\ No newline at end of file

src/brpc/policy/thrift_protocol.cpp

@@ -638,7 +638,7 @@ void RegisterThriftProtocol() {
                                  policy::SerializeThriftRequest, policy::PackThriftRequest,
                                  policy::ProcessThriftRequest, policy::ProcessThriftResponse,
                                  policy::VerifyThriftRequest, NULL, NULL,
-                                 CONNECTION_TYPE_POOLED_AND_SHORT, "thrift" };
+                                 CONNECTION_TYPE_POOLED, "thrift" };
     if (RegisterProtocol(PROTOCOL_THRIFT, thrift_binary_protocol) != 0) {
         exit(1);
     }