Apache Thrift Overview

kc@example.com (kc kim) — Mon, 05 Jun 2023 10:30:42 +0900

Apache Thrift Overview

Apache Thrift is an RPC (Remote Procedure Call) framework. It was developed at Facebook, became open source in April 2007, entered the Apache Incubator in May 2008, and became an Apache TLP (Top-Level Project) in November 2010. Thrift is powerful and provides fast binary transport.
Apache Thrift - Home

Installing Apache Thrift

You can find installation information in the following document.
http://wiki.apache.org/thrift/ThriftInstallation

Installing on Ubuntu

The Ubuntu installation steps are summarized below.

Install the required dependencies.

$ sudo apt-get install libboost-dev libboost-test-dev \
libboost-program-options-dev libevent-dev automake libtool flex bison \
pkg-config g++ libssl-dev

Move to the installation root directory.
$ ./configure
$ make
Run the following command as a superuser.
```
$ make install
```

Installing on Mac

In a Mac environment, you can install it with Homebrew using the following commands.

% brew update
% brew install thrift

Apache Thrift IDL

In Thrift, interfaces are defined with IDL (Interface Description Language or Interface Definition Language), and source code is generated for each language for implementation.

Supported languages include As3, C Glib, C++, CSharp, D, Delphi, Erlang, Go, Graphviz, Haskell, Java, Java Me, Javascript, Node.js, Objective-c, OCaml, Perl, PHP, Python, Ruby, Smalltalk, and more than 24 others.
Apache Thrift - Language and Feature Matrix

This section explains Thrift IDL.

Available Types

Thrift supports six kinds of types: base types, container types, structs, exceptions, enums, and unions.

Base Types

Type	Description
`bool`	Boolean, one byte. Logical value, true or false.
`byte`	Signed byte. 1-byte integer.
`i16`	Signed 16-bit integer. 2-byte integer.
`i32`	Signed 32-bit integer. 4-byte integer.
`i64`	Signed 64-bit integer. 8-byte integer.
`double`	64-bit floating point value. 8-byte floating point.
`string`	String. UTF-8 encoded string.
`binary`	Blob (byte array) Unencoded byte data.

Container Types

Type	Description
`map<t1,t2>`	Map from one type to another. A unique key-value combination. Synonymous with C++ STL map, Java HashMap, PHP associative arrays, and Python/Ruby dictionaries.
`list<t1>`	Ordered list of one type. A list of elements. Synonymous with C++ STL vector, Java ArrayList, and arrays in scripting languages.
`set<t1>`	Set of unique elements of one type. A collection of unique elements. Synonymous with C++ STL set, Java HashSet, and Python set.

Container type definitions follow C++ usage. The following is an example definition.

struct ExampleContainerDefinition
{
  1:map<i32, string> mapexample,
  2:set<i32> setexample,
  3:list<i32> listexample
}

Structs

Thrift structs are very similar to C structs. A common declaration is written as follows.

struct ExampleStructure
{
  1:i32 id,
  2:string message
}

The values written at the beginning, such as 1 and 2, are called Field IDs. A Field ID must be unique within the struct and is used to verify that the structure definition matches on both server and client. (The same ID may appear in a different struct.)

You can also set initial values and define whether struct fields are required or optional. An initial value can be specified after the field name with =. To mark whether a struct field is required, write required; if it is optional, write optional.

struct ExampleStructure
{
  1: required i32 id,
  2: optional string message="default"
}

Exceptions

As with structs, you can define types used for exceptions.

exception exampleException 
{
  1:i32 errorcode,
  2:string message
}

Enums

Thrift also supports enums. Enum values are assigned from 0 in order, but arbitrary values can also be defined.

enum exampleEnum1 {
  EnumA,
  EnumB,
  EnumC
}

enum exampleEnum2 {
  ONE = 1,
  TWO,
  FIVE = 5
}

Unions

A union is defined in the same way as a struct, but it behaves differently.
Only one of the multiple fields defined in a union can be used. A Thrift union is like a C++ union.

For this reason, required cannot be used on union fields.

Services

A Service defined in Thrift is like an interface class. Inside a Service, define a collection of methods.

service exampleService 
{
  void set(1:i32 key,2:string value),
  string get(1:i32 key) throws (1:i32 errorcode),
  i32 size()
}

Method

In Thrift, methods can be defined inside a Service.
Methods can use types that Thrift can define, as well as void.
As with struct declarations, method arguments require Field IDs that are unique within the method argument list.

Exception

Thrift can also define exceptions.

The following is an exception definition example.

exception exampleException1 
{
  1:i32 errorcode,
  2:string message
}

service exampleService 
{
  void testException1(1:string arg) throws(1:exampleException1 error),
  void testException2(1:string arg) throws(1:exampleException1 error, 2:i32 error2)
}

As in testException2, multiple exceptions can also be defined.

oneway method

Among methods defined in a Service, you can also define methods that do not need to wait for a response.

When using a oneway method, the return value must be void.

service exampleService
{
  oneway void show()
}

Other Thrift Rules

This section explains writing rules for Thrift definition files.

Comments

Comments can be written as follows.

/*
 comment
*/

// comment

Headers

Headers can use three kinds: include, cpp_include, and namespace.

include

Use include when using another thrift file. Define it in the form include "example.thrift".

cpp_include

To include C++, add a custom C++ include to the output of the C++ code generator in Thrift.

namespace

namespace determines the namespace to which structs, enums, and Services defined in the file belong.
It is defined as follows, and the place of cpp can contain values such as php or java.

The notable point about namespaces is that they should be defined for each language.

namespace cpp hoge
namespace java hoge

Constants

Constants can be defined inside Thrift definitions.

To declare a constant, simply place const before the type name.

const EXAMPLE_VALUE = 1

Typedef

You can change type names inside Thrift definitions.

To change a type name, add typedef before the type.

typedef ExampleType i32

Field Naming Rules

Field names may contain letters, numbers, _, and .. The first character of a field must be a letter or _.

References

Thrift interface description language

devkuma – RPC

Apache Thrift Overview