thrift.md

中文版

thrift 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.

Example: 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

brpc depends on the thrift lib and the code generated by thrift tools to reuse the parsing code. Please read official documents to find out how 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 under Ubuntu Read Official wiki to install depended libs and tools, then download thrift source code from official site, uncompress and compile。

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 4 -s
sudo make install

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.

sh config_brpc.sh --headers=/usr/include --libs=/usr/lib --with-thrift

PS: Please Define ENABLE_THRIFT_FRAMED_PROTOCOL Marco in user code in order to make it work when including thrift utils headers in brpc.

Client accesses thrift server

Steps：

• Create a Channel setting protocol to brpc::PROTOCOL_THRIFT
• Define and use brpc::ThriftMessage as the request, brpc::ThriftMessage as the response. Call raw() method to get the native thrift message.
• Set method-name for thrift via Controller::set_thrift_method_name()

Example code:

#include <brpc/channel.h>
#include <brpc/thrift_message.h>         // Defines ThriftMessage
...

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;
}

...

// example::[EchoRequest/EchoResponse] are generated by thrift
brpc::ThriftMessage<example::EchoRequest> req;
brpc::ThriftMessage<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 processes thrift requests

Inherit brpc::ThriftService to implement the processing code, which may call the native handler generated by thrift to re-use existing entry directly, or read the request and set the response directly just as in other protobuf services.

class MyThriftProtocol : public brpc::ThriftService {
public:
    void ProcessThriftFramedRequest(const brpc::Server&,
                              brpc::Controller* cntl,
                              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().
        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>();

        // Get method-name for thrift via request->method_name() after Cast() was called
        if (_native_handler) {
            _native_handler->Echo(*res, *req);
        } else {
            res->data = req->data + "user data";
        }
    }
private:
    EchoServiceHandler* _native_handler;
};

Set the implemented service to ServerOptions.thrift_service and start the service.

    brpc::Server server;
    brpc::ServerOptions options;
    options.thrift_service = new MyThriftProtocol;
    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;
    }