Thrift Protocol Documentation

Thrift Protocol Documentation

Table of Contents

  1. Introduction
  2. Protocol Structure
  3. Data Types
  4. Data Structures
  5. Service Definition
  6. Examples
  7. Protocol Advantages and Use Cases
  8. Official Documentation

Introduction

Thrift is a scalable cross-language service development framework that combines a powerful code generation engine to build efficient, reliable, and seamlessly compatible services. Thrift supports multiple programming languages, including C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, and more.

Protocol Structure

The Thrift protocol consists of several components:

  • Namespace: Used for logical grouping of code.
  • Data Structures: Define the data format for communication between services.
  • Service Interface: Defines method signatures for remote procedure calls (RPC).

Data Types

Thrift supports the following basic data types:

  • bool: Boolean value
  • byte: 8-bit signed integer
  • i16: 16-bit signed integer
  • i32: 32-bit signed integer
  • i64: 64-bit signed integer
  • double: 64-bit floating point number
  • string: UTF-8 encoded string

Additionally, Thrift supports complex data types:

  • struct: Struct-like structure in C language.
  • union: Union-like structure in C language.
  • enum: Enumeration representing a set of named integer constants.
  • list: Ordered collection of elements.
  • set: Unordered collection of unique elements.
  • map: Collection of key-value pairs.

Data Structures

In Thrift, data structures are defined using the struct keyword. Each field must be assigned a unique identifier and type. For example:

1
2
3
4
5
struct Person {
1: i32 id,
2: string name,
3: i16 age
}

Struct

A struct is the most commonly used data structure in Thrift, similar to classes or structs in other languages. Each field can be any data type, including other structs.

Graphical Example

1
2
3
4
5
6
7
8
9
+----------------------------+
| Person |
+---------+------------------+
| id | i32 |
+---------+------------------+
| name | string |
+---------+------------------+
| age | i16 |
+---------+------------------+

Union

A union is a special data structure that can only contain one field’s value. It is similar to unions in the C language and is suitable for scenarios where memory needs to be saved.

Graphical Example

1
2
3
4
5
6
7
8
9
+----------------------------+
| ColorUnion |
+---------+------------------+
| RED | 0 |
+---------+------------------+
| GREEN | 1 |
+---------+------------------+
| BLUE | 2 |
+---------+------------------+

Enum

An enum is used to define a group of named integer constants. For example:

1
2
3
4
5
enum Color {
RED = 0,
GREEN = 1,
BLUE = 2
}

Graphical Example

1
2
3
4
5
6
7
8
9
+----------------------------+
| ColorEnum |
+---------+------------------+
| RED | 0 |
+---------+------------------+
| GREEN | 1 |
+---------+------------------+
| BLUE | 2 |
+---------+------------------+

Container Types

Thrift supports three container types:

  • list: Ordered collection of elements.
  • set: Unordered collection of unique elements.
  • map: Collection of key-value pairs.

For example:

1
2
3
4
5
struct Example {
1: list<string> names,
2: set<i32> ids,
3: map<string, i32> scores
}

Graphical Example

1
2
3
4
5
6
7
8
9
+---------------------------------------------------+
| Example |
+----------------+----------------------------------+
| names | ["Alice", "Bob"] |
+----------------+----------------------------------+
| ids | {1001, 1002} |
+----------------+----------------------------------+
| scores | {"Math": 90, "English": 85} |
+----------------+----------------------------------+

Service Definition

Thrift allows you to define service interfaces that can be called by clients. A service interface definition looks like this:

1
2
3
service MyService {
string sayHello(1: string name)
}

Examples

Below is a complete example of a Thrift IDL file:

1
2
3
4
5
6
7
8
9
10
11
namespace cpp example

struct Person {
1: i32 id,
2: string name,
3: i16 age
}

service PersonService {
Person getPerson(1: i32 id)
}

Protocol Advantages and Use Cases

Protocol Advantages

Thrift protocol has several notable advantages:

  1. Cross-Language Support: Thrift supports multiple programming languages, allowing seamless communication between services written in different languages.
  2. High Performance: Thrift uses binary encoding, which is more efficient than JSON and XML, making it suitable for high-concurrency, low-latency scenarios.
  3. Code Generation: Thrift provides a powerful code generation tool that can automatically generate client and server-side code from IDL, reducing repetitive development work.
  4. Flexibility: Thrift supports various transport methods (e.g., TCP, HTTP) and serialization protocols (e.g., Binary, Compact), allowing flexible choices based on requirements.
  5. Good Extensibility: The design of Thrift allows adding new fields or methods in the future without affecting the compatibility of existing services.

Use Cases

Thrift is widely used in distributed systems, with common use cases including:

  1. Microservices Architecture: Thrift can serve as the communication protocol between services, helping to build efficient microservices systems.
  2. Big Data Processing: Thrift is often used in big data platforms to define data structures and communication protocols.
  3. Cross-Platform Communication: When systems need to communicate between components written in different languages, Thrift provides a unified solution.
  4. Remote Procedure Call (RPC): Thrift has built-in support for RPC, making it ideal for building remote call services.

Practical Application Example

Suppose we have a user management system that includes a Thrift-based service for retrieving user information:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// user.thrift
namespace cpp user

struct User {
1: i32 id,
2: string name,
3: string email,
4: i16 age
}

service UserService {
User getUser(1: i32 id),
list<User> getAllUsers()
}

In this example, UserService provides two methods: getUser, which retrieves a single user’s information based on their ID, and getAllUsers, which retrieves a list of all users. Clients can invoke these methods through the Thrift library and automatically handle the underlying serialization and network communication.

The power of Thrift lies in its ability to abstract away complex communication logic, allowing developers to focus on implementing business logic.

Official Documentation

You can visit the Apache Thrift official documentation to get more detailed information about the Thrift protocol, including installation guides, usage tutorials, and API references.


Thrift Protocol Documentation
https://www.chiullson.com/2025/06/19/thrift-protocol.en/
Author
Rev Chen
Posted on
June 19, 2025
Licensed under