Skip to content

B
brpc
Unverified Commit 7bd28453 authored by Ge Jun's avatar Ge Jun Committed by GitHub
Browse files
Options

Modify according to new thrift.md in chinese

parent 60fe48c0
Hide whitespace changes
Inline Side-by-side
Showing with 49 additions and 69 deletions
docs/en/thrift.md
View file @ 7bd28453
[中文版](../cn/thrift.md)
[thrift](https://thrift.apache.org/)is a RPC framework used widely in production environment which was developed by Facebook. In order to access thrift servers more conveniently and make full use of concurrency ability of bthread, 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.
[thrift](https://thrift.apache.org/) is a RPC framework used widely in various environments, which was developed by Facebook and adopted by Apache later. In order to interact with thrift servers and solves issues on thread-safety, usabilities and concurrencies, brpc directly supports the thrift protocol that is used by thrift in NonBlocking mode.
Advantages compared to the official thrift client:
Example: [example/thrift_extension_c++](https://github.com/brpc/brpc/tree/master/example/thrift_extension_c++/).
Advantages compared to the official solution:
- Thread safety. No need to set up separate clients for each thread.
- Supports synchronous, asynchronous, batch synchronous, batch asynchronous, and other access methods. Combination channels such as ParallelChannel are also supported.
- 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 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.
# Compile
To reuse the parsing code, brpc depends on the thrift lib and the code generated by thrift tools to support thrift. Please read official documents to find out methods to write thrift files, generate code, compilations etc.
brpc does not enable thrift support or depend on the thrift lib by default. If the thrift support is needed, config brpc with extra --with-thrift.
Install Thrift in Ubuntu
Install thrift under Ubuntu
Read [Official wiki](https://thrift.apache.org/docs/install/debian) to install depended libs and tools, then download the thrift source code from [official site](https://thrift.apache.org/download), uncompress and compile。
```bash
Download thrift source code from offical [web site](https://thrift.apache.org/download)
wget http://www.us.apache.org/dist/thrift/0.11.0/thrift-0.11.0.tar.gz
tar -xf thrift-0.11.0.tar.gz
cd thrift-0.11.0/
./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 CPPFLAGS=-DFORCE_BOOST_SMART_PTR -j 3 -s
make CPPFLAGS=-DFORCE_BOOST_SMART_PTR -j 4 -s
sudo make install
```
Debian please refer [offical wiki]](https://thrift.apache.org/docs/install/debian)
Configure with thrift support
Config brpc with thrift support, then make. The compiled libbrpc.a includes extended code for thrift support and can be linked normally as in other brpc projects.
```bash
sh config_brpc.sh --headers=/usr/include --libs=/usr/lib --nodebugsymbols --with-thrift
```
Thrift extension was supported via static library, libbrpc.a was generated after compile, link with it if users 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);
}
sh config_brpc.sh --headers=/usr/include --libs=/usr/lib --with-thrift
```
# Client accesses thrift server
Steps：
- Create a Channel with protocol set to brpc::PROTOCOL_THRIFT
- Define and use brpc::ThriftMessage<Native-Request> as the request, brpc::ThriftMessage<Native-Response> as the response. raw() method returns the native thrift message.
- Set method-name for thrift via Controller::set_thrift_method_name()
# Client asscess thrift server
create a Channel to access thrift server:
Example code:
```c++
#include <brpc/channel.h>
#include <brpc/details/thrift_utils.h>
#include <brpc/thrift_message.h>
#include <brpc/thrift_message.h>         // 定义了ThriftMessage
...
DEFINE_string(server, "0.0.0.0:8019", "IP Address of thrift server");
......@@ -69,39 +53,34 @@ if (thrift_channel.Init(Flags_server.c_str(), FLAGS_load_balancer.c_str(), &opti
LOG(ERROR) << "Fail to initialize thrift channel";
return -1;
}
...
```
Construct a thrift request and send it to server, ThriftMessage is a template class that hosts thrift navtive messages, raw() methods can directly manipulate native thrift messages.
```c++
// wrapper thrift raw request into ThriftMessage
// example::[EchoRequest/EchoResponse]is thrift native message generated by thrift toolkits
brpc::ThriftMessage<example::EchoRequest> req;
brpc::ThriftMessage<example::EchoResponse> res;
...
req.raw().data = "hello";
// wrapper thrift raw request into ThriftMessage
// example::[EchoRequest/EchoResponse]是thrfit原生定义的消息(通过thrift代码生成工具生成)
brpc::ThriftMessage<example::EchoRequest> req;
brpc::ThriftMessage<example::EchoResponse> res;
cntl.set_thrift_method_name("Echo");
req.raw().data = "hello";
cntl.set_thrift_method_name("Echo");
channel.CallMethod(NULL, &cntl, &req, &res, NULL);
channel.CallMethod(NULL, &cntl, &req, &res, NULL);
if (cntl.Failed()) {
LOG(ERROR) << "Fail to send thrift request, " << cntl.ErrorText();
return -1;
}
if (cntl.Failed()) {
LOG(ERROR) << "Fail to send thrift request, " << cntl.ErrorText();
return -1;
}
```
# Server side processing upstream thrift requests
Users need to implement their own thrift handler which was inherited from brpc::ThriftService.
Due to the limitation of thrift protocol itself, only the method name can be obtained on the server (via the controller.thrift_method_name() method), and the service name cannot be obtained. This is consistent with the native thrift implementation, which means that there can only be one thrift service in one brpc server.
# Server processes thrift requests
Inherit brpc::ThriftService to implement the processing code, which may call the native handler generated by thrift to re-use older entry directly, or read the request and set the response directly just as in other protobuf services.
```c++
// Implement User Thrift Service handler
class MyThriftProtocolPbManner : public brpc::ThriftService {
class MyThriftProtocol : public brpc::ThriftService {
public:
void ProcessThriftFramedRequest(const brpc::Server&,
brpc::Controller* cntl,
brpc::ThriftMessage* request,
brpc::ThriftMessage* response,
brpc::ThriftFramedMessage* request,
brpc::ThriftFramedMessage* 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().
......@@ -117,21 +96,23 @@ public:
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";
       // Get method-name for thrift via cntl->thrift_method_name()
       if (_native_handler) {
_native_handler->Echo(*res, *req);
} else {
res->data = req->data + "user data";
}
}
private:
EchoServiceHandler* _native_handler;
};
```
Register thrift service and start brpc server
After implementing the thrift service, set to ServerOptions.thrift_service and start the service.
```c++
brpc::Server server;
brpc::Server server;
brpc::ServerOptions options;
options.thrift_service = new MyThriftProtocolPbManner;
options.thrift_service = new MyThriftProtocol;
options.idle_timeout_sec = FLAGS_idle_timeout_s;
options.max_concurrency = FLAGS_max_concurrency;
......@@ -140,4 +121,4 @@ brpc::Server server;
LOG(ERROR) << "Fail to start EchoServer";
return -1;
}
```
\ No newline at end of file
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment